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