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