MdeModulePkg/Universal/Network/Dhcp4Dxe/Dhcp4Option.h

   1 /** @file
   2   To validate, parse and process the DHCP options.
   3
   4 Copyright (c) 2006, Intel Corporation.<BR>
   5 All rights reserved. This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __EFI_DHCP4_OPTION_H__
  16 #define __EFI_DHCP4_OPTION_H__
  17
  18 ///
  19 /// DHCP option tags (types)
  20 ///
  21 typedef enum {
  22   //
  23   // RFC1497 vendor extensions
  24   //
  25   DHCP_TAG_PAD             = 0,    // Pad Option
  26   DHCP_TAG_EOP             = 255,  // End Option
  27   DHCP_TAG_NETMASK         = 1,    // Subnet Mask
  28   DHCP_TAG_TIME_OFFSET     = 2,    // Time Offset from UTC
  29   DHCP_TAG_ROUTER          = 3,    // Router option,
  30   DHCP_TAG_TIME_SERVER     = 4,    // Time Server
  31   DHCP_TAG_NAME_SERVER     = 5,    // Name Server
  32   DHCP_TAG_DNS_SERVER      = 6,    // Domain Name Server
  33   DHCP_TAG_LOG_SERVER      = 7,    // Log Server
  34   DHCP_TAG_COOKIE_SERVER   = 8,    // Cookie Server
  35   DHCP_TAG_LPR_SERVER      = 9,    // LPR Print Server
  36   DHCP_TAG_IMPRESS_SERVER  = 10,   // Impress Server
  37   DHCP_TAG_RL_SERVER       = 11,   // Resource Location Server
  38   DHCP_TAG_HOSTNAME        = 12,   // Host Name
  39   DHCP_TAG_BOOTFILE_LEN    = 13,   // Boot File Size
  40   DHCP_TAG_DUMP            = 14,   // Merit Dump File
  41   DHCP_TAG_DOMAINNAME      = 15,   // Domain Name
  42   DHCP_TAG_SWAP_SERVER     = 16,   // Swap Server
  43   DHCP_TAG_ROOTPATH        = 17,   // Root path
  44   DHCP_TAG_EXTEND_PATH     = 18,   // Extensions Path
  45
  46   //
  47   // IP Layer Parameters per Host
  48   //
  49   DHCP_TAG_IPFORWARD       = 19, // IP Forwarding Enable/Disable
  50   DHCP_TAG_NONLOCAL_SRR    = 20, // on-Local Source Routing Enable/Disable
  51   DHCP_TAG_POLICY_SRR      = 21, // Policy Filter
  52   DHCP_TAG_EMTU            = 22, // Maximum Datagram Reassembly Size
  53   DHCP_TAG_TTL             = 23, // Default IP Time-to-live
  54   DHCP_TAG_PATHMTU_AGE     = 24, // Path MTU Aging Timeout
  55   DHCP_TAG_PATHMTU_PLATEAU = 25, // Path MTU Plateau Table
  56
  57   //
  58   // IP Layer Parameters per Interface
  59   //
  60   DHCP_TAG_IFMTU           = 26, // Interface MTU
  61   DHCP_TAG_SUBNET_LOCAL    = 27, // All Subnets are Local
  62   DHCP_TAG_BROADCAST       = 28, // Broadcast Address
  63   DHCP_TAG_DISCOVER_MASK   = 29, // Perform Mask Discovery
  64   DHCP_TAG_SUPPLY_MASK     = 30, // Mask Supplier
  65   DHCP_TAG_DISCOVER_ROUTE  = 31, // Perform Router Discovery
  66   DHCP_TAG_ROUTER_SOLICIT  = 32, // Router Solicitation Address
  67   DHCP_TAG_STATIC_ROUTE    = 33, // Static Route
  68
  69   //
  70   // Link Layer Parameters per Interface
  71   //
  72   DHCP_TAG_TRAILER         = 34, // Trailer Encapsulation
  73   DHCP_TAG_ARPAGE          = 35, // ARP Cache Timeout
  74   DHCP_TAG_ETHER_ENCAP     = 36, // Ethernet Encapsulation
  75
  76   //
  77   // TCP Parameters
  78   //
  79   DHCP_TAG_TCP_TTL         = 37, // TCP Default TTL
  80   DHCP_TAG_KEEP_INTERVAL   = 38, // TCP Keepalive Interval
  81   DHCP_TAG_KEEP_GARBAGE    = 39, // TCP Keepalive Garbage
  82
  83   //
  84   // Application and Service Parameters
  85   //
  86   DHCP_TAG_NIS_DOMAIN      = 40,   // Network Information Service Domain
  87   DHCP_TAG_NIS_SERVER      = 41,   // Network Information Servers
  88   DHCP_TAG_NTP_SERVER      = 42,   // Network Time Protocol Servers
  89   DHCP_TAG_VENDOR          = 43,   // Vendor Specific Information
  90   DHCP_TAG_NBNS            = 44,   // NetBIOS over TCP/IP Name Server
  91   DHCP_TAG_NBDD            = 45,   // NetBIOS Datagram Distribution Server
  92   DHCP_TAG_NBTYPE          = 46,   // NetBIOS over TCP/IP Node Type
  93   DHCP_TAG_NBSCOPE         = 47,   // NetBIOS over TCP/IP Scope
  94   DHCP_TAG_XFONT           = 48,   // X Window System Font Server
  95   DHCP_TAG_XDM             = 49,   // X Window System Display Manager
  96   DHCP_TAG_NISPLUS         = 64,   // Network Information Service+ Domain
  97   DHCP_TAG_NISPLUS_SERVER  = 65,   // Network Information Service+ Servers
  98   DHCP_TAG_MOBILEIP        = 68,   // Mobile IP Home Agent
  99   DHCP_TAG_SMTP            = 69,   // Simple Mail Transport Protocol Server
 100   DHCP_TAG_POP3            = 70,   // Post Office Protocol (POP3) Server
 101   DHCP_TAG_NNTP            = 71,   // Network News Transport Protocol Server
 102   DHCP_TAG_WWW             = 72,   // Default World Wide Web (WWW) Server
 103   DHCP_TAG_FINGER          = 73,   // Default Finger Server
 104   DHCP_TAG_IRC             = 74,   // Default Internet Relay Chat (IRC) Server
 105   DHCP_TAG_STTALK          = 75,   // StreetTalk Server
 106   DHCP_TAG_STDA            = 76,   // StreetTalk Directory Assistance Server
 107   DHCP_TAG_CLASSLESS_ROUTE = 121,  // Classless Route
 108
 109   //
 110   // DHCP Extensions
 111   //
 112   DHCP_TAG_REQUEST_IP      = 50,         // Requested IP Address
 113   DHCP_TAG_LEASE           = 51,         // IP Address Lease Time
 114   DHCP_TAG_OVERLOAD        = 52,         // Option Overload
 115   DHCP_TAG_TFTP            = 66,         // TFTP server name
 116   DHCP_TAG_BOOTFILE        = 67,         // Bootfile name
 117   DHCP_TAG_TYPE            = 53,         // DHCP Message Type
 118   DHCP_TAG_SERVER_ID       = 54,         // Server Identifier
 119   DHCP_TAG_PARA_LIST       = 55,         // Parameter Request List
 120   DHCP_TAG_MESSAGE         = 56,         // Message
 121   DHCP_TAG_MAXMSG          = 57,         // Maximum DHCP Message Size
 122   DHCP_TAG_T1              = 58,         // Renewal (T1) Time Value
 123   DHCP_TAG_T2              = 59,         // Rebinding (T2) Time Value
 124   DHCP_TAG_VENDOR_CLASS    = 60,         // Vendor class identifier
 125   DHCP_TAG_CLIENT_ID       = 61          // Client-identifier
 126 } DHCP_TAGS;
 127
 128 #define DHCP_OPTION_MAGIC      0x63538263 // Network byte order
 129 #define DHCP_MAX_OPTIONS              256
 130
 131 typedef enum {
 132   //
 133   // DHCP option types, this is used to validate the DHCP options.
 134   //
 135   DHCP_OPTION_SWITCH       = 1,
 136   DHCP_OPTION_INT8,
 137   DHCP_OPTION_INT16,
 138   DHCP_OPTION_INT32,
 139   DHCP_OPTION_IP,
 140   DHCP_OPTION_IPPAIR
 141 } DHCP_OPTION_TYPE;
 142
 143 typedef enum {
 144   //
 145   // Value of DHCP overload option
 146   //
 147   DHCP_OVERLOAD_FILENAME   = 1,
 148   DHCP_OVERLOAD_SVRNAME    = 2,
 149   DHCP_OVERLOAD_BOTH       = 3
 150 } DHCP_OVERLOAD_TYPE;
 151
 152 ///
 153 /// The DHCP option structure. This structure extends the EFI_DHCP_OPTION
 154 /// structure to support options longer than 255 bytes, such as classless route.
 155 ///
 156 typedef struct {
 157   UINT8                     Tag;
 158   UINT16                    Len;
 159   UINT8                     *Data;
 160 } DHCP_OPTION;
 161
 162 ///
 163 /// Structures used to parse the DHCP options with RFC3396 support.
 164 ///
 165 typedef struct {
 166   UINT8                     Index;
 167   UINT16                    Offset;
 168 } DHCP_OPTION_COUNT;
 169
 170 typedef struct {
 171   DHCP_OPTION_COUNT         *OpCount;
 172   DHCP_OPTION               *Options;
 173   UINT8                     *Buf;
 174 } DHCP_OPTION_CONTEXT;
 175
 176 ///
 177 /// The options that matters to DHCP driver itself. The user of
 178 /// DHCP clients may be interested in other options, such as
 179 /// classless route, who can parse the DHCP offer to get them.
 180 ///
 181 typedef struct {
 182   IP4_ADDR                  NetMask;  // DHCP_TAG_NETMASK
 183   IP4_ADDR                  Router;   // DHCP_TAG_ROUTER, only the first router is used
 184
 185   //
 186   // DHCP specific options
 187   //
 188   UINT8                     DhcpType; // DHCP_TAG_TYPE
 189   UINT8                     Overload; // DHCP_TAG_OVERLOAD
 190   IP4_ADDR                  ServerId; // DHCP_TAG_SERVER_ID
 191   UINT32                    Lease;    // DHCP_TAG_LEASE
 192   UINT32                    T1;       // DHCP_TAG_T1
 193   UINT32                    T2;       // DHCP_TAG_T2
 194 } DHCP_PARAMETER;
 195
 196 ///
 197 /// Structure used to describe and validate the format of DHCP options.
 198 /// Type is the options' data type, such as DHCP_OPTION_INT8. MinOccur
 199 /// is the minium occurance of this data type. MaxOccur is defined
 200 /// similarly. If MaxOccur is -1, it means that there is no limit on the
 201 /// maximum occurance. Alert tells whether DHCP client should further
 202 /// inspect the option to parse DHCP_PARAMETER.
 203 ///
 204 typedef struct {
 205   UINT8                     Tag;
 206   INTN                      Type;
 207   INTN                      MinOccur;
 208   INTN                      MaxOccur;
 209   BOOLEAN                   Alert;
 210 } DHCP_OPTION_FORMAT;
 211
 212 typedef
 213 EFI_STATUS
 214 (*DHCP_CHECK_OPTION) (
 215   IN UINT8                  Tag,
 216   IN UINT8                  Len,
 217   IN UINT8                  *Data,
 218   IN VOID                   *Context
 219   );
 220
 221 /**
 222   Iterate through a DHCP message to visit each option. First inspect
 223   all the options in the OPTION field. Then if overloaded, inspect
 224   the options in FILENAME and SERVERNAME fields. One option may be
 225   encoded in several places. See RFC 3396 Encoding Long Options in DHCP
 226
 227   @param[in]  Packet                 The DHCP packet to check the options for
 228   @param[in]  Check                  The callback function to be called for each option
 229                                      found
 230   @param[in]  Context                The opaque parameter for Check
 231
 232   @retval EFI_SUCCESS            The DHCP packet's options are well formated
 233   @retval EFI_INVALID_PARAMETER  The DHCP packet's options are not well formated
 234
 235 **/
 236 EFI_STATUS
 237 DhcpIterateOptions (
 238   IN  EFI_DHCP4_PACKET      *Packet,
 239   IN  DHCP_CHECK_OPTION     Check,        OPTIONAL
 240   IN  VOID                  *Context
 241   );
 242
 243 /**
 244   Validate the packet's options. If necessary, allocate
 245   and fill in the interested parameters.
 246
 247   @param[in]  Packet                 The packet to validate the options
 248   @param[out] Para                   The variable to save the DHCP parameters.
 249
 250   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory to validate the packet.
 251   @retval EFI_INVALID_PARAMETER  The options are mal-formated
 252   @retval EFI_SUCCESS            The options are parsed into OptionPoint
 253
 254 **/
 255 EFI_STATUS
 256 DhcpValidateOptions (
 257   IN  EFI_DHCP4_PACKET      *Packet,
 258   OUT DHCP_PARAMETER        **Para       OPTIONAL
 259   );
 260
 261 /**
 262   Parse the options of a DHCP packet. It supports RFC 3396: Encoding
 263   Long Options in DHCP. That is, it will combine all the option value
 264   of all the occurances of each option.
 265   A little bit of implemenation:
 266   It adopts the "Key indexed counting" algorithm. First, it allocates
 267   an array of 256 DHCP_OPTION_COUNTs because DHCP option tag is encoded
 268   as a UINT8. It then iterates the DHCP packet to get data length of
 269   each option by calling DhcpIterOptions with DhcpGetOptionLen. Now, it
 270   knows the number of present options and their length. It allocates a
 271   array of DHCP_OPTION and a continuous buffer after the array to put
 272   all the options' data. Each option's data is pointed to by the Data
 273   field in DHCP_OPTION structure. At last, it call DhcpIterateOptions
 274   with DhcpFillOption to fill each option's data to its position in the
 275   buffer.
 276
 277   @param[in]  Packet                 The DHCP packet to parse the options
 278   @param[out] Count                  The number of valid dhcp options present in the
 279                                      packet
 280   @param[out] OptionPoint            The array that contains the DHCP options. Caller
 281                                      should free it.
 282
 283   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory to parse the packet.
 284   @retval EFI_INVALID_PARAMETER  The options are mal-formated
 285   @retval EFI_SUCCESS            The options are parsed into OptionPoint
 286
 287 **/
 288 EFI_STATUS
 289 DhcpParseOption (
 290   IN  EFI_DHCP4_PACKET      *Packet,
 291   OUT INTN                  *Count,
 292   OUT DHCP_OPTION           **OptionPoint
 293   );
 294
 295 /**
 296   Append an option to the memory, if the option is longer than
 297   255 bytes, splits it into several options.
 298
 299   @param[out] Buf                    The buffer to append the option to
 300   @param[in]  Tag                    The option's tag
 301   @param[in]  DataLen                The length of the option's data
 302   @param[in]  Data                   The option's data
 303
 304   @return The position to append the next option
 305
 306 **/
 307 UINT8 *
 308 DhcpAppendOption (
 309   OUT UINT8                  *Buf,
 310   IN  UINT8                  Tag,
 311   IN  UINT16                 DataLen,
 312   IN  UINT8                  *Data
 313   );
 314
 315 /**
 316   Build a new DHCP packet from a seed packet. Options may be deleted or
 317   appended. The caller should free the NewPacket when finished using it.
 318
 319   @param[in]  SeedPacket             The seed packet to start with
 320   @param[in]  DeleteCount            The number of options to delete
 321   @param[in]  DeleteList             The options to delete from the packet
 322   @param[in]  AppendCount            The number of options to append
 323   @param[in]  AppendList             The options to append to the packet
 324   @param[out] NewPacket              The new packet, allocated and built by this
 325                                      function.
 326
 327   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory
 328   @retval EFI_INVALID_PARAMETER  The options in SeekPacket are mal-formated
 329   @retval EFI_SUCCESS            The packet is build.
 330
 331 **/
 332 EFI_STATUS
 333 DhcpBuild (
 334   IN  EFI_DHCP4_PACKET        *SeedPacket,
 335   IN  UINT32                  DeleteCount,
 336   IN  UINT8                   *DeleteList     OPTIONAL,
 337   IN  UINT32                  AppendCount,
 338   IN  EFI_DHCP4_PACKET_OPTION *AppendList[]   OPTIONAL,
 339   OUT EFI_DHCP4_PACKET        **NewPacket
 340   );
 341
 342 #endif