MdeModulePkg/Universal/Network/Dhcp4Dxe/Dhcp4Option.h

   1 /** @file
   2   To validate, parse and process the DHCP options.
   3
   4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5 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
  22 #define DHCP_OPTION_MAGIC         0x63538263 // Network byte order
  23 #define DHCP_MAX_OPTIONS          256
  24
  25
  26 //
  27 // DHCP option types, this is used to validate the DHCP options.
  28 //
  29 #define DHCP_OPTION_SWITCH        1
  30 #define DHCP_OPTION_INT8          2
  31 #define DHCP_OPTION_INT16         3
  32 #define DHCP_OPTION_INT32         4
  33 #define DHCP_OPTION_IP            5
  34 #define DHCP_OPTION_IPPAIR        6
  35
  36 //
  37 // Value of DHCP overload option
  38 //
  39 #define DHCP_OVERLOAD_FILENAME    1
  40 #define DHCP_OVERLOAD_SVRNAME     2
  41 #define DHCP_OVERLOAD_BOTH        3
  42
  43 ///
  44 /// The DHCP option structure. This structure extends the EFI_DHCP_OPTION
  45 /// structure to support options longer than 255 bytes, such as classless route.
  46 ///
  47 typedef struct {
  48   UINT8                     Tag;
  49   UINT16                    Len;
  50   UINT8                     *Data;
  51 } DHCP_OPTION;
  52
  53 ///
  54 /// Structures used to parse the DHCP options with RFC3396 support.
  55 ///
  56 typedef struct {
  57   UINT8                     Index;
  58   UINT16                    Offset;
  59 } DHCP_OPTION_COUNT;
  60
  61 typedef struct {
  62   DHCP_OPTION_COUNT         *OpCount;
  63   DHCP_OPTION               *Options;
  64   UINT8                     *Buf;
  65 } DHCP_OPTION_CONTEXT;
  66
  67 ///
  68 /// The options that matters to DHCP driver itself. The user of
  69 /// DHCP clients may be interested in other options, such as
  70 /// classless route, who can parse the DHCP offer to get them.
  71 ///
  72 typedef struct {
  73   IP4_ADDR                  NetMask;  // DHCP4_TAG_NETMASK
  74   IP4_ADDR                  Router;   // DHCP4_TAG_ROUTER, only the first router is used
  75
  76   //
  77   // DHCP specific options
  78   //
  79   UINT8                     DhcpType; // DHCP4_TAG_MSG_TYPE
  80   UINT8                     Overload; // DHCP4_TAG_OVERLOAD
  81   IP4_ADDR                  ServerId; // DHCP4_TAG_SERVER_ID
  82   UINT32                    Lease;    // DHCP4_TAG_LEASE
  83   UINT32                    T1;       // DHCP4_TAG_T1
  84   UINT32                    T2;       // DHCP4_TAG_T2
  85 } DHCP_PARAMETER;
  86
  87 ///
  88 /// Structure used to describe and validate the format of DHCP options.
  89 /// Type is the options' data type, such as DHCP_OPTION_INT8. MinOccur
  90 /// is the minium occurance of this data type. MaxOccur is defined
  91 /// similarly. If MaxOccur is -1, it means that there is no limit on the
  92 /// maximum occurance. Alert tells whether DHCP client should further
  93 /// inspect the option to parse DHCP_PARAMETER.
  94 ///
  95 typedef struct {
  96   UINT8                     Tag;
  97   INTN                      Type;
  98   INTN                      MinOccur;
  99   INTN                      MaxOccur;
 100   BOOLEAN                   Alert;
 101 } DHCP_OPTION_FORMAT;
 102
 103 typedef
 104 EFI_STATUS
 105 (*DHCP_CHECK_OPTION) (
 106   IN UINT8                  Tag,
 107   IN UINT8                  Len,
 108   IN UINT8                  *Data,
 109   IN VOID                   *Context
 110   );
 111
 112 /**
 113   Iterate through a DHCP message to visit each option. First inspect
 114   all the options in the OPTION field. Then if overloaded, inspect
 115   the options in FILENAME and SERVERNAME fields. One option may be
 116   encoded in several places. See RFC 3396 Encoding Long Options in DHCP
 117
 118   @param[in]  Packet                 The DHCP packet to check the options for
 119   @param[in]  Check                  The callback function to be called for each option
 120                                      found
 121   @param[in]  Context                The opaque parameter for Check
 122
 123   @retval EFI_SUCCESS            The DHCP packet's options are well formated
 124   @retval EFI_INVALID_PARAMETER  The DHCP packet's options are not well formated
 125
 126 **/
 127 EFI_STATUS
 128 DhcpIterateOptions (
 129   IN  EFI_DHCP4_PACKET      *Packet,
 130   IN  DHCP_CHECK_OPTION     Check         OPTIONAL,
 131   IN  VOID                  *Context
 132   );
 133
 134 /**
 135   Validate the packet's options. If necessary, allocate
 136   and fill in the interested parameters.
 137
 138   @param[in]  Packet                 The packet to validate the options
 139   @param[out] Para                   The variable to save the DHCP parameters.
 140
 141   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory to validate the packet.
 142   @retval EFI_INVALID_PARAMETER  The options are mal-formated
 143   @retval EFI_SUCCESS            The options are parsed into OptionPoint
 144
 145 **/
 146 EFI_STATUS
 147 DhcpValidateOptions (
 148   IN  EFI_DHCP4_PACKET      *Packet,
 149   OUT DHCP_PARAMETER        **Para       OPTIONAL
 150   );
 151
 152 /**
 153   Parse the options of a DHCP packet. It supports RFC 3396: Encoding
 154   Long Options in DHCP. That is, it will combine all the option value
 155   of all the occurances of each option.
 156   A little bit of implemenation:
 157   It adopts the "Key indexed counting" algorithm. First, it allocates
 158   an array of 256 DHCP_OPTION_COUNTs because DHCP option tag is encoded
 159   as a UINT8. It then iterates the DHCP packet to get data length of
 160   each option by calling DhcpIterOptions with DhcpGetOptionLen. Now, it
 161   knows the number of present options and their length. It allocates a
 162   array of DHCP_OPTION and a continuous buffer after the array to put
 163   all the options' data. Each option's data is pointed to by the Data
 164   field in DHCP_OPTION structure. At last, it call DhcpIterateOptions
 165   with DhcpFillOption to fill each option's data to its position in the
 166   buffer.
 167
 168   @param[in]  Packet                 The DHCP packet to parse the options
 169   @param[out] Count                  The number of valid dhcp options present in the
 170                                      packet
 171   @param[out] OptionPoint            The array that contains the DHCP options. Caller
 172                                      should free it.
 173
 174   @retval EFI_NOT_FOUND          Cannot find any option.
 175   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory to parse the packet.
 176   @retval EFI_INVALID_PARAMETER  The options are mal-formated
 177   @retval EFI_SUCCESS            The options are parsed into OptionPoint
 178
 179 **/
 180 EFI_STATUS
 181 DhcpParseOption (
 182   IN  EFI_DHCP4_PACKET      *Packet,
 183   OUT INTN                  *Count,
 184   OUT DHCP_OPTION           **OptionPoint
 185   );
 186
 187 /**
 188   Append an option to the memory, if the option is longer than
 189   255 bytes, splits it into several options.
 190
 191   @param[out] Buf                    The buffer to append the option to
 192   @param[in]  Tag                    The option's tag
 193   @param[in]  DataLen                The length of the option's data
 194   @param[in]  Data                   The option's data
 195
 196   @return The position to append the next option
 197
 198 **/
 199 UINT8 *
 200 DhcpAppendOption (
 201   OUT UINT8                  *Buf,
 202   IN  UINT8                  Tag,
 203   IN  UINT16                 DataLen,
 204   IN  UINT8                  *Data
 205   );
 206
 207 /**
 208   Build a new DHCP packet from a seed packet. Options may be deleted or
 209   appended. The caller should free the NewPacket when finished using it.
 210
 211   @param[in]  SeedPacket             The seed packet to start with
 212   @param[in]  DeleteCount            The number of options to delete
 213   @param[in]  DeleteList             The options to delete from the packet
 214   @param[in]  AppendCount            The number of options to append
 215   @param[in]  AppendList             The options to append to the packet
 216   @param[out] NewPacket              The new packet, allocated and built by this
 217                                      function.
 218
 219   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory
 220   @retval EFI_INVALID_PARAMETER  The options in SeekPacket are mal-formated
 221   @retval EFI_SUCCESS            The packet is build.
 222
 223 **/
 224 EFI_STATUS
 225 DhcpBuild (
 226   IN  EFI_DHCP4_PACKET        *SeedPacket,
 227   IN  UINT32                  DeleteCount,
 228   IN  UINT8                   *DeleteList     OPTIONAL,
 229   IN  UINT32                  AppendCount,
 230   IN  EFI_DHCP4_PACKET_OPTION *AppendList[]   OPTIONAL,
 231   OUT EFI_DHCP4_PACKET        **NewPacket
 232   );
 233
 234 #endif