NetworkPkg/HttpDxe/HttpsSupport.h

   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 its
 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