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