NetworkPkg/TlsDxe/TlsImpl.h

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