Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 170 lines (126 sloc) 5.784 kB
94fce13 @msantos Split epcap_net into a new repository and rename
authored
1
2 An Erlang network protocol library.
3
4941f02 @msantos Markdownify README
authored
4 Originally part of epcap:
5 <http://github.com/msantos/epcap>
94fce13 @msantos Split epcap_net into a new repository and rename
authored
6
7
4941f02 @msantos Markdownify README
authored
8 ## EXPORTS
94fce13 @msantos Split epcap_net into a new repository and rename
authored
9
4941f02 @msantos Markdownify README
authored
10 pkt:decapsulate(Data) -> Packet
f7320aa @msantos decapsulate/decode: update README
authored
11 pkt:decapsulate(Proto, Data) -> Packet
a2eb240 @msantos Update README for LLC and VRRP
authored
12
4941f02 @msantos Markdownify README
authored
13 Types Data = binary()
f7320aa @msantos decapsulate/decode: update README
authored
14 Proto = atom() | integer()
15 Packet = [ Header | Payload ]
16 Header = #ether{} | #arp{} | #null{} | #linux_cooked{} |
17 #ipv4{} | #ipv6{} | #tcp{} | #udp{} | #sctp{} | #icmp{} |
cffe0a0 @ates Add '802.1q' to README
ates authored
18 #icmp6{} | #igmp{} | #gre{} | #llc{} | #vrrp{} | #'802.1q'{}
4941f02 @msantos Markdownify README
authored
19 Payload = binary()
94fce13 @msantos Split epcap_net into a new repository and rename
authored
20
f7320aa @msantos decapsulate/decode: update README
authored
21 Convert network protocols from binary data to a list of Erlang
22 records followed by the payload.
23
24 decapsulate/1,2 works on valid packets. If the packet is malformed
25 or unsupported, decapsulate/1 will crash.
26
27 decapsulate/1 parses the data as an ethernet frame.
28
29 decapsulate/2 allows specifying the protocol for decoding the
30 packet. If the protocol is specified as an integer, the integer
31 is treated as a datalink type.
32
33 pkt:decode(Data) -> {ok, Packet} | {error, SoFar, {FailedProto, binary()}}
34 pkt:decode(Proto, Data) -> {ok, Packet} | {error, SoFar, {FailedProto, binary()}}
35
36 Types Data = binary()
37 Proto = FailedProto = atom()
541a573 @msantos decode: represent a packet as a tuple
authored
38 Packet = {Headers, Payload}
39 Headers = [Header]
f7320aa @msantos decapsulate/decode: update README
authored
40 Header = #ether{} | #arp{} | #null{} | #linux_cooked{} |
41 #ipv4{} | #ipv6{} | #tcp{} | #udp{} | #sctp{} | #icmp{} |
cffe0a0 @ates Add '802.1q' to README
ates authored
42 #icmp6{} | #igmp{} | #gre{} | #llc{} | #vrrp{} | #'802.1q'{}
f7320aa @msantos decapsulate/decode: update README
authored
43 SoFar = Headers | []
44 Payload = binary()
45
46 Similar to decapsulate/1 but, on error, returns any part of the
47 packet that has been successfully converted to Erlang term format.
94fce13 @msantos Split epcap_net into a new repository and rename
authored
48
49 The following functions create the protocol headers, converting between
50 records and binaries. See include/pkt.hrl for definition of the record
51 types.
52
4941f02 @msantos Markdownify README
authored
53 ether(Packet) -> {#ether{}, Payload} | binary()
a2eb240 @msantos Update README for LLC and VRRP
authored
54 llc(Packet) -> {#llc{}, Payload} | binary()
55 vrrp(Packet) -> {#vrrp{}, Payload} | binary()
cffe0a0 @ates Add '802.1q' to README
ates authored
56 '802.1q'(Packet) -> {#'802.1q'{}, Payload} | binary()
4941f02 @msantos Markdownify README
authored
57 null(Packet) -> {#null{}, Payload} | binary()
58 linux_cooked(Packet) -> {#linux_cooked{}, Payload} | binary()
f7320aa @msantos decapsulate/decode: update README
authored
59 gre(Packet) -> {#gre{}, Payload} | binary()
4941f02 @msantos Markdownify README
authored
60 arp(Packet) -> {#arp{}, Payload} | binary()
61 ipv4(Packet) -> {#ipv4{}, Payload} | binary()
62 ipv6(Packet) -> {#ipv6{}, Payload} | binary()
63 tcp(Packet) -> {#tcp{}, Payload} | binary()
64 sctp(Packet) -> {#sctp{}, Payload} | binary()
65 udp(Packet) -> {#udp{}, Payload} | binary()
66 icmp(Packet) -> {#icmp{}, Payload} | binary()
7b0ccf4 @msantos Add support for ICMPv6 packets
authored
67 icmp6(Packet) -> {#icmp6{}, Payload} | binary()
747a0a1 @msantos Add test for IGMP and update readme
authored
68 igmp(Packet) -> {#igmp{}, Payload} | binary()
a2eb240 @msantos Update README for LLC and VRRP
authored
69
4941f02 @msantos Markdownify README
authored
70 Types Packet = Header | binary()
71 Header = #ether{} | #null{} | #linux_cooked{} | #arp{} |
7b0ccf4 @msantos Add support for ICMPv6 packets
authored
72 #ipv4{} | #ipv6{} | #tcp{} | #sctp{} | #udp{} |
a2eb240 @msantos Update README for LLC and VRRP
authored
73 #icmp{} | #icmp6{} | #igmp{} | #gre{} | #llc{} |
cffe0a0 @ates Add '802.1q' to README
ates authored
74 #vrrp{} | #'802.1q'{}
a2eb240 @msantos Update README for LLC and VRRP
authored
75
7b0ccf4 @msantos Add support for ICMPv6 packets
authored
76
4941f02 @msantos Markdownify README
authored
77 makesum(Packet) -> integer()
a2eb240 @msantos Update README for LLC and VRRP
authored
78
4941f02 @msantos Markdownify README
authored
79 Types Packet = IPv4_header | [IPv4_header, Header, Payload]
80 IPv4_header = #ipv4{}
81 Header = #tcp{} | #udp{}
82 Payload = binary()
a2eb240 @msantos Update README for LLC and VRRP
authored
83
f7320aa @msantos decapsulate/decode: update README
authored
84 Calculate the one's complement checksum of the packet.
4941f02 @msantos Markdownify README
authored
85
e7101f7 @msantos makesum: use the sum field in the header
authored
86 When computing the checksum, the header sum field must be set
87 to 0:
88
89 Sum = pkt:makesum([IPv4, TCP#tcp{sum = 0}, Payload]).
90
91 For verifcation, the checksum can be compared to the value in
92 the header or:
93
94 0 = pkt:makesum([IPv4, TCP, Payload]).
4941f02 @msantos Markdownify README
authored
95
f7320aa @msantos decapsulate/decode: update README
authored
96 ## EXAMPLES
97
98 * decode an ethernet frame, displaying the source and destination of
99 valid packets
100
101 ```erlang
102 Frame = <<224,105,149,59,163,24,0,22,182,181,62,198,8,0,69,0,0,54,2,108,64,
103 0,53,6,172,243,173,192,82,195,192,168,213,54,0,80,143,166,75,154,
104 212,181,116,33,53,92,128,24,0,126,60,199,0,0,1,1,8,10,92,104,96,
105 16,22,69,237,136,137,0>>,
106
107 try pkt:decapsulate(Frame) of
108 [#ether{}, #ipv4{saddr = Saddr, daddr = Daddr},
109 #tcp{sport = Sport, dport = Dport}, _Payload] ->
110 {{Saddr, Sport}, {Daddr, Dport}}
111 catch
112 error:_ ->
113 ok; % ignore invalid packets
114 end
115 ```
116
117 * verify the TCP checksum of an ethernet frame
118
119 ```erlang
120 {ok, [#ether{}, IPv4, #tcp{sum = Sum} = TCP, Payload]} = pkt:decode(ether, Frame),
121
122 % Re-calculate the checksum and match against the checksum in the header
123 Sum = pkt:makesum([IPv4, TCP#tcp{sum = 0}, Payload]),
124
125 % Or just verify the checksum
126 0 = pkt:makesum([IPv4, TCP, Payload]).
127 ```
128
ad2be68 @msantos readme: note about padding of frames
authored
129 ## PADDING OF ETHERNET FRAMES
130
131 The minimum size of an ethernet payload is 46 bytes. An ethernet frame
132 containing a TCP/IP packet composed of a 20 byte IPv4 header and 20 byte
133 TCP header and payload will be padded by 6 bytes. To calculate the actual
134 length of the packet, use the length and header length values in the IPv4
135 header and the offset value in the TCP header:
136
137 ```erlang
138 [#ether{}, #ipv4{len = Len, hl = HL}, #tcp{off = Off}, Payload] = pkt:decapsulate(Frame),
139 Size = Len - (HL * 4) - (Off * 4),
140 <<Payload:Size/bytes>>.
141 ```
142
4941f02 @msantos Markdownify README
authored
143 ## TODO
94fce13 @msantos Split epcap_net into a new repository and rename
authored
144
538359d @msantos pkt: cleanup
authored
145 * support RFC 2675 (IPv6 Jumbograms)
146
8efc60f @msantos Preliminary support for ICMP6 neighbour discovery
authored
147 * IPv6 AH and ESP
148 * handle alignment differences between IPv4 and IPv6 (IPv4 uses 32
149 bits, IPv6 uses 64 bits)
150
151 * ICMPv6
152 * fix handling of neighbour discovery
153 * simplify ICMPv6 header record and add a record for ICMPv6 type or
154 add functions for ICMPv6 variable length payloads
155
747a0a1 @msantos Add test for IGMP and update readme
authored
156 * IGMP
157 * support IGMPv3 variable payloads
158
8efc60f @msantos Preliminary support for ICMP6 neighbour discovery
authored
159 * merge in DLT\_IEEE802\_11 support from wierl
160
161 * merge in ICMPv6 code from gen_icmp
162
b4cacba @msantos Update docs
authored
163 * DLTs
164 * DLT_SLIP
165 * DLT_PPP
166 * DLT_RAW
167 * DLT\_PPP\_SERIAL
168 * DLT\_PPP\_ETHER
169 * DLT_LOOP
Something went wrong with that request. Please try again.