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 /** Maximum normal DHCP option */
 171 #define DHCP_MAX_OPTION 254
 172
 173 /** End of options
 174  *
 175  * This tag does not have a length field; it is always only a single
 176  * byte in length.
 177  */
 178 #define DHCP_END 255
 179
 180 /** @} */
 181
 182 /**
 183  * Count number of arguments to a variadic macro
 184  *
 185  * This rather neat, non-iterative solution is courtesy of Laurent
 186  * Deniau.
 187  *
 188  */
 189 #define _VA_ARG_COUNT(  _1,  _2,  _3,  _4,  _5,  _6,  _7,  _8,          \
 190                         _9, _10, _11, _12, _13, _14, _15, _16,          \
 191                        _17, _18, _19, _20, _21, _22, _23, _24,          \
 192                        _25, _26, _27, _28, _29, _30, _31, _32,          \
 193                        _33, _34, _35, _36, _37, _38, _39, _40,          \
 194                        _41, _42, _43, _44, _45, _46, _47, _48,          \
 195                        _49, _50, _51, _52, _53, _54, _55, _56,          \
 196                        _57, _58, _59, _60, _61, _62, _63,   N, ... ) N
 197 #define VA_ARG_COUNT( ... )                                             \
 198         _VA_ARG_COUNT ( __VA_ARGS__,                                    \
 199                         63, 62, 61, 60, 59, 58, 57, 56,                 \
 200                         55, 54, 53, 52, 51, 50, 49, 48,                 \
 201                         47, 46, 45, 44, 43, 42, 41, 40,                 \
 202                         39, 38, 37, 36, 35, 34, 33, 32,                 \
 203                         31, 30, 29, 28, 27, 26, 25, 24,                 \
 204                         23, 22, 21, 20, 19, 18, 17, 16,                 \
 205                         15, 14, 13, 12, 11, 10,  9,  8,                 \
 206                          7,  6,  5,  4,  3,  2,  1,  0 )
 207
 208 /** Construct a DHCP option from a list of bytes */
 209 #define DHCP_OPTION( ... ) VA_ARG_COUNT ( __VA_ARGS__ ), __VA_ARGS__
 210
 211 /** Construct a DHCP option from a list of characters */
 212 #define DHCP_STRING( ... ) DHCP_OPTION ( __VA_ARGS__ )
 213
 214 /** Construct a byte-valued DHCP option */
 215 #define DHCP_BYTE( value ) DHCP_OPTION ( value )
 216
 217 /** Construct a word-valued DHCP option */
 218 #define DHCP_WORD( value ) DHCP_OPTION ( ( ( (value) >> 8 ) & 0xff ),   \
 219                                          ( ( (value) >> 0  ) & 0xff ) )
 220
 221 /** Construct a dword-valued DHCP option */
 222 #define DHCP_DWORD( value ) DHCP_OPTION ( ( ( (value) >> 24 ) & 0xff ), \
 223                                           ( ( (value) >> 16 ) & 0xff ), \
 224                                           ( ( (value) >> 8  ) & 0xff ), \
 225                                           ( ( (value) >> 0  ) & 0xff ) )
 226
 227 /** Construct a DHCP encapsulated options field */
 228 #define DHCP_ENCAP( ... ) DHCP_OPTION ( __VA_ARGS__, DHCP_END )
 229
 230 /**
 231  * A DHCP option
 232  *
 233  * DHCP options consist of a mandatory tag, a length field that is
 234  * mandatory for all options except @c DHCP_PAD and @c DHCP_END, and a
 235  * payload.
 236  */
 237 struct dhcp_option {
 238         /** Tag
 239          *
 240          * Must be a @c DHCP_XXX value.
 241          */
 242         uint8_t tag;
 243         /** Length
 244          *
 245          * This is the length of the data field (i.e. excluding the
 246          * tag and length fields).  For the two tags @c DHCP_PAD and
 247          * @c DHCP_END, the length field is implicitly zero and is
 248          * also missing, i.e. these DHCP options are only a single
 249          * byte in length.
 250          */
 251         uint8_t len;
 252         /** Option data
 253          *
 254          * Interpretation of the content is entirely dependent upon
 255          * the tag.  For fields containing a multi-byte integer, the
 256          * field is defined to be in network-endian order (unless you
 257          * are Intel and feel like violating the spec for fun).
 258          */
 259         union {
 260                 uint8_t byte;
 261                 uint16_t word;
 262                 uint32_t dword;
 263                 struct in_addr in;
 264                 uint8_t bytes[0];
 265                 char string[0];
 266         } data;
 267 } __attribute__ (( packed ));
 268
 269 /**
 270  * Length of a DHCP option header
 271  *
 272  * The header is the portion excluding the data, i.e. the tag and the
 273  * length.
 274  */
 275 #define DHCP_OPTION_HEADER_LEN ( offsetof ( struct dhcp_option, data ) )
 276
 277 /** Maximum length for a single DHCP option */
 278 #define DHCP_MAX_LEN 0xff
 279
 280 /** A DHCP options block */
 281 struct dhcp_option_block {
 282         /** List of option blocks */
 283         struct list_head list;
 284         /** Option block raw data */
 285         void *data;
 286         /** Option block length */
 287         size_t len;
 288         /** Option block maximum length */
 289         size_t max_len;
 290         /** Block priority
 291          *
 292          * This is determined at the time of the call to
 293          * register_options() by searching for the @c DHCP_EB_PRIORITY
 294          * option.
 295          */
 296         signed int priority;
 297 };
 298
 299 /**
 300  * A DHCP header
 301  *
 302  */
 303 struct dhcphdr {
 304         /** Operation
 305          *
 306          * This must be either @c BOOTP_REQUEST or @c BOOTP_REPLY.
 307          */
 308         uint8_t op;
 309         /** Hardware address type
 310          *
 311          * This is an ARPHRD_XXX constant.  Note that ARPHRD_XXX
 312          * constants are nominally 16 bits wide; this could be
 313          * considered to be a bug in the BOOTP/DHCP specification.
 314          */
 315         uint8_t htype;
 316         /** Hardware address length */
 317         uint8_t hlen;
 318         /** Number of hops from server */
 319         uint8_t hops;
 320         /** Transaction ID */
 321         uint32_t xid;
 322         /** Seconds since start of acquisition */
 323         uint16_t secs;
 324         /** Flags */
 325         uint16_t flags;
 326         /** "Client" IP address
 327          *
 328          * This is filled in if the client already has an IP address
 329          * assigned and can respond to ARP requests.
 330          */
 331         struct in_addr ciaddr;
 332         /** "Your" IP address
 333          *
 334          * This is the IP address assigned by the server to the client.
 335          */
 336         struct in_addr yiaddr;
 337         /** "Server" IP address
 338          *
 339          * This is the IP address of the next server to be used in the
 340          * boot process.
 341          */
 342         struct in_addr siaddr;
 343         /** "Gateway" IP address
 344          *
 345          * This is the IP address of the DHCP relay agent, if any.
 346          */
 347         struct in_addr giaddr;
 348         /** Client hardware address */
 349         uint8_t chaddr[16];
 350         /** Server host name (null terminated)
 351          *
 352          * This field may be overridden and contain DHCP options
 353          */
 354         uint8_t sname[64];
 355         /** Boot file name (null terminated)
 356          *
 357          * This field may be overridden and contain DHCP options
 358          */
 359         uint8_t file[128];
 360         /** DHCP magic cookie
 361          *
 362          * Must have the value @c DHCP_MAGIC_COOKIE.
 363          */
 364         uint32_t magic;
 365         /** DHCP options
 366          *
 367          * Variable length; extends to the end of the packet.  Minimum
 368          * length (for the sake of sanity) is 1, to allow for a single
 369          * @c DHCP_END tag.
 370          */
 371         uint8_t options[1];
 372 };
 373
 374 /** Opcode for a request from client to server */
 375 #define BOOTP_REQUEST 1
 376
 377 /** Opcode for a reply from server to client */
 378 #define BOOTP_REPLY 2
 379
 380 /** DHCP magic cookie */
 381 #define DHCP_MAGIC_COOKIE 0x63825363UL
 382
 383 /** DHCP packet option block fill order
 384  *
 385  * This is the order in which option blocks are filled when
 386  * reassembling a DHCP packet.  We fill the smallest field ("sname")
 387  * first, to maximise the chances of being able to fit large options
 388  * within fields which are large enough to contain them.
 389  */
 390 enum dhcp_packet_option_block_fill_order {
 391         OPTS_SNAME = 0,
 392         OPTS_FILE,
 393         OPTS_MAIN,
 394         NUM_OPT_BLOCKS
 395 };
 396
 397 /**
 398  * A DHCP packet
 399  *
 400  */
 401 struct dhcp_packet {
 402         /** The DHCP packet contents */
 403         struct dhcphdr *dhcphdr;
 404         /** Maximum length of the DHCP packet buffer */
 405         size_t max_len;
 406         /** Used length of the DHCP packet buffer */
 407         size_t len;
 408         /** DHCP option blocks within a DHCP packet
 409          *
 410          * A DHCP packet contains three fields which can be used to
 411          * contain options: the actual "options" field plus the "file"
 412          * and "sname" fields (which can be overloaded to contain
 413          * options).
 414          */
 415         struct dhcp_option_block options[NUM_OPT_BLOCKS];
 416 };
 417
 418 /** A DHCP session */
 419 struct dhcp_session {
 420         /** UDP connection for this session */
 421         struct udp_connection udp;
 422
 423         /** Network device being configured */
 424         struct net_device *netdev;
 425
 426         /** Options obtained from server */
 427         struct dhcp_option_block *options;
 428
 429         /** State of the session
 430          *
 431          * This is a value for the @c DHCP_MESSAGE_TYPE option
 432          * (e.g. @c DHCPDISCOVER).
 433          */
 434         int state;
 435         /** Asynchronous operation for this DHCP session */
 436         struct async_operation aop;
 437         /** Retransmission timer */
 438         struct retry_timer timer;
 439 };
 440
 441 extern unsigned long dhcp_num_option ( struct dhcp_option *option );
 442 extern void dhcp_ipv4_option ( struct dhcp_option *option,
 443                                struct in_addr *inp );
 444 extern int dhcp_snprintf ( char *buf, size_t size,
 445                            struct dhcp_option *option );
 446 extern struct dhcp_option *
 447 find_dhcp_option ( struct dhcp_option_block *options, unsigned int tag );
 448 extern void register_dhcp_options ( struct dhcp_option_block *options );
 449 extern void unregister_dhcp_options ( struct dhcp_option_block *options );
 450 extern void init_dhcp_options ( struct dhcp_option_block *options,
 451                                 void *data, size_t max_len );
 452 extern struct dhcp_option_block * alloc_dhcp_options ( size_t max_len );
 453 extern void free_dhcp_options ( struct dhcp_option_block *options );
 454 extern struct dhcp_option *
 455 set_dhcp_option ( struct dhcp_option_block *options, unsigned int tag,
 456                   const void *data, size_t len );
 457 extern struct dhcp_option * find_global_dhcp_option ( unsigned int tag );
 458 extern unsigned long find_dhcp_num_option ( struct dhcp_option_block *options,
 459                                             unsigned int tag );
 460 extern unsigned long find_global_dhcp_num_option ( unsigned int tag );
 461 extern void find_dhcp_ipv4_option ( struct dhcp_option_block *options,
 462                                     unsigned int tag, struct in_addr *inp );
 463 extern void find_global_dhcp_ipv4_option ( unsigned int tag,
 464                                            struct in_addr *inp );
 465 extern void delete_dhcp_option ( struct dhcp_option_block *options,
 466                                  unsigned int tag );
 467
 468 extern struct dhcp_option_block dhcp_request_options;
 469 extern int create_dhcp_packet ( struct net_device *netdev, uint8_t msgtype,
 470                                 void *data, size_t max_len,
 471                                 struct dhcp_packet *dhcppkt );
 472 extern int copy_dhcp_packet_options ( struct dhcp_packet *dhcppkt,
 473                                       struct dhcp_option_block *options );
 474 extern struct async_operation * start_dhcp ( struct dhcp_session *dhcp );
 475
 476 #endif /* _GPXE_DHCP_H */