{"id":13399094,"url":"https://github.com/sipcapture/hep-erlang","last_synced_at":"2025-07-10T11:32:42.126Z","repository":{"id":18800905,"uuid":"22015007","full_name":"sipcapture/hep-erlang","owner":"sipcapture","description":"HEP: Erlang implementation of HEP/EEP Encapsulation Protocol","archived":false,"fork":false,"pushed_at":"2015-05-28T21:59:09.000Z","size":135,"stargazers_count":5,"open_issues_count":0,"forks_count":9,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-07-31T19:18:01.428Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://sipcapture.org","language":"Erlang","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sipcapture.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-07-19T17:21:47.000Z","updated_at":"2022-08-25T17:05:04.000Z","dependencies_parsed_at":"2022-09-25T02:30:24.186Z","dependency_job_id":null,"html_url":"https://github.com/sipcapture/hep-erlang","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sipcapture%2Fhep-erlang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sipcapture%2Fhep-erlang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sipcapture%2Fhep-erlang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sipcapture%2Fhep-erlang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sipcapture","download_url":"https://codeload.github.com/sipcapture/hep-erlang/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225636898,"owners_count":17500358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T19:00:34.085Z","updated_at":"2024-11-20T21:55:42.503Z","avatar_url":"https://github.com/sipcapture.png","language":"Erlang","funding_links":[],"categories":["Contribution Guidelines"],"sub_categories":["Libraries and Code Examples"],"readme":"hep-erlang\n==========\n\nAn Erlang implementation of HEP (Homer Encapsulation Protocol).\n\n**WARNING**\n\nThis project is currently in the incubator of\n[Pannonia Technologies](http://www.pannonia-technologies.com), so there maybe\na lot of changes in how this software works or it might not even work at all.\nThere might be terrible inconsistencies in or a complete lack of documentation.\nSo you are warned to use this software at your own risk!\n\nIf you'd like to contribute, don't ask, just do it. That's one reason we are\nhere on GitHub.\n\nGoals\n-----\n\nHEP was designed by the developers of the\n[Homer SIP Capture Server](http://www.sipcapture.org) solution. HEP is used to\ntransport metadata and SIP messages from a SIP proxy or SIP user agent to a\ncapture server. HEP is not limited to transport SIP messages, but before\nversion 3 of the protocol, the payload could not be distinguished by the\nmetadata, so transporting anything else than SIP before Version 3 is rather\nimpractical when conveyed through the same channel. A few major Open Source\nSIP-related projects, like [FreeSWITCH](http://www.freeswitch.org),\n[Kamailio](http://www.kamailio.org) and [OpenSIPS](http://www.opensips.org)\nintegrated HEP natively, so this is why this project exists and we also wanted\nto be able to capture and/or send HEP messages from Erlang. HEP can use any\nkind of transport channel, but most of the time UDP is used.\n\n\nUsage\n-----\n\nVery basic example:\n\n```erlang\n\n-module(naive_udp_hep_listener).\n\n-export([start/1, stop/1]).\n\nstart(Port) -\u003e\n    ListenerPid = spawn(fun() -\u003e\n        {ok, Socket} = gen_udp:open(Port, [binary, {active, true}]),\n        Loop = fun(Fun) -\u003e\n            receive\n                {udp, _, _, _, Message} -\u003e\n                    {ok, Hep} = hep_multi_parser:parse(Message),\n                    HepMsg = hep_transform:transform(Hep),\n                    error_logger:info_msg(\"~p~n\", [HepMsg]),\n                    Fun(Fun);\n                stop -\u003e\n                    gen_udp:close(Socket);\n                _ -\u003e\n                    Fun(Fun)\n            end\n        end,\n        Loop(Loop)\n    end),\n    {ok, ListenerPid}.\n\nstop(ListenerPid) -\u003e\n    ListenerPid ! stop.\n\n```\n\nProtocol Version 1\n------------------\n\nAll integer fields are stored in network byte order.\n\n| Name                | Length   | Description                                                                         |\n|---------------------|----------|-------------------------------------------------------------------------------------|\n| Version             |  8 bits  | HEP version, always 1 for this version.                                             |\n| Length              |  8 bits  | Length of the HEP header, including Version and Length field and excluding payload. |\n| Protocol Family     |  8 bits  | Protocol Family PF_INET, PF_INET6 (2 = IPv4, 10 = IPv6).                            |\n| Protocol            |  8 bits  | UDP, TCP, TLS, SCTP, etc..                                                          |\n| Source Port         | 16 bits  | Source Port of the captured packet in payload.                                      |\n| Destination Port    | 16 bits  | Destination Port of the captured packet in payload.                                 |\n| Source Address      | *1       | Source IP of the captured packet in payload.                                        |\n| Destination Address | *1       | Destination IP of the captured packet in payload.                                   |\n| Payload             | *2       | Payload (usually SIP message)                                                       |\n\n*1) Length is 32 bits for IPv4 and 128 bits for IPv6.\n\n*2) Variable length not defined by metadata, so this protocol is really only well suited for UDP.\n\nProtocol Version 2\n------------------\n\nAll integer fields are stored in network byte order.\n\n| Name                | Length   | Description                                                                         |\n|---------------------|----------|-------------------------------------------------------------------------------------|\n| Version             |  8 bits  | HEP version, always 2 for this version.                                             |\n| Length              |  8 bits  | Length of the HEP header, including Version and Length field and excluding payload. |\n| Protocol Family     |  8 bits  | Protocol Family PF_INET, PF_INET6 (2 = IPv4, 10 = IPv6).                            |\n| Protocol            |  8 bits  | UDP, TCP, TLS, SCTP, etc..                                                          |\n| Source Port         | 16 bits  | Source Port of the captured packet in payload.                                      |\n| Destination Port    | 16 bits  | Destination Port of the captured packet in payload.                                 |\n| Source Address      | *1       | Source IP of the captured packet in payload.                                        |\n| Destination Address | *1       | Destination IP of the captured packet in payload.                                   |\n| Seconds             | 32 bits  | The timestamp in seconds since the Epoch when the included payload was captured.    |\n| Microseconds        | 32 bits  | The microseconds part of the timestamp.                                             |\n| Capture ID of node  | 16 bits  | A capture ID of the node. XXX: What does this exactly mean???                       |\n| *unused*            | 16 bits  | *unused*                                                                            |\n| Payload             | *2       | Payload (usually SIP message)                                                       |\n\n*1) Length is 32 bits for IPv4 and 128 bits for IPv6.\n\n*2) Variable length not defined by metadata, so this protocol is really only well suited for UDP.\n\nProtocol Version 3\n------------------\n\nEach packet in HEP version 3 starts with a header:\n\n| Name                | Length   | Description                                                                      |\n|---------------------|----------|----------------------------------------------------------------------------------|\n| Protocol Identifier | 4 bytes  | Always contains \"HEP3\" for this version.                                         |\n| Total Length        | 2 bytes  | The total length of this packet, including Protocol Identifier and Total Length. |\n| Chunks              | variable | The payload as chunks, with a length of \"Total Length\" minus 6.                  |\n\nAll data is encapsulated in chunks:\n\n| Name          | Length   | Description                                                       |\n|---------------|----------|-------------------------------------------------------------------|\n| Vendor ID     | 2 bytes  | Vendor Namespace of this chunk.                                   |\n| Chunk ID      | 2 bytes  | Vendor specific chunk id.                                         |\n| Chunk Length  | 2 bytes  | The total length of this chunk, including Vendor ID and Chunk ID. |\n| Chunk Payload | variable | The payload of the chunk, with a length of \"Chunk Length minus 6. |\n\nThe following chunk data types are defined:\n\n| Type         | Description                                          |\n|--------------|------------------------------------------------------|\n| octet-string | Arbitrary octet string (\"byte array\").               |\n| utf8-string  | UTF-8 encoded character sequence.                    |\n| uint8        | 8 bit unsigned integer.                              |\n| uint16       | 16 bit unsigned integer in network byte order.       |\n| uint32       | 32 bit unsigned integer in network byte order.       |\n| inet4-addr   | 4 octet IPv4 address, most significant octet first.  |\n| inet6-addr   | 16 octet IPv6 address, most significant octet first. |\n\n\nThe following Vendor IDs are assigned:\n\n| Vendor ID | Assigned Vendor                 |\n|-----------|---------------------------------|\n| 16#0000   | Generic chunk types, see below. |\n| 16#0001   | FreeSWITCH                      |\n| 16#0002   | Kamailio                        |\n| 16#0003   | OpenSIPS                        |\n| 16#0004   | Asterisk                        |\n| 16#0005   | Homer Project                   |\n| 16#0006   | SipXecs                         |\n\nGeneric chunk types:\n\n| Chunk ID | Type         | Description                          |\n|----------|--------------|--------------------------------------|\n| 16#0001  | uint8        | IP protocol family                   |\n| 16#0002  | uint8        | IP protocol id                       |\n| 16#0003  | inet4-addr   | IPv4 source address                  |\n| 16#0004  | inet4-addr   | IPv4 destination address             |\n| 16#0005  | inet6-addr   | IPv6 source address                  |\n| 16#0006  | inet6-addr   | IPv6 destination address             |\n| 16#0007  | uint16       | Protocol source port                 |\n| 16#0008  | uint16       | Protocol destination port            |\n| 16#0009  | uint32       | Timestamp in seconds since the Epoch |\n| 16#000a  | uint32       | Microseconds part of timestamp       |\n| 16#000b  | uint8        | Protocol type (see table below)      |\n| 16#000c  | uint32       | Capture agent id                     |\n| 16#000d  | uint16       | keep alive time in seconds           |\n| 16#000e  | octet-string | Authenticate key                     |\n| 16#000f  | octet-string | captured packet payload              |\n\nProtocol types:\n\n| Type ID | Description        |\n|---------|--------------------|\n| 16#00   | reserved           |\n| 16#01   | SIP                |\n| 16#02   | H.323              |\n| 16#03   | SDP                |\n| 16#04   | RTP                |\n| 16#05   | RTCP               |\n| 16#06   | MGCP               |\n| 16#07   | MEGACO / H.248     |\n| 16#08   | M2UA (SS7/SIGTRAN) |\n| 16#09   | M3UA (SS7/SIGTRAN) |\n| 16#10   | IAX                |\n\nJSON representation\n-------------------\n\n```json\n[\n    {\n        \"type\": \"HEP\",\n        \"version\": 1,\n        \"protocolFamily\": 2,\n        \"protocol\": 17,\n        \"srcIp\": \"192.168.3.11\",\n        \"srcPort\": 5060,\n        \"dstIp\": \"192.168.3.190\",\n        \"dstPort\": 2048,\n        \"timestamp\": \"2013-10-29T15:25:53.567Z\",\n        \"timestampUSecs\": 123,\n        \"captureId\": null,\n        \"vendorChunks\": [],\n        \"payload\": {\n            \"type\": \"SIP\",\n            \"data\": \"INVITE sip:100@pantech.intern SIP/2.0\\r\\n...\"\n        }\n    },\n    {\n        \"type\": \"HEP\",\n        \"version\": 2,\n        \"protocolFamily\": 2,\n        \"protocol\": 17,\n        \"srcIp\": \"192.168.3.12\",\n        \"srcPort\": 5060,\n        \"dstIp\": \"192.168.3.11\",\n        \"dstPort\": 5060,\n        \"timestamp\": \"2013-10-29T15:25:53:577Z\",\n        \"timestampUSecs\": 0,\n        \"captureId\": 241,\n        \"vendorChunks\": [],\n        \"payload\": {\n            \"type\": \"SIP\",\n            \"data\": \"INVITE sip:100@pantech.intern SIP/2.0\\r\\n...\"\n        }\n    }\n]\n```\n\nOther Software Supporting HEP\n-----------------------------\n\nThis is third-party software also supporting HEP.\n\n| Name                                            | HEP Versions Supported | Client | Server |\n|-------------------------------------------------|------------------------|--------|--------|\n| [captagent](http://code.google.com/p/captagent) | 1, 2, 3                | yes    | no     |\n| [FreeSWITCH](http://www.freeswitch.org)         | 1                      | yes    | no     |\n| [Kamailio](http://www.kamailio.org)             | 1, 2                   | yes    | yes    |\n| [OpenSIPS](http://www.opensips.org)             | 1, 2                   | yes    | yes    |\n\nContributors\n------------\n\n- [Matthias Endler](https://github.com/matthias-endler)\n\nLicense\n-------\n\nThis project is licensed under the ISC License. See [LICENSE](LICENSE) for details.\n\n---\n\nCopyright \u0026#169; 2013 Matthias Endler. All rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsipcapture%2Fhep-erlang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsipcapture%2Fhep-erlang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsipcapture%2Fhep-erlang/lists"}