Create "username" and "password" DHCP options, ready for placing this
[people/xl0/gpxe.git] / src / include / gpxe / dhcp.h
1 #ifndef _GPXE_DHCP_H
2 #define _GPXE_DHCP_H
3
4 /** @file
5  *
6  * Dynamic Host Configuration Protocol
7  *
8  */
9
10 #include <stdint.h>
11 #include <gpxe/list.h>
12 #include <gpxe/in.h>
13 #include <gpxe/udp.h>
14 #include <gpxe/async.h>
15 #include <gpxe/retry.h>
16
17 /** BOOTP/DHCP server port */
18 #define BOOTPS_PORT 67
19
20 /** BOOTP/DHCP client port */
21 #define BOOTPC_PORT 68
22
23 /** Construct a tag value for an encapsulated option
24  *
25  * This tag value can be passed to Etherboot functions when searching
26  * for DHCP options in order to search for a tag within an
27  * encapsulated options block.
28  */
29 #define DHCP_ENCAP_OPT( encapsulator, encapsulated ) \
30         ( ( (encapsulator) << 8 ) | (encapsulated) )
31 /** Extract encapsulating option block tag from encapsulated tag value */
32 #define DHCP_ENCAPSULATOR( encap_opt ) ( (encap_opt) >> 8 )
33 /** Extract encapsulated option tag from encapsulated tag value */
34 #define DHCP_ENCAPSULATED( encap_opt ) ( (encap_opt) & 0xff )
35 /** Option is encapsulated */
36 #define DHCP_IS_ENCAP_OPT( opt ) DHCP_ENCAPSULATOR( opt )
37
38 /**
39  * @defgroup dhcpopts DHCP option tags
40  * @{
41  */
42
43 /** Padding
44  *
45  * This tag does not have a length field; it is always only a single
46  * byte in length.
47  */
48 #define DHCP_PAD 0
49
50 /** Minimum normal DHCP option */
51 #define DHCP_MIN_OPTION 1
52
53 /** Subnet mask */
54 #define DHCP_SUBNET_MASK 1
55
56 /** Routers */
57 #define DHCP_ROUTERS 3
58
59 /** DNS servers */
60 #define DHCP_DNS_SERVERS 6
61
62 /** Host name */
63 #define DHCP_HOST_NAME 12
64
65 /** Domain name */
66 #define DHCP_DOMAIN_NAME 15
67
68 /** Root path */
69 #define DHCP_ROOT_PATH 17
70
71 /** Vendor encapsulated options */
72 #define DHCP_VENDOR_ENCAP 43
73
74 /** Requested IP address */
75 #define DHCP_REQUESTED_ADDRESS 50
76
77 /** Lease time */
78 #define DHCP_LEASE_TIME 51
79
80 /** Option overloading
81  *
82  * The value of this option is the bitwise-OR of zero or more
83  * DHCP_OPTION_OVERLOAD_XXX constants.
84  */
85 #define DHCP_OPTION_OVERLOAD 52
86
87 /** The "file" field is overloaded to contain extra DHCP options */
88 #define DHCP_OPTION_OVERLOAD_FILE 1
89
90 /** The "sname" field is overloaded to contain extra DHCP options */
91 #define DHCP_OPTION_OVERLOAD_SNAME 2
92
93 /** DHCP message type */
94 #define DHCP_MESSAGE_TYPE 53
95 #define DHCPDISCOVER 1
96 #define DHCPOFFER 2
97 #define DHCPREQUEST 3
98 #define DHCPDECLINE 4
99 #define DHCPACK 5
100 #define DHCPNAK 6
101 #define DHCPRELEASE 7
102 #define DHCPINFORM 8
103
104 /** DHCP server identifier */
105 #define DHCP_SERVER_IDENTIFIER 54
106
107 /** Parameter request list */
108 #define DHCP_PARAMETER_REQUEST_LIST 55
109
110 /** Maximum DHCP message size */
111 #define DHCP_MAX_MESSAGE_SIZE 57
112
113 /** Vendor class identifier */
114 #define DHCP_VENDOR_CLASS_ID 60
115
116 /** TFTP server name
117  *
118  * This option replaces the fixed "sname" field, when that field is
119  * used to contain overloaded options.
120  */
121 #define DHCP_TFTP_SERVER_NAME 66
122
123 /** Bootfile name
124  *
125  * This option replaces the fixed "file" field, when that field is
126  * used to contain overloaded options.
127  */
128 #define DHCP_BOOTFILE_NAME 67
129
130 /** Etherboot-specific encapsulated options
131  *
132  * This encapsulated options field is used to contain all options
133  * specific to Etherboot (i.e. not assigned by IANA or other standards
134  * bodies).
135  */
136 #define DHCP_EB_ENCAP 175
137
138 /** Priority of this options block
139  *
140  * This is a signed 8-bit integer field indicating the priority of
141  * this block of options.  It can be used to specify the relative
142  * priority of multiple option blocks (e.g. options from non-volatile
143  * storage versus options from a DHCP server).
144  */
145 #define DHCP_EB_PRIORITY DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 1 )
146
147 /** "Your" IP address
148  *
149  * This option is used internally to contain the value of the "yiaddr"
150  * field, in order to provide a consistent approach to storing and
151  * processing options.  It should never be present in a DHCP packet.
152  */
153 #define DHCP_EB_YIADDR DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 2 )
154
155 /** "Server" IP address
156  *
157  * This option is used internally to contain the value of the "siaddr"
158  * field, in order to provide a consistent approach to storing and
159  * processing options.  It should never be present in a DHCP packet.
160  */
161 #define DHCP_EB_SIADDR DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 3 )
162
163 /** BIOS drive number
164  *
165  * This is the drive number for a drive emulated via INT 13.  0x80 is
166  * the first hard disk, 0x81 is the second hard disk, etc.
167  */
168 #define DHCP_EB_BIOS_DRIVE DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbd )
169
170 /** Username
171  *
172  * This will be used as the username for any required authentication.
173  * It is expected that this option's value will be held in
174  * non-volatile storage, rather than transmitted as part of a DHCP
175  * packet.
176  */
177 #define DHCP_EB_USERNAME DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbe )
178
179 /** Password
180  *
181  * This will be used as the password for any required authentication.
182  * It is expected that this option's value will be held in
183  * non-volatile storage, rather than transmitted as part of a DHCP
184  * packet.
185  */
186 #define DHCP_EB_PASSWORD DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbf )
187
188 /** Maximum normal DHCP option */
189 #define DHCP_MAX_OPTION 254
190
191 /** End of options
192  *
193  * This tag does not have a length field; it is always only a single
194  * byte in length.
195  */
196 #define DHCP_END 255
197
198 /** @} */
199
200 /**
201  * Count number of arguments to a variadic macro
202  *
203  * This rather neat, non-iterative solution is courtesy of Laurent
204  * Deniau.
205  *
206  */
207 #define _VA_ARG_COUNT(  _1,  _2,  _3,  _4,  _5,  _6,  _7,  _8,          \
208                         _9, _10, _11, _12, _13, _14, _15, _16,          \
209                        _17, _18, _19, _20, _21, _22, _23, _24,          \
210                        _25, _26, _27, _28, _29, _30, _31, _32,          \
211                        _33, _34, _35, _36, _37, _38, _39, _40,          \
212                        _41, _42, _43, _44, _45, _46, _47, _48,          \
213                        _49, _50, _51, _52, _53, _54, _55, _56,          \
214                        _57, _58, _59, _60, _61, _62, _63,   N, ... ) N
215 #define VA_ARG_COUNT( ... )                                             \
216         _VA_ARG_COUNT ( __VA_ARGS__,                                    \
217                         63, 62, 61, 60, 59, 58, 57, 56,                 \
218                         55, 54, 53, 52, 51, 50, 49, 48,                 \
219                         47, 46, 45, 44, 43, 42, 41, 40,                 \
220                         39, 38, 37, 36, 35, 34, 33, 32,                 \
221                         31, 30, 29, 28, 27, 26, 25, 24,                 \
222                         23, 22, 21, 20, 19, 18, 17, 16,                 \
223                         15, 14, 13, 12, 11, 10,  9,  8,                 \
224                          7,  6,  5,  4,  3,  2,  1,  0 )
225
226 /** Construct a DHCP option from a list of bytes */
227 #define DHCP_OPTION( ... ) VA_ARG_COUNT ( __VA_ARGS__ ), __VA_ARGS__
228
229 /** Construct a DHCP option from a list of characters */
230 #define DHCP_STRING( ... ) DHCP_OPTION ( __VA_ARGS__ )
231
232 /** Construct a byte-valued DHCP option */
233 #define DHCP_BYTE( value ) DHCP_OPTION ( value )
234
235 /** Construct a word-valued DHCP option */
236 #define DHCP_WORD( value ) DHCP_OPTION ( ( ( (value) >> 8 ) & 0xff ),   \
237                                          ( ( (value) >> 0  ) & 0xff ) )
238
239 /** Construct a dword-valued DHCP option */
240 #define DHCP_DWORD( value ) DHCP_OPTION ( ( ( (value) >> 24 ) & 0xff ), \
241                                           ( ( (value) >> 16 ) & 0xff ), \
242                                           ( ( (value) >> 8  ) & 0xff ), \
243                                           ( ( (value) >> 0  ) & 0xff ) )
244
245 /** Construct a DHCP encapsulated options field */
246 #define DHCP_ENCAP( ... ) DHCP_OPTION ( __VA_ARGS__, DHCP_END )
247
248 /**
249  * A DHCP option
250  *
251  * DHCP options consist of a mandatory tag, a length field that is
252  * mandatory for all options except @c DHCP_PAD and @c DHCP_END, and a
253  * payload.  
254  */
255 struct dhcp_option {
256         /** Tag
257          *
258          * Must be a @c DHCP_XXX value.
259          */
260         uint8_t tag;
261         /** Length
262          *
263          * This is the length of the data field (i.e. excluding the
264          * tag and length fields).  For the two tags @c DHCP_PAD and
265          * @c DHCP_END, the length field is implicitly zero and is
266          * also missing, i.e. these DHCP options are only a single
267          * byte in length.
268          */
269         uint8_t len;
270         /** Option data
271          *
272          * Interpretation of the content is entirely dependent upon
273          * the tag.  For fields containing a multi-byte integer, the
274          * field is defined to be in network-endian order (unless you
275          * are Intel and feel like violating the spec for fun).
276          */
277         union {
278                 uint8_t byte;
279                 uint16_t word;
280                 uint32_t dword;
281                 struct in_addr in;
282                 uint8_t bytes[0];
283                 char string[0];
284         } data;
285 } __attribute__ (( packed ));
286
287 /**
288  * Length of a DHCP option header
289  *
290  * The header is the portion excluding the data, i.e. the tag and the
291  * length.
292  */
293 #define DHCP_OPTION_HEADER_LEN ( offsetof ( struct dhcp_option, data ) )
294
295 /** Maximum length for a single DHCP option */
296 #define DHCP_MAX_LEN 0xff
297
298 /** A DHCP options block */
299 struct dhcp_option_block {
300         /** List of option blocks */
301         struct list_head list;
302         /** Option block raw data */
303         void *data;
304         /** Option block length */
305         size_t len;
306         /** Option block maximum length */
307         size_t max_len;
308         /** Block priority
309          *
310          * This is determined at the time of the call to
311          * register_options() by searching for the @c DHCP_EB_PRIORITY
312          * option.
313          */
314         signed int priority;
315 };
316
317 /**
318  * A DHCP header
319  *
320  */
321 struct dhcphdr {
322         /** Operation
323          *
324          * This must be either @c BOOTP_REQUEST or @c BOOTP_REPLY.
325          */
326         uint8_t op;
327         /** Hardware address type
328          *
329          * This is an ARPHRD_XXX constant.  Note that ARPHRD_XXX
330          * constants are nominally 16 bits wide; this could be
331          * considered to be a bug in the BOOTP/DHCP specification.
332          */
333         uint8_t htype;
334         /** Hardware address length */
335         uint8_t hlen;
336         /** Number of hops from server */
337         uint8_t hops;
338         /** Transaction ID */
339         uint32_t xid;
340         /** Seconds since start of acquisition */
341         uint16_t secs;
342         /** Flags */
343         uint16_t flags;
344         /** "Client" IP address
345          *
346          * This is filled in if the client already has an IP address
347          * assigned and can respond to ARP requests.
348          */
349         struct in_addr ciaddr;
350         /** "Your" IP address
351          *
352          * This is the IP address assigned by the server to the client.
353          */
354         struct in_addr yiaddr;
355         /** "Server" IP address
356          *
357          * This is the IP address of the next server to be used in the
358          * boot process.
359          */
360         struct in_addr siaddr;
361         /** "Gateway" IP address
362          *
363          * This is the IP address of the DHCP relay agent, if any.
364          */
365         struct in_addr giaddr;
366         /** Client hardware address */
367         uint8_t chaddr[16];
368         /** Server host name (null terminated)
369          *
370          * This field may be overridden and contain DHCP options
371          */
372         uint8_t sname[64];
373         /** Boot file name (null terminated)
374          *
375          * This field may be overridden and contain DHCP options
376          */
377         uint8_t file[128];
378         /** DHCP magic cookie
379          *
380          * Must have the value @c DHCP_MAGIC_COOKIE.
381          */
382         uint32_t magic;
383         /** DHCP options
384          *
385          * Variable length; extends to the end of the packet.  Minimum
386          * length (for the sake of sanity) is 1, to allow for a single
387          * @c DHCP_END tag.
388          */
389         uint8_t options[1];
390 };
391
392 /** Opcode for a request from client to server */
393 #define BOOTP_REQUEST 1
394
395 /** Opcode for a reply from server to client */
396 #define BOOTP_REPLY 2
397
398 /** DHCP magic cookie */
399 #define DHCP_MAGIC_COOKIE 0x63825363UL
400
401 /** DHCP packet option block fill order
402  *
403  * This is the order in which option blocks are filled when
404  * reassembling a DHCP packet.  We fill the smallest field ("sname")
405  * first, to maximise the chances of being able to fit large options
406  * within fields which are large enough to contain them.
407  */
408 enum dhcp_packet_option_block_fill_order {
409         OPTS_SNAME = 0,
410         OPTS_FILE,
411         OPTS_MAIN,
412         NUM_OPT_BLOCKS
413 };
414
415 /**
416  * A DHCP packet
417  *
418  */
419 struct dhcp_packet {
420         /** The DHCP packet contents */
421         struct dhcphdr *dhcphdr;
422         /** Maximum length of the DHCP packet buffer */
423         size_t max_len;
424         /** Used length of the DHCP packet buffer */
425         size_t len;
426         /** DHCP option blocks within a DHCP packet
427          *
428          * A DHCP packet contains three fields which can be used to
429          * contain options: the actual "options" field plus the "file"
430          * and "sname" fields (which can be overloaded to contain
431          * options).
432          */
433         struct dhcp_option_block options[NUM_OPT_BLOCKS];
434 };
435
436 /** A DHCP session */
437 struct dhcp_session {
438         /** UDP connection for this session */
439         struct udp_connection udp;
440
441         /** Network device being configured */
442         struct net_device *netdev;
443
444         /** Options obtained from server */
445         struct dhcp_option_block *options;
446
447         /** State of the session
448          *
449          * This is a value for the @c DHCP_MESSAGE_TYPE option
450          * (e.g. @c DHCPDISCOVER).
451          */
452         int state;
453         /** Asynchronous operation for this DHCP session */
454         struct async_operation aop;
455         /** Retransmission timer */
456         struct retry_timer timer;
457 };
458
459 extern unsigned long dhcp_num_option ( struct dhcp_option *option );
460 extern void dhcp_ipv4_option ( struct dhcp_option *option,
461                                struct in_addr *inp );
462 extern int dhcp_snprintf ( char *buf, size_t size,
463                            struct dhcp_option *option );
464 extern struct dhcp_option *
465 find_dhcp_option ( struct dhcp_option_block *options, unsigned int tag );
466 extern void register_dhcp_options ( struct dhcp_option_block *options );
467 extern void unregister_dhcp_options ( struct dhcp_option_block *options );
468 extern void init_dhcp_options ( struct dhcp_option_block *options,
469                                 void *data, size_t max_len );
470 extern struct dhcp_option_block * alloc_dhcp_options ( size_t max_len );
471 extern void free_dhcp_options ( struct dhcp_option_block *options );
472 extern struct dhcp_option *
473 set_dhcp_option ( struct dhcp_option_block *options, unsigned int tag,
474                   const void *data, size_t len );
475 extern struct dhcp_option * find_global_dhcp_option ( unsigned int tag );
476 extern unsigned long find_dhcp_num_option ( struct dhcp_option_block *options,
477                                             unsigned int tag );
478 extern unsigned long find_global_dhcp_num_option ( unsigned int tag );
479 extern void find_dhcp_ipv4_option ( struct dhcp_option_block *options,
480                                     unsigned int tag, struct in_addr *inp );
481 extern void find_global_dhcp_ipv4_option ( unsigned int tag,
482                                            struct in_addr *inp );
483 extern void delete_dhcp_option ( struct dhcp_option_block *options,
484                                  unsigned int tag );
485
486 extern struct dhcp_option_block dhcp_request_options;
487 extern int create_dhcp_packet ( struct net_device *netdev, uint8_t msgtype,
488                                 void *data, size_t max_len,
489                                 struct dhcp_packet *dhcppkt );
490 extern int copy_dhcp_packet_options ( struct dhcp_packet *dhcppkt,
491                                       struct dhcp_option_block *options );
492 extern struct async_operation * start_dhcp ( struct dhcp_session *dhcp );
493
494 #endif /* _GPXE_DHCP_H */