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