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