HttpsSupport.h 8.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264
  1. /** @file
  2. The header files of miscellaneous routines specific to Https for HttpDxe driver.
  3. Copyright (c) 2016 - 2018, Intel Corporation. All rights reserved.<BR>
  4. SPDX-License-Identifier: BSD-2-Clause-Patent
  5. **/
  6. #ifndef __EFI_HTTPS_SUPPORT_H__
  7. #define __EFI_HTTPS_SUPPORT_H__
  8. #define HTTPS_DEFAULT_PORT 443
  9. #define HTTPS_FLAG "https://"
  10. /**
  11. Check whether the Url is from Https.
  12. @param[in] Url The pointer to a HTTP or HTTPS URL string.
  13. @retval TRUE The Url is from HTTPS.
  14. @retval FALSE The Url is from HTTP.
  15. **/
  16. BOOLEAN
  17. IsHttpsUrl (
  18. IN CHAR8 *Url
  19. );
  20. /**
  21. Creates a Tls child handle, open EFI_TLS_PROTOCOL and EFI_TLS_CONFIGURATION_PROTOCOL.
  22. @param[in] ImageHandle The firmware allocated handle for the UEFI image.
  23. @param[out] TlsSb Pointer to the TLS SERVICE_BINDING_PROTOCOL.
  24. @param[out] TlsProto Pointer to the EFI_TLS_PROTOCOL instance.
  25. @param[out] TlsConfiguration Pointer to the EFI_TLS_CONFIGURATION_PROTOCOL instance.
  26. @return The child handle with opened EFI_TLS_PROTOCOL and EFI_TLS_CONFIGURATION_PROTOCOL.
  27. **/
  28. EFI_HANDLE
  29. EFIAPI
  30. TlsCreateChild (
  31. IN EFI_HANDLE ImageHandle,
  32. OUT EFI_SERVICE_BINDING_PROTOCOL **TlsSb,
  33. OUT EFI_TLS_PROTOCOL **TlsProto,
  34. OUT EFI_TLS_CONFIGURATION_PROTOCOL **TlsConfiguration
  35. );
  36. /**
  37. Create event for the TLS receive and transmit tokens which are used to receive and
  38. transmit TLS related messages.
  39. @param[in, out] HttpInstance Pointer to HTTP_PROTOCOL structure.
  40. @retval EFI_SUCCESS The events are created successfully.
  41. @retval others Other error as indicated.
  42. **/
  43. EFI_STATUS
  44. EFIAPI
  45. TlsCreateTxRxEvent (
  46. IN OUT HTTP_PROTOCOL *HttpInstance
  47. );
  48. /**
  49. Close events in the TlsTxToken and TlsRxToken.
  50. @param[in] HttpInstance Pointer to HTTP_PROTOCOL structure.
  51. **/
  52. VOID
  53. EFIAPI
  54. TlsCloseTxRxEvent (
  55. IN HTTP_PROTOCOL *HttpInstance
  56. );
  57. /**
  58. Read the TlsCaCertificate variable and configure it.
  59. @param[in, out] HttpInstance The HTTP instance private data.
  60. @retval EFI_SUCCESS TlsCaCertificate is configured.
  61. @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.
  62. @retval EFI_NOT_FOUND Fail to get "TlsCaCertificate" variable.
  63. @retval Others Other error as indicated.
  64. **/
  65. EFI_STATUS
  66. TlsConfigCertificate (
  67. IN OUT HTTP_PROTOCOL *HttpInstance
  68. );
  69. /**
  70. Configure TLS session data.
  71. @param[in, out] HttpInstance The HTTP instance private data.
  72. @retval EFI_SUCCESS TLS session data is configured.
  73. @retval Others Other error as indicated.
  74. **/
  75. EFI_STATUS
  76. EFIAPI
  77. TlsConfigureSession (
  78. IN OUT HTTP_PROTOCOL *HttpInstance
  79. );
  80. /**
  81. Transmit the Packet by processing the associated HTTPS token.
  82. @param[in, out] HttpInstance Pointer to HTTP_PROTOCOL structure.
  83. @param[in] Packet The packet to transmit.
  84. @retval EFI_SUCCESS The packet is transmitted.
  85. @retval EFI_INVALID_PARAMETER HttpInstance is NULL or Packet is NULL.
  86. @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.
  87. @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
  88. @retval Others Other errors as indicated.
  89. **/
  90. EFI_STATUS
  91. EFIAPI
  92. TlsCommonTransmit (
  93. IN OUT HTTP_PROTOCOL *HttpInstance,
  94. IN NET_BUF *Packet
  95. );
  96. /**
  97. Receive the Packet by processing the associated HTTPS token.
  98. @param[in, out] HttpInstance Pointer to HTTP_PROTOCOL structure.
  99. @param[in] Packet The packet to transmit.
  100. @param[in] Timeout The time to wait for connection done.
  101. @retval EFI_SUCCESS The Packet is received.
  102. @retval EFI_INVALID_PARAMETER HttpInstance is NULL or Packet is NULL.
  103. @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.
  104. @retval EFI_TIMEOUT The operation is time out.
  105. @retval Others Other error as indicated.
  106. **/
  107. EFI_STATUS
  108. EFIAPI
  109. TlsCommonReceive (
  110. IN OUT HTTP_PROTOCOL *HttpInstance,
  111. IN NET_BUF *Packet,
  112. IN EFI_EVENT Timeout
  113. );
  114. /**
  115. Receive one TLS PDU. An TLS PDU contains an TLS record header and its
  116. corresponding record data. These two parts will be put into two blocks of buffers in the
  117. net buffer.
  118. @param[in, out] HttpInstance Pointer to HTTP_PROTOCOL structure.
  119. @param[out] Pdu The received TLS PDU.
  120. @param[in] Timeout The time to wait for connection done.
  121. @retval EFI_SUCCESS An TLS PDU is received.
  122. @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.
  123. @retval EFI_PROTOCOL_ERROR An unexpected TLS packet was received.
  124. @retval Others Other errors as indicated.
  125. **/
  126. EFI_STATUS
  127. EFIAPI
  128. TlsReceiveOnePdu (
  129. IN OUT HTTP_PROTOCOL *HttpInstance,
  130. OUT NET_BUF **Pdu,
  131. IN EFI_EVENT Timeout
  132. );
  133. /**
  134. Connect one TLS session by finishing the TLS handshake process.
  135. @param[in] HttpInstance The HTTP instance private data.
  136. @param[in] Timeout The time to wait for connection done.
  137. @retval EFI_SUCCESS The TLS session is established.
  138. @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.
  139. @retval EFI_ABORTED TLS session state is incorrect.
  140. @retval Others Other error as indicated.
  141. **/
  142. EFI_STATUS
  143. EFIAPI
  144. TlsConnectSession (
  145. IN HTTP_PROTOCOL *HttpInstance,
  146. IN EFI_EVENT Timeout
  147. );
  148. /**
  149. Close the TLS session and send out the close notification message.
  150. @param[in] HttpInstance The HTTP instance private data.
  151. @retval EFI_SUCCESS The TLS session is closed.
  152. @retval EFI_INVALID_PARAMETER HttpInstance is NULL or Packet is NULL.
  153. @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.
  154. @retval Others Other error as indicated.
  155. **/
  156. EFI_STATUS
  157. EFIAPI
  158. TlsCloseSession (
  159. IN HTTP_PROTOCOL *HttpInstance
  160. );
  161. /**
  162. Process one message according to the CryptMode.
  163. @param[in] HttpInstance Pointer to HTTP_PROTOCOL structure.
  164. @param[in] Message Pointer to the message buffer needed to processed.
  165. If ProcessMode is EfiTlsEncrypt, the message contain the TLS
  166. header and plain text TLS APP payload.
  167. If ProcessMode is EfiTlsDecrypt, the message contain the TLS
  168. header and cipher text TLS APP payload.
  169. @param[in] MessageSize Pointer to the message buffer size.
  170. @param[in] ProcessMode Process mode.
  171. @param[in, out] Fragment Only one Fragment returned after the Message is
  172. processed successfully.
  173. If ProcessMode is EfiTlsEncrypt, the fragment contain the TLS
  174. header and cipher text TLS APP payload.
  175. If ProcessMode is EfiTlsDecrypt, the fragment contain the TLS
  176. header and plain text TLS APP payload.
  177. @retval EFI_SUCCESS Message is processed successfully.
  178. @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.
  179. @retval Others Other errors as indicated.
  180. **/
  181. EFI_STATUS
  182. EFIAPI
  183. TlsProcessMessage (
  184. IN HTTP_PROTOCOL *HttpInstance,
  185. IN UINT8 *Message,
  186. IN UINTN MessageSize,
  187. IN EFI_TLS_CRYPT_MODE ProcessMode,
  188. IN OUT NET_FRAGMENT *Fragment
  189. );
  190. /**
  191. Receive one fragment decrypted from one TLS record.
  192. @param[in] HttpInstance Pointer to HTTP_PROTOCOL structure.
  193. @param[in, out] Fragment The received Fragment.
  194. @param[in] Timeout The time to wait for connection done.
  195. @retval EFI_SUCCESS One fragment is received.
  196. @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.
  197. @retval EFI_ABORTED Something wrong decryption the message.
  198. @retval Others Other errors as indicated.
  199. **/
  200. EFI_STATUS
  201. EFIAPI
  202. HttpsReceive (
  203. IN HTTP_PROTOCOL *HttpInstance,
  204. IN OUT NET_FRAGMENT *Fragment,
  205. IN EFI_EVENT Timeout
  206. );
  207. #endif