iPXE
eap.h
Go to the documentation of this file.
1 #ifndef _IPXE_EAP_H
2 #define _IPXE_EAP_H
3 
4 /** @file
5  *
6  * Extensible Authentication Protocol
7  *
8  */
9 
10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
11 
12 #include <stdint.h>
13 #include <ipxe/netdevice.h>
14 #include <ipxe/timer.h>
15 #include <ipxe/tables.h>
16 
17 /** EAP header */
18 struct eap_header {
19  /** Code */
21  /** Identifier */
23  /** Length */
25 } __attribute__ (( packed ));
26 
27 /** EAP request */
28 #define EAP_CODE_REQUEST 1
29 
30 /** EAP response */
31 #define EAP_CODE_RESPONSE 2
32 
33 /** EAP request/response message */
34 struct eap_message {
35  /** Header */
36  struct eap_header hdr;
37  /** Type */
39  /** Type data */
41 } __attribute__ (( packed ));
42 
43 /** EAP "no available types" marker */
44 #define EAP_TYPE_NONE 0
45 
46 /** EAP identity */
47 #define EAP_TYPE_IDENTITY 1
48 
49 /** EAP NAK */
50 #define EAP_TYPE_NAK 3
51 
52 /** EAP MD5 challenge request/response */
53 #define EAP_TYPE_MD5 4
54 
55 /** EAP MD5 challenge request/response type data */
56 struct eap_md5 {
57  /** Value length */
59  /** Value */
61 } __attribute__ (( packed ));
62 
63 /** EAP MS-CHAPv2 request/response */
64 #define EAP_TYPE_MSCHAPV2 26
65 
66 /** EAP MS-CHAPv2 request/response type data */
67 struct eap_mschapv2 {
68  /** Code
69  *
70  * This is in the same namespace as the EAP header's code
71  * field, but is used to extend the handshake by allowing for
72  * "success request" and "success response" packets.
73  */
75  /** Identifier
76  *
77  * This field serves no purposes: it always has the same value
78  * as the EAP header's identifier field (located 5 bytes
79  * earlier in the same packet).
80  */
82  /** Length
83  *
84  * This field serves no purpose: it always has the same value
85  * as the EAP header's length field (located 5 bytes earlier
86  * in the same packet), minus the 5 byte length of the EAP
87  * header.
88  */
90 } __attribute__ (( packed ));
91 
92 /** EAP success */
93 #define EAP_CODE_SUCCESS 3
94 
95 /** EAP failure */
96 #define EAP_CODE_FAILURE 4
97 
98 /** EAP packet */
99 union eap_packet {
100  /** Header */
101  struct eap_header hdr;
102  /** Request/response message */
103  struct eap_message msg;
104 };
105 
106 /** EAP link block timeout
107  *
108  * We mark the link as blocked upon receiving a Request-Identity, on
109  * the basis that this most likely indicates that the switch will not
110  * yet be forwarding packets.
111  *
112  * There is no way to tell how frequently the Request-Identity packet
113  * will be retransmitted by the switch. The default value for Cisco
114  * switches seems to be 30 seconds, so treat the link as blocked for
115  * 45 seconds.
116  */
117 #define EAP_BLOCK_TIMEOUT ( 45 * TICKS_PER_SEC )
118 
119 /** EAP protocol wait timeout
120  *
121  * In the EAP model, the supplicant is a pure responder. The model
122  * also defines no acknowledgement response for the final Success or
123  * Failure "requests". This leaves open the possibility that the
124  * final Success or Failure packet is lost, with the supplicant having
125  * no way to determine the final authentication status.
126  *
127  * Sideband mechanisms such as EAPoL-Start may be used to restart the
128  * entire EAP process, as a (crude) workaround for this protocol flaw.
129  * When expecting to receive a further EAP request (e.g. an
130  * authentication challenge), we may wait for some length of time
131  * before triggering this restart. Choose a duration that is shorter
132  * than the link block timeout, so that there is no period during
133  * which we erroneously leave the link marked as not blocked.
134  */
135 #define EAP_WAIT_TIMEOUT ( EAP_BLOCK_TIMEOUT * 7 / 8 )
136 
137 /** An EAP supplicant */
139  /** Network device */
141  /** Flags */
143  /** ID for current request/response */
145  /** Type for current request/response */
147  /**
148  * Transmit EAP response
149  *
150  * @v supplicant EAP supplicant
151  * @v data Response data
152  * @v len Length of response data
153  * @ret rc Return status code
154  */
155  int ( * tx ) ( struct eap_supplicant *supplicant,
156  const void *data, size_t len );
157 };
158 
159 /** EAP authentication is in progress
160  *
161  * This indicates that we have received an EAP Request-Identity, but
162  * have not yet received a final EAP Success or EAP Failure.
163  */
164 #define EAP_FL_ONGOING 0x0001
165 
166 /** EAP supplicant is passive
167  *
168  * This indicates that the supplicant should not transmit any futher
169  * unsolicited packets (e.g. EAPoL-Start for a supplicant running over
170  * EAPoL). This could be because authentication has already
171  * completed, or because we are relying upon MAC Authentication Bypass
172  * (MAB) which may have a very long timeout.
173  */
174 #define EAP_FL_PASSIVE 0x0002
175 
176 /** An EAP method */
177 struct eap_method {
178  /** Type */
180  /**
181  * Handle EAP request
182  *
183  * @v supplicant EAP supplicant
184  * @v req Request type data
185  * @v req_len Length of request type data
186  * @ret rc Return status code
187  */
188  int ( * rx ) ( struct eap_supplicant *supplicant,
189  const void *req, size_t req_len );
190 };
191 
192 /** EAP method table */
193 #define EAP_METHODS __table ( struct eap_method, "eap_methods" )
194 
195 /** Declare an EAP method */
196 #define __eap_method __table_entry ( EAP_METHODS, 01 )
197 
198 extern int eap_tx_response ( struct eap_supplicant *supplicant,
199  const void *rsp, size_t rsp_len );
200 extern int eap_rx ( struct eap_supplicant *supplicant,
201  const void *data, size_t len );
202 
203 #endif /* _IPXE_EAP_H */
int eap_rx(struct eap_supplicant *supplicant, const void *data, size_t len)
Handle EAP packet.
Definition: eap.c:263
#define __attribute__(x)
Definition: compiler.h:10
EAP MS-CHAPv2 request/response type data.
Definition: eap.h:67
unsigned short uint16_t
Definition: stdint.h:11
uint8_t data[0]
Type data.
Definition: eap.h:40
struct eap_message msg
Request/response message.
Definition: eap.h:103
int eap_tx_response(struct eap_supplicant *supplicant, const void *rsp, size_t rsp_len)
Transmit EAP response.
Definition: eap.c:47
struct eap_header hdr
Header.
Definition: eap.h:101
EAP MD5 challenge request/response type data.
Definition: eap.h:56
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
An EAP supplicant.
Definition: eap.h:138
iPXE timers
EAP request/response message.
Definition: eap.h:34
uint8_t id
ID for current request/response.
Definition: eap.h:144
uint8_t type
Type.
Definition: eap.h:38
uint8_t type
Type.
Definition: eap.h:179
EAP header.
Definition: eap.h:18
EAP packet.
Definition: eap.h:99
struct eap_header hdr
Header.
Definition: eap.h:36
uint8_t code
Code.
Definition: eap.h:74
uint16_t len
Length.
Definition: eap.h:89
uint8_t len
Value length.
Definition: eap.h:58
uint8_t id
Identifier.
Definition: eap.h:22
uint64_t rsp
Definition: librm.h:267
A network device.
Definition: netdevice.h:352
unsigned char uint8_t
Definition: stdint.h:10
int(* rx)(struct eap_supplicant *supplicant, const void *req, size_t req_len)
Handle EAP request.
Definition: eap.h:188
uint16_t len
Length.
Definition: eap.h:24
uint8_t id
Identifier.
Definition: eap.h:81
Network device management.
int(* tx)(struct eap_supplicant *supplicant, const void *data, size_t len)
Transmit EAP response.
Definition: eap.h:155
uint8_t code
Code.
Definition: eap.h:20
uint8_t type
Type for current request/response.
Definition: eap.h:146
uint8_t value[0]
Value.
Definition: eap.h:60
uint8_t data[48]
Additional event data.
Definition: ena.h:22
Linker tables.
struct net_device * netdev
Network device.
Definition: eap.h:140
uint32_t len
Length.
Definition: ena.h:14
uint16_t flags
Flags.
Definition: eap.h:142
An EAP method.
Definition: eap.h:177