xref: /freebsd/contrib/wpa/src/l2_packet/l2_packet.h (revision 3a92d97ff0f22d21608e1c19b83104c4937523b6)
1 /*
2  * WPA Supplicant - Layer2 packet interface definition
3  * Copyright (c) 2003-2005, Jouni Malinen <j@w1.fi>
4  *
5  * This software may be distributed under the terms of the BSD license.
6  * See README for more details.
7  *
8  * This file defines an interface for layer 2 (link layer) packet sending and
9  * receiving. l2_packet_linux.c is one implementation for such a layer 2
10  * implementation using Linux packet sockets and l2_packet_pcap.c another one
11  * using libpcap and libdnet. When porting %wpa_supplicant to other operating
12  * systems, a new l2_packet implementation may need to be added.
13  */
14 
15 #ifndef L2_PACKET_H
16 #define L2_PACKET_H
17 
18 /**
19  * struct l2_packet_data - Internal l2_packet data structure
20  *
21  * This structure is used by the l2_packet implementation to store its private
22  * data. Other files use a pointer to this data when calling the l2_packet
23  * functions, but the contents of this structure should not be used directly
24  * outside l2_packet implementation.
25  */
26 struct l2_packet_data;
27 
28 #ifdef _MSC_VER
29 #pragma pack(push, 1)
30 #endif /* _MSC_VER */
31 
32 struct l2_ethhdr {
33 	u8 h_dest[ETH_ALEN];
34 	u8 h_source[ETH_ALEN];
35 	be16 h_proto;
36 } STRUCT_PACKED;
37 
38 #ifdef _MSC_VER
39 #pragma pack(pop)
40 #endif /* _MSC_VER */
41 
42 /**
43  * l2_packet_init - Initialize l2_packet interface
44  * @ifname: Interface name
45  * @own_addr: Optional own MAC address if available from driver interface or
46  *	%NULL if not available
47  * @protocol: Ethernet protocol number in host byte order
48  * @rx_callback: Callback function that will be called for each received packet
49  * @rx_callback_ctx: Callback data (ctx) for calls to rx_callback()
50  * @l2_hdr: 1 = include layer 2 header, 0 = do not include header
51  * Returns: Pointer to internal data or %NULL on failure
52  *
53  * rx_callback function will be called with src_addr pointing to the source
54  * address (MAC address) of the the packet. If l2_hdr is set to 0, buf
55  * points to len bytes of the payload after the layer 2 header and similarly,
56  * TX buffers start with payload. This behavior can be changed by setting
57  * l2_hdr=1 to include the layer 2 header in the data buffer.
58  */
59 struct l2_packet_data * l2_packet_init(
60 	const char *ifname, const u8 *own_addr, unsigned short protocol,
61 	void (*rx_callback)(void *ctx, const u8 *src_addr,
62 			    const u8 *buf, size_t len),
63 	void *rx_callback_ctx, int l2_hdr);
64 
65 /**
66  * l2_packet_deinit - Deinitialize l2_packet interface
67  * @l2: Pointer to internal l2_packet data from l2_packet_init()
68  */
69 void l2_packet_deinit(struct l2_packet_data *l2);
70 
71 /**
72  * l2_packet_get_own_addr - Get own layer 2 address
73  * @l2: Pointer to internal l2_packet data from l2_packet_init()
74  * @addr: Buffer for the own address (6 bytes)
75  * Returns: 0 on success, -1 on failure
76  */
77 int l2_packet_get_own_addr(struct l2_packet_data *l2, u8 *addr);
78 
79 /**
80  * l2_packet_send - Send a packet
81  * @l2: Pointer to internal l2_packet data from l2_packet_init()
82  * @dst_addr: Destination address for the packet (only used if l2_hdr == 0)
83  * @proto: Protocol/ethertype for the packet in host byte order (only used if
84  * l2_hdr == 0)
85  * @buf: Packet contents to be sent; including layer 2 header if l2_hdr was
86  * set to 1 in l2_packet_init() call. Otherwise, only the payload of the packet
87  * is included.
88  * @len: Length of the buffer (including l2 header only if l2_hdr == 1)
89  * Returns: >=0 on success, <0 on failure
90  */
91 int l2_packet_send(struct l2_packet_data *l2, const u8 *dst_addr, u16 proto,
92 		   const u8 *buf, size_t len);
93 
94 /**
95  * l2_packet_get_ip_addr - Get the current IP address from the interface
96  * @l2: Pointer to internal l2_packet data from l2_packet_init()
97  * @buf: Buffer for the IP address in text format
98  * @len: Maximum buffer length
99  * Returns: 0 on success, -1 on failure
100  *
101  * This function can be used to get the current IP address from the interface
102  * bound to the l2_packet. This is mainly for status information and the IP
103  * address will be stored as an ASCII string. This function is not essential
104  * for %wpa_supplicant operation, so full implementation is not required.
105  * l2_packet implementation will need to define the function, but it can return
106  * -1 if the IP address information is not available.
107  */
108 int l2_packet_get_ip_addr(struct l2_packet_data *l2, char *buf, size_t len);
109 
110 
111 /**
112  * l2_packet_notify_auth_start - Notify l2_packet about start of authentication
113  * @l2: Pointer to internal l2_packet data from l2_packet_init()
114  *
115  * This function is called when authentication is expected to start, e.g., when
116  * association has been completed, in order to prepare l2_packet implementation
117  * for EAPOL frames. This function is used mainly if the l2_packet code needs
118  * to do polling in which case it can increasing polling frequency. This can
119  * also be an empty function if the l2_packet implementation does not benefit
120  * from knowing about the starting authentication.
121  */
122 void l2_packet_notify_auth_start(struct l2_packet_data *l2);
123 
124 #endif /* L2_PACKET_H */
125