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