MdeModulePkg/Universal/Network/Dhcp4Dxe/Dhcp4Option.h

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