NetworkPkg/TlsDxe/TlsImpl.h

   1 /** @file
   2   Header file of Miscellaneous Routines for TlsDxe driver.
   3
   4 Copyright (c) 2016 - 2018, Intel Corporation. All rights reserved.<BR>
   5
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef __EFI_TLS_IMPL_H__
  11 #define __EFI_TLS_IMPL_H__
  12
  13 //
  14 // Libraries
  15 //
  16 #include <Library/UefiBootServicesTableLib.h>
  17 #include <Library/MemoryAllocationLib.h>
  18 #include <Library/BaseMemoryLib.h>
  19 #include <Library/BaseLib.h>
  20 #include <Library/UefiLib.h>
  21 #include <Library/DebugLib.h>
  22 #include <Library/NetLib.h>
  23 #include <Library/BaseCryptLib.h>
  24 #include <Library/TlsLib.h>
  25
  26 //
  27 // Consumed Protocols
  28 //
  29 #include <Protocol/Tls.h>
  30 #include <Protocol/TlsConfig.h>
  31
  32 #include <IndustryStandard/Tls1.h>
  33
  34 #include "TlsDriver.h"
  35
  36 //
  37 // Protocol instances
  38 //
  39 extern EFI_SERVICE_BINDING_PROTOCOL    mTlsServiceBinding;
  40 extern EFI_TLS_PROTOCOL                mTlsProtocol;
  41 extern EFI_TLS_CONFIGURATION_PROTOCOL  mTlsConfigurationProtocol;
  42
  43 /**
  44   Encrypt the message listed in fragment.
  45
  46   @param[in]       TlsInstance    The pointer to the TLS instance.
  47   @param[in, out]  FragmentTable  Pointer to a list of fragment.
  48                                   On input these fragments contain the TLS header and
  49                                   plain text TLS payload;
  50                                   On output these fragments contain the TLS header and
  51                                   cipher text TLS payload.
  52   @param[in]       FragmentCount  Number of fragment.
  53
  54   @retval EFI_SUCCESS             The operation completed successfully.
  55   @retval EFI_OUT_OF_RESOURCES    Can't allocate memory resources.
  56   @retval EFI_ABORTED             TLS session state is incorrect.
  57   @retval Others                  Other errors as indicated.
  58 **/
  59 EFI_STATUS
  60 TlsEncryptPacket (
  61   IN     TLS_INSTANCE                  *TlsInstance,
  62   IN OUT EFI_TLS_FRAGMENT_DATA         **FragmentTable,
  63   IN     UINT32                        *FragmentCount
  64   );
  65
  66 /**
  67   Decrypt the message listed in fragment.
  68
  69   @param[in]       TlsInstance    The pointer to the TLS instance.
  70   @param[in, out]  FragmentTable  Pointer to a list of fragment.
  71                                   On input these fragments contain the TLS header and
  72                                   cipher text TLS payload;
  73                                   On output these fragments contain the TLS header and
  74                                   plain text TLS payload.
  75   @param[in]       FragmentCount  Number of fragment.
  76
  77   @retval EFI_SUCCESS             The operation completed successfully.
  78   @retval EFI_OUT_OF_RESOURCES    Can't allocate memory resources.
  79   @retval EFI_ABORTED             TLS session state is incorrect.
  80   @retval Others                  Other errors as indicated.
  81 **/
  82 EFI_STATUS
  83 TlsDecryptPacket (
  84   IN     TLS_INSTANCE                  *TlsInstance,
  85   IN OUT EFI_TLS_FRAGMENT_DATA         **FragmentTable,
  86   IN     UINT32                        *FragmentCount
  87   );
  88
  89 /**
  90   Set TLS session data.
  91
  92   The SetSessionData() function set data for a new TLS session. All session data should
  93   be set before BuildResponsePacket() invoked.
  94
  95   @param[in]  This                Pointer to the EFI_TLS_PROTOCOL instance.
  96   @param[in]  DataType            TLS session data type.
  97   @param[in]  Data                Pointer to session data.
  98   @param[in]  DataSize            Total size of session data.
  99
 100   @retval EFI_SUCCESS             The TLS session data is set successfully.
 101   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 102                                   This is NULL.
 103                                   Data is NULL.
 104                                   DataSize is 0.
 105   @retval EFI_UNSUPPORTED         The DataType is unsupported.
 106   @retval EFI_ACCESS_DENIED       If the DataType is one of below:
 107                                   EfiTlsClientRandom
 108                                   EfiTlsServerRandom
 109                                   EfiTlsKeyMaterial
 110   @retval EFI_NOT_READY           Current TLS session state is NOT
 111                                   EfiTlsSessionStateNotStarted.
 112   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.
 113 **/
 114 EFI_STATUS
 115 EFIAPI
 116 TlsSetSessionData (
 117   IN     EFI_TLS_PROTOCOL              *This,
 118   IN     EFI_TLS_SESSION_DATA_TYPE     DataType,
 119   IN     VOID                          *Data,
 120   IN     UINTN                         DataSize
 121   );
 122
 123 /**
 124   Get TLS session data.
 125
 126   The GetSessionData() function return the TLS session information.
 127
 128   @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.
 129   @param[in]       DataType       TLS session data type.
 130   @param[in, out]  Data           Pointer to session data.
 131   @param[in, out]  DataSize       Total size of session data. On input, it means
 132                                   the size of Data buffer. On output, it means the size
 133                                   of copied Data buffer if EFI_SUCCESS, and means the
 134                                   size of desired Data buffer if EFI_BUFFER_TOO_SMALL.
 135
 136   @retval EFI_SUCCESS             The TLS session data is got successfully.
 137   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 138                                   This is NULL.
 139                                   DataSize is NULL.
 140                                   Data is NULL if *DataSize is not zero.
 141   @retval EFI_UNSUPPORTED         The DataType is unsupported.
 142   @retval EFI_NOT_FOUND           The TLS session data is not found.
 143   @retval EFI_NOT_READY           The DataType is not ready in current session state.
 144   @retval EFI_BUFFER_TOO_SMALL    The buffer is too small to hold the data.
 145 **/
 146 EFI_STATUS
 147 EFIAPI
 148 TlsGetSessionData (
 149   IN     EFI_TLS_PROTOCOL              *This,
 150   IN     EFI_TLS_SESSION_DATA_TYPE     DataType,
 151   IN OUT VOID                          *Data,  OPTIONAL
 152   IN OUT UINTN                         *DataSize
 153   );
 154
 155 /**
 156   Build response packet according to TLS state machine. This function is only valid for
 157   alert, handshake and change_cipher_spec content type.
 158
 159   The BuildResponsePacket() function builds TLS response packet in response to the TLS
 160   request packet specified by RequestBuffer and RequestSize. If RequestBuffer is NULL and
 161   RequestSize is 0, and TLS session status is EfiTlsSessionNotStarted, the TLS session
 162   will be initiated and the response packet needs to be ClientHello. If RequestBuffer is
 163   NULL and RequestSize is 0, and TLS session status is EfiTlsSessionClosing, the TLS
 164   session will be closed and response packet needs to be CloseNotify. If RequestBuffer is
 165   NULL and RequestSize is 0, and TLS session status is EfiTlsSessionError, the TLS
 166   session has errors and the response packet needs to be Alert message based on error
 167   type.
 168
 169   @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.
 170   @param[in]       RequestBuffer  Pointer to the most recently received TLS packet. NULL
 171                                   means TLS need initiate the TLS session and response
 172                                   packet need to be ClientHello.
 173   @param[in]       RequestSize    Packet size in bytes for the most recently received TLS
 174                                   packet. 0 is only valid when RequestBuffer is NULL.
 175   @param[out]      Buffer         Pointer to the buffer to hold the built packet.
 176   @param[in, out]  BufferSize     Pointer to the buffer size in bytes. On input, it is
 177                                   the buffer size provided by the caller. On output, it
 178                                   is the buffer size in fact needed to contain the
 179                                   packet.
 180
 181   @retval EFI_SUCCESS             The required TLS packet is built successfully.
 182   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 183                                   This is NULL.
 184                                   RequestBuffer is NULL but RequestSize is NOT 0.
 185                                   RequestSize is 0 but RequestBuffer is NOT NULL.
 186                                   BufferSize is NULL.
 187                                   Buffer is NULL if *BufferSize is not zero.
 188   @retval EFI_BUFFER_TOO_SMALL    BufferSize is too small to hold the response packet.
 189   @retval EFI_NOT_READY           Current TLS session state is NOT ready to build
 190                                   ResponsePacket.
 191   @retval EFI_ABORTED             Something wrong build response packet.
 192 **/
 193 EFI_STATUS
 194 EFIAPI
 195 TlsBuildResponsePacket (
 196   IN     EFI_TLS_PROTOCOL              *This,
 197   IN     UINT8                         *RequestBuffer, OPTIONAL
 198   IN     UINTN                         RequestSize, OPTIONAL
 199      OUT UINT8                         *Buffer, OPTIONAL
 200   IN OUT UINTN                         *BufferSize
 201   );
 202
 203 /**
 204   Decrypt or encrypt TLS packet during session. This function is only valid after
 205   session connected and for application_data content type.
 206
 207   The ProcessPacket () function process each inbound or outbound TLS APP packet.
 208
 209   @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.
 210   @param[in, out]  FragmentTable  Pointer to a list of fragment. The caller will take
 211                                   responsible to handle the original FragmentTable while
 212                                   it may be reallocated in TLS driver. If CryptMode is
 213                                   EfiTlsEncrypt, on input these fragments contain the TLS
 214                                   header and plain text TLS APP payload; on output these
 215                                   fragments contain the TLS header and cipher text TLS
 216                                   APP payload. If CryptMode is EfiTlsDecrypt, on input
 217                                   these fragments contain the TLS header and cipher text
 218                                   TLS APP payload; on output these fragments contain the
 219                                   TLS header and plain text TLS APP payload.
 220   @param[in]       FragmentCount  Number of fragment.
 221   @param[in]       CryptMode      Crypt mode.
 222
 223   @retval EFI_SUCCESS             The operation completed successfully.
 224   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 225                                   This is NULL.
 226                                   FragmentTable is NULL.
 227                                   FragmentCount is NULL.
 228                                   CryptoMode is invalid.
 229   @retval EFI_NOT_READY           Current TLS session state is NOT
 230                                   EfiTlsSessionDataTransferring.
 231   @retval EFI_ABORTED             Something wrong decryption the message. TLS session
 232                                   status will become EfiTlsSessionError. The caller need
 233                                   call BuildResponsePacket() to generate Error Alert
 234                                   message and send it out.
 235   @retval EFI_OUT_OF_RESOURCES    No enough resource to finish the operation.
 236 **/
 237 EFI_STATUS
 238 EFIAPI
 239 TlsProcessPacket (
 240   IN     EFI_TLS_PROTOCOL              *This,
 241   IN OUT EFI_TLS_FRAGMENT_DATA         **FragmentTable,
 242   IN     UINT32                        *FragmentCount,
 243   IN     EFI_TLS_CRYPT_MODE            CryptMode
 244   );
 245
 246 /**
 247   Set TLS configuration data.
 248
 249   The SetData() function sets TLS configuration to non-volatile storage or volatile
 250   storage.
 251
 252   @param[in]  This                Pointer to the EFI_TLS_CONFIGURATION_PROTOCOL instance.
 253   @param[in]  DataType            Configuration data type.
 254   @param[in]  Data                Pointer to configuration data.
 255   @param[in]  DataSize            Total size of configuration data.
 256
 257   @retval EFI_SUCCESS             The TLS configuration data is set successfully.
 258   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 259                                   This is NULL.
 260                                   Data is NULL.
 261                                   DataSize is 0.
 262   @retval EFI_UNSUPPORTED         The DataType is unsupported.
 263   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.
 264 **/
 265 EFI_STATUS
 266 EFIAPI
 267 TlsConfigurationSetData (
 268   IN     EFI_TLS_CONFIGURATION_PROTOCOL  *This,
 269   IN     EFI_TLS_CONFIG_DATA_TYPE        DataType,
 270   IN     VOID                            *Data,
 271   IN     UINTN                           DataSize
 272   );
 273
 274 /**
 275   Get TLS configuration data.
 276
 277   The GetData() function gets TLS configuration.
 278
 279   @param[in]       This           Pointer to the EFI_TLS_CONFIGURATION_PROTOCOL instance.
 280   @param[in]       DataType       Configuration data type.
 281   @param[in, out]  Data           Pointer to configuration data.
 282   @param[in, out]  DataSize       Total size of configuration data. On input, it means
 283                                   the size of Data buffer. On output, it means the size
 284                                   of copied Data buffer if EFI_SUCCESS, and means the
 285                                   size of desired Data buffer if EFI_BUFFER_TOO_SMALL.
 286
 287   @retval EFI_SUCCESS             The TLS configuration data is got successfully.
 288   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 289                                   This is NULL.
 290                                   DataSize is NULL.
 291                                   Data is NULL if *DataSize is not zero.
 292   @retval EFI_UNSUPPORTED         The DataType is unsupported.
 293   @retval EFI_NOT_FOUND           The TLS configuration data is not found.
 294   @retval EFI_BUFFER_TOO_SMALL    The buffer is too small to hold the data.
 295 **/
 296 EFI_STATUS
 297 EFIAPI
 298 TlsConfigurationGetData (
 299   IN     EFI_TLS_CONFIGURATION_PROTOCOL  *This,
 300   IN     EFI_TLS_CONFIG_DATA_TYPE        DataType,
 301   IN OUT VOID                            *Data, OPTIONAL
 302   IN OUT UINTN                           *DataSize
 303   );
 304
 305 #endif
 306