1 /** @file 2 To validate, parse and process the DHCP options. 3 4 Copyright (c) 2006 - 2016, 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 235