Skip to content
Newer
Older
100644 196 lines (122 sloc) 5.45 KB
14979fa @msantos Portable raw socket interface using pcap
authored
1 ewpcap is a native Erlang interface to PCAP that can be used for reading
2 and writing packets from the network.
3
4 ewpcap is an experiment, meant to be a portable raw socket interface to
5 all the platforms that support Erlang and libpcap.
6
7 ## WARNING
8
9 ewpcap was written and tested under Linux. But if you are using a
10 Unix system, it is much safer to use one of these projects:
11
12 * procket : https://github.com/msantos/procket
13
14 * epcap : https://github.com/msantos/epcap
15
16 The ewpcap interface will still go through some changes. For example,
17 the function names may change as may the packet tuple.
18
19 ewpcap hasn't been heavily tested. It will probably segfault.
20
21
22 ## REQUIREMENTS
23
24 * libpcap/winpcap
25
26 On Ubuntu: sudo apt-get install libpcap-dev
27
44bfe79 @msantos Include a reference in packet message
authored
28 These libraries are not required but can be used with ewpcap:
14979fa @msantos Portable raw socket interface using pcap
authored
29
30 * pkt: https://github.com/msantos/pkt.git
31
44bfe79 @msantos Include a reference in packet message
authored
32 Use pkt to decode/encode packets read from the network.
14979fa @msantos Portable raw socket interface using pcap
authored
33
34 * privileges
35
36 ewpcap requires beam to be running with root privileges:
37
38 * using sudo
39
40 sudo erl -smp -pa ebin
41
42 * using capabilities
43
44 setcap cap_net_raw=ep /path/to/beam.smp
45
46 * SMP
47
48 SMP erlang must be enabled (erl -smp -pa ebin).
49
50
51 ## COMPILING
52
53 make
54
55
56 ## EXPORTS
57
58 open() -> {ok, Socket} | {error, Error}
59 open(Dev) -> {ok, Socket} | {error, Error}
60 open(Dev, Options) -> {ok, Socket} | {error, Error}
61
62 Types Dev = binary() | string()
63 Error = enomem | pcap_error_string()
64 Socket = resource()
65 Options = [ Option ]
66 Option = {promisc, boolean()}
67 | {snaplen, integer()}
68 | {to_ms, integer()}
39db696 @msantos Begin receiving packets upon opening the device
authored
69 | {filter, binary() | string()}
70 | FilterOpts
71
72 Open a network interface and begin receiving packets.
14979fa @msantos Portable raw socket interface using pcap
authored
73
74 Dev is the name of the network device. If an empty binary (<<>>)
75 is passed in, pcap will select a default interface.
76
77 If an error occurs, the PCAP string describing the error is
78 returned to the caller.
79
39db696 @msantos Begin receiving packets upon opening the device
authored
80 open/1 and open/2 default to:
14979fa @msantos Portable raw socket interface using pcap
authored
81
82 * promiscuous mode disabled
83
84 * a snaplen (packet length) of 65535 bytes
85
86 * timeout set to 500 ms
87
39db696 @msantos Begin receiving packets upon opening the device
authored
88 * no filter (all packets are received)
14979fa @msantos Portable raw socket interface using pcap
authored
89
39db696 @msantos Begin receiving packets upon opening the device
authored
90 For filter options, see filter/3.
14979fa @msantos Portable raw socket interface using pcap
authored
91
39db696 @msantos Begin receiving packets upon opening the device
authored
92 Packets are returned as messages to the caller:
14979fa @msantos Portable raw socket interface using pcap
authored
93
44bfe79 @msantos Include a reference in packet message
authored
94 {ewpcap, Ref, DatalinkType, Time, Length, Packet}
95
96 Ref is a reference identifying the socket handle.
14979fa @msantos Portable raw socket interface using pcap
authored
97
98 The DataLinkType is an integer representing the link layer,
99 e.g., ethernet, Linux cooked socket.
100
101 The Time is a tuple in the same format as erlang:now/0, {MegaSecs,
102 Secs, MicroSecs}.
103
104 The Length corresponds to the actual packet length on the
105 wire. The captured packet may have been truncated. To get the
106 captured packet length, use byte_size(Packet).
107
108 The Packet is a binary holding the captured data.
109
39db696 @msantos Begin receiving packets upon opening the device
authored
110 close(Socket) -> ok
111
112 Closes the pcap descriptor.
113
114 filter(Socket, Filter) -> ok | {error, Error}
115 filter(Socket, Filter, Options) -> ok | {error, Error}
116
117 Types Socket = resource()
118 Error = enomem | pcap_error_string()
119 Options = [ Option ]
120 Option = {optimize, boolean()}
121 | {netmask, integer()}
122
123 Compile a PCAP filter and apply it to the PCAP descriptor.
124
14979fa @msantos Portable raw socket interface using pcap
authored
125 read(Socket) -> {ok, Packet}
126 read(Socket, Timeout) -> {ok, Packet} | {error, eagain}
127
128 Types Socket = resource()
129 Timeout = uint() | infinity
44bfe79 @msantos Include a reference in packet message
authored
130 Packet = binary()
14979fa @msantos Portable raw socket interface using pcap
authored
131
44bfe79 @msantos Include a reference in packet message
authored
132 Convenience function wrapping receive, returning the packet
133 contents.
14979fa @msantos Portable raw socket interface using pcap
authored
134
135 write(Socket) -> ok | {error, pcap_error_string()}
136
137 Types Socket = resource()
138
139 Write the packet to the network. See pcap_sendpacket(3PCAP).
140
9019c01 @msantos Test for sniffing packets
authored
141 dev() -> {ok, string()} | {error, pcap_error_string()}
142
143 Returns the default device used by PCAP.
144
394cefb @msantos Retrieve a list of interfaces
authored
145 getifaddrs() -> {ok, Iflist} | {error, posix()}
146
147 Types Iflist = [{Ifname, [Ifopt]}]
148 Ifname = string()
149 Ifopt = {flag, [Flag]}
150 | {addr, Addr}
151 | {netmask, Netmask}
152 | {broadaddr, Broadaddr}
153 | {dstaddr, Dstaddr}
154 | {description, string()}
155 Flag = loopback
156 Addr = Netmask = Broadaddr = Dstaddr = ip_address()
157
158 Returns a list of interfaces. Ifname can be used as the first
159 parameter to open/1 and open/2.
160
161 This function is modelled on inet:getifaddrs/0 but uses
162 pcap_findalldevs(3PCAP) to look up the interface attributes:
163
164 * getifaddrs/0 may return pseudo devices, such as the "any"
165 device on Linux
166
167 * getifaddrs/0 will only return the list of devices that
168 can be used with open/1 and open/2. An empty list ({ok,
169 []}) may be returned if the user does not have permission
170 to open any of the system interfaces
14979fa @msantos Portable raw socket interface using pcap
authored
171
172 ## EXAMPLES
173
174 -module(icmp_resend).
175 -export([start/1]).
176
177 % icmp_resend:start("eth0").
178 start(Dev) ->
39db696 @msantos Begin receiving packets upon opening the device
authored
179 {ok, Socket} = ewpcap:open(Dev, [{filter, "icmp"}]),
14979fa @msantos Portable raw socket interface using pcap
authored
180 resend(Socket).
181
182 resend(Socket) ->
394cefb @msantos Retrieve a list of interfaces
authored
183 {ok, Packet} = ewpcap:read(Socket),
14979fa @msantos Portable raw socket interface using pcap
authored
184 ok = ewpcap:write(Socket, Packet),
185 resend(Socket).
186
187 ## TODO
188
44bfe79 @msantos Include a reference in packet message
authored
189 * ewpcap, epcap, epcap\_compile ... confusing!
14979fa @msantos Portable raw socket interface using pcap
authored
190
44bfe79 @msantos Include a reference in packet message
authored
191 * pcap\_sendpacket may block
14979fa @msantos Portable raw socket interface using pcap
authored
192
39db696 @msantos Begin receiving packets upon opening the device
authored
193 * pcap\_findalldevices blocks
194
44bfe79 @msantos Include a reference in packet message
authored
195 * re-write as a port driver?
Something went wrong with that request. Please try again.