NetworkPkg/HttpDxe/HttpsSupport.h

   1 /** @file
   2   The header files of miscellaneous routines specific to Https for HttpDxe driver.
   3
   4 Copyright (c) 2016, 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] TlsProto              Pointer to the EFI_TLS_PROTOCOL instance.
  41   @param[out] TlsConfiguration      Pointer to the EFI_TLS_CONFIGURATION_PROTOCOL instance.
  42
  43   @return  The child handle with opened EFI_TLS_PROTOCOL and EFI_TLS_CONFIGURATION_PROTOCOL.
  44
  45 **/
  46 EFI_HANDLE
  47 EFIAPI
  48 TlsCreateChild (
  49   IN  EFI_HANDLE                     ImageHandle,
  50   OUT EFI_TLS_PROTOCOL               **TlsProto,
  51   OUT EFI_TLS_CONFIGURATION_PROTOCOL **TlsConfiguration
  52   );
  53
  54 /**
  55   Create event for the TLS receive and transmit tokens which are used to receive and
  56   transmit TLS related messages.
  57
  58   @param[in, out]  HttpInstance       Pointer to HTTP_PROTOCOL structure.
  59
  60   @retval EFI_SUCCESS            The events are created successfully.
  61   @retval others                 Other error as indicated.
  62
  63 **/
  64 EFI_STATUS
  65 EFIAPI
  66 TlsCreateTxRxEvent (
  67   IN OUT HTTP_PROTOCOL      *HttpInstance
  68   );
  69
  70 /**
  71   Close events in the TlsTxToken and TlsRxToken.
  72
  73   @param[in]  HttpInstance   Pointer to HTTP_PROTOCOL structure.
  74
  75 **/
  76 VOID
  77 EFIAPI
  78 TlsCloseTxRxEvent (
  79   IN  HTTP_PROTOCOL        *HttpInstance
  80   );
  81
  82 /**
  83   Read the TlsCaCertificate variable and configure it.
  84
  85   @param[in, out]  HttpInstance       The HTTP instance private data.
  86
  87   @retval EFI_SUCCESS            TlsCaCertificate is configured.
  88   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.
  89   @retval EFI_NOT_FOUND          Fail to get "TlsCaCertificate" variable.
  90   @retval Others                 Other error as indicated.
  91
  92 **/
  93 EFI_STATUS
  94 TlsConfigCertificate (
  95   IN OUT HTTP_PROTOCOL      *HttpInstance
  96   );
  97
  98 /**
  99   Configure TLS session data.
 100
 101   @param[in, out]  HttpInstance       The HTTP instance private data.
 102
 103   @retval EFI_SUCCESS            TLS session data is configured.
 104   @retval Others                 Other error as indicated.
 105
 106 **/
 107 EFI_STATUS
 108 EFIAPI
 109 TlsConfigureSession (
 110   IN OUT HTTP_PROTOCOL      *HttpInstance
 111   );
 112
 113 /**
 114   Transmit the Packet by processing the associated HTTPS token.
 115
 116   @param[in, out]   HttpInstance    Pointer to HTTP_PROTOCOL structure.
 117   @param[in]        Packet          The packet to transmit.
 118
 119   @retval EFI_SUCCESS            The packet is transmitted.
 120   @retval EFI_INVALID_PARAMETER  HttpInstance is NULL or Packet is NULL.
 121   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.
 122   @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.
 123   @retval Others                 Other errors as indicated.
 124
 125 **/
 126 EFI_STATUS
 127 EFIAPI
 128 TlsCommonTransmit (
 129   IN OUT HTTP_PROTOCOL      *HttpInstance,
 130   IN     NET_BUF            *Packet
 131   );
 132
 133 /**
 134   Receive the Packet by processing the associated HTTPS token.
 135
 136   @param[in, out]   HttpInstance    Pointer to HTTP_PROTOCOL structure.
 137   @param[in]        Packet          The packet to transmit.
 138   @param[in]        Timeout         The time to wait for connection done.
 139
 140   @retval EFI_SUCCESS            The Packet is received.
 141   @retval EFI_INVALID_PARAMETER  HttpInstance is NULL or Packet is NULL.
 142   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.
 143   @retval EFI_TIMEOUT            The operation is time out.
 144   @retval Others                 Other error as indicated.
 145
 146 **/
 147 EFI_STATUS
 148 EFIAPI
 149 TlsCommonReceive (
 150   IN OUT HTTP_PROTOCOL      *HttpInstance,
 151   IN     NET_BUF            *Packet,
 152   IN     EFI_EVENT          Timeout
 153   );
 154
 155 /**
 156   Receive one TLS PDU. An TLS PDU contains an TLS record header and it's
 157   corresponding record data. These two parts will be put into two blocks of buffers in the
 158   net buffer.
 159
 160   @param[in, out]      HttpInstance    Pointer to HTTP_PROTOCOL structure.
 161   @param[out]          Pdu             The received TLS PDU.
 162   @param[in]           Timeout         The time to wait for connection done.
 163
 164   @retval EFI_SUCCESS          An TLS PDU is received.
 165   @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.
 166   @retval EFI_PROTOCOL_ERROR   An unexpected TLS packet was received.
 167   @retval Others               Other errors as indicated.
 168
 169 **/
 170 EFI_STATUS
 171 EFIAPI
 172 TlsReceiveOnePdu (
 173   IN OUT HTTP_PROTOCOL      *HttpInstance,
 174      OUT NET_BUF            **Pdu,
 175   IN     EFI_EVENT          Timeout
 176   );
 177
 178 /**
 179   Connect one TLS session by finishing the TLS handshake process.
 180
 181   @param[in]  HttpInstance       The HTTP instance private data.
 182   @param[in]  Timeout            The time to wait for connection done.
 183
 184   @retval EFI_SUCCESS            The TLS session is established.
 185   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.
 186   @retval EFI_ABORTED            TLS session state is incorrect.
 187   @retval Others                 Other error as indicated.
 188
 189 **/
 190 EFI_STATUS
 191 EFIAPI
 192 TlsConnectSession (
 193   IN  HTTP_PROTOCOL            *HttpInstance,
 194   IN  EFI_EVENT                Timeout
 195   );
 196
 197 /**
 198   Close the TLS session and send out the close notification message.
 199
 200   @param[in]  HttpInstance       The HTTP instance private data.
 201
 202   @retval EFI_SUCCESS            The TLS session is closed.
 203   @retval EFI_INVALID_PARAMETER  HttpInstance is NULL or Packet is NULL.
 204   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.
 205   @retval Others                 Other error as indicated.
 206
 207 **/
 208 EFI_STATUS
 209 EFIAPI
 210 TlsCloseSession (
 211   IN  HTTP_PROTOCOL            *HttpInstance
 212   );
 213
 214 /**
 215   Process one message according to the CryptMode.
 216
 217   @param[in]           HttpInstance    Pointer to HTTP_PROTOCOL structure.
 218   @param[in]           Message         Pointer to the message buffer needed to processed.
 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
 224   @retval EFI_SUCCESS          Message is processed successfully.
 225   @retval EFI_OUT_OF_RESOURCES   Can't allocate memory resources.
 226   @retval Others               Other errors as indicated.
 227
 228 **/
 229 EFI_STATUS
 230 EFIAPI
 231 TlsProcessMessage (
 232   IN     HTTP_PROTOCOL            *HttpInstance,
 233   IN     UINT8                    *Message,
 234   IN     UINTN                    MessageSize,
 235   IN     EFI_TLS_CRYPT_MODE       ProcessMode,
 236   IN OUT NET_FRAGMENT             *Fragment
 237   );
 238
 239 /**
 240   Receive one fragment decrypted from one TLS record.
 241
 242   @param[in]           HttpInstance    Pointer to HTTP_PROTOCOL structure.
 243   @param[in, out]      Fragment        The received Fragment.
 244   @param[in]           Timeout         The time to wait for connection done.
 245
 246   @retval EFI_SUCCESS          One fragment is received.
 247   @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.
 248   @retval EFI_ABORTED          Something wrong decryption the message.
 249   @retval Others               Other errors as indicated.
 250
 251 **/
 252 EFI_STATUS
 253 EFIAPI
 254 HttpsReceive (
 255   IN     HTTP_PROTOCOL         *HttpInstance,
 256   IN OUT NET_FRAGMENT          *Fragment,
 257   IN     EFI_EVENT             Timeout
 258   );
 259
 260 #endif