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