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