Dhcp4Option.h 7.6 KB

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