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