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