MdePkg/Include/Protocol/Tls.h

   1 /** @file
   2   EFI TLS Protocols as defined in UEFI 2.5.
   3
   4   The EFI TLS Service Binding Protocol is used to locate EFI TLS Protocol drivers
   5   to create and destroy child of the driver to communicate with other host using
   6   TLS protocol.
   7   The EFI TLS Protocol provides the ability to manage TLS session.
   8
   9   Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>
  10   SPDX-License-Identifier: BSD-2-Clause-Patent
  11
  12   @par Revision Reference:
  13   This Protocol is introduced in UEFI Specification 2.5
  14
  15 **/
  16
  17 #ifndef __EFI_TLS_PROTOCOL_H__
  18 #define __EFI_TLS_PROTOCOL_H__
  19
  20 ///
  21 /// The EFI TLS Service Binding Protocol is used to locate EFI TLS Protocol drivers to
  22 /// create and destroy child of the driver to communicate with other host using TLS
  23 /// protocol.
  24 ///
  25 #define EFI_TLS_SERVICE_BINDING_PROTOCOL_GUID \
  26   { \
  27     0x952cb795, 0xff36, 0x48cf, {0xa2, 0x49, 0x4d, 0xf4, 0x86, 0xd6, 0xab, 0x8d } \
  28   }
  29
  30 ///
  31 /// The EFI TLS protocol provides the ability to manage TLS session.
  32 ///
  33 #define EFI_TLS_PROTOCOL_GUID \
  34   { \
  35     0xca959f, 0x6cfa, 0x4db1, {0x95, 0xbc, 0xe4, 0x6c, 0x47, 0x51, 0x43, 0x90 } \
  36   }
  37
  38 typedef struct _EFI_TLS_PROTOCOL EFI_TLS_PROTOCOL;
  39
  40 ///
  41 /// EFI_TLS_SESSION_DATA_TYPE
  42 ///
  43 typedef enum {
  44   ///
  45   /// Session Configuration
  46   ///
  47
  48   ///
  49   /// TLS session Version. The corresponding Data is of type EFI_TLS_VERSION.
  50   ///
  51   EfiTlsVersion,
  52   ///
  53   /// TLS session as client or as server. The corresponding Data is of
  54   /// EFI_TLS_CONNECTION_END.
  55   ///
  56   EfiTlsConnectionEnd,
  57   ///
  58   /// A priority list of preferred algorithms for the TLS session.
  59   /// The corresponding Data is a list of EFI_TLS_CIPHER.
  60   ///
  61   EfiTlsCipherList,
  62   ///
  63   /// TLS session compression method.
  64   /// The corresponding Data is of type EFI_TLS_COMPRESSION.
  65   ///
  66   EfiTlsCompressionMethod,
  67   ///
  68   /// TLS session extension data.
  69   /// The corresponding Data is a list of type EFI_TLS_EXTENSION .
  70   ///
  71   EfiTlsExtensionData,
  72   ///
  73   /// TLS session verify method.
  74   /// The corresponding Data is of type EFI_TLS_VERIFY.
  75   ///
  76   EfiTlsVerifyMethod,
  77   ///
  78   /// TLS session data session ID.
  79   /// For SetSessionData(), it is TLS session ID used for session resumption.
  80   /// For GetSessionData(), it is the TLS session ID used for current session.
  81   /// The corresponding Data is of type EFI_TLS_SESSION_ID.
  82   ///
  83   EfiTlsSessionID,
  84   ///
  85   /// TLS session data session state.
  86   /// The corresponding Data is of type EFI_TLS_SESSION_STATE.
  87   ///
  88   EfiTlsSessionState,
  89
  90   ///
  91   /// Session information
  92   ///
  93
  94   ///
  95   /// TLS session data client random.
  96   /// The corresponding Data is of type EFI_TLS_RANDOM.
  97   ///
  98   EfiTlsClientRandom,
  99   ///
 100   /// TLS session data server random.
 101   /// The corresponding Data is of type EFI_TLS_RANDOM.
 102   ///
 103   EfiTlsServerRandom,
 104   ///
 105   /// TLS session data key material.
 106   /// The corresponding Data is of type EFI_TLS_MASTER_SECRET.
 107   ///
 108   EfiTlsKeyMaterial,
 109
 110   EfiTlsSessionDataTypeMaximum
 111
 112 } EFI_TLS_SESSION_DATA_TYPE;
 113
 114 ///
 115 /// EFI_TLS_VERSION
 116 /// Note: The TLS version definition is from SSL3.0 to the latest TLS (e.g. 1.2).
 117 ///       SSL2.0 is obsolete and should not be used.
 118 ///
 119 typedef struct {
 120   UINT8                         Major;
 121   UINT8                         Minor;
 122 } EFI_TLS_VERSION;
 123
 124 ///
 125 /// EFI_TLS_CONNECTION_END to define TLS session as client or server.
 126 ///
 127 typedef enum {
 128   EfiTlsClient,
 129   EfiTlsServer,
 130 } EFI_TLS_CONNECTION_END;
 131
 132 ///
 133 /// EFI_TLS_CIPHER
 134 /// Note: The definition of EFI_TLS_CIPHER definition is from "RFC 5246, A.4.1.
 135 ///       Hello Messages". The value of EFI_TLS_CIPHER is from TLS Cipher
 136 ///       Suite Registry of IANA.
 137 ///
 138 #pragma pack (1)
 139 typedef struct {
 140   UINT8                         Data1;
 141   UINT8                         Data2;
 142 } EFI_TLS_CIPHER;
 143 #pragma pack ()
 144
 145 ///
 146 /// EFI_TLS_COMPRESSION
 147 /// Note: The value of EFI_TLS_COMPRESSION definition is from "RFC 3749".
 148 ///
 149 typedef UINT8 EFI_TLS_COMPRESSION;
 150
 151 ///
 152 /// EFI_TLS_EXTENSION
 153 /// Note: The definition of EFI_TLS_EXTENSION if from "RFC 5246 A.4.1.
 154 ///       Hello Messages".
 155 ///
 156 #pragma pack (1)
 157 typedef struct {
 158   UINT16                        ExtensionType;
 159   UINT16                        Length;
 160   UINT8                         Data[1];
 161 } EFI_TLS_EXTENSION;
 162 #pragma pack ()
 163
 164 ///
 165 /// EFI_TLS_VERIFY
 166 /// Use either EFI_TLS_VERIFY_NONE or EFI_TLS_VERIFY_PEER, the last two options
 167 /// are 'ORed' with EFI_TLS_VERIFY_PEER if they are desired.
 168 ///
 169 typedef UINT32  EFI_TLS_VERIFY;
 170 ///
 171 /// No certificates will be sent or the TLS/SSL handshake will be continued regardless
 172 /// of the certificate verification result.
 173 ///
 174 #define EFI_TLS_VERIFY_NONE                  0x0
 175 ///
 176 /// The TLS/SSL handshake is immediately terminated with an alert message containing
 177 /// the reason for the certificate verification failure.
 178 ///
 179 #define EFI_TLS_VERIFY_PEER                  0x1
 180 ///
 181 /// TLS session will fail peer certificate is absent.
 182 ///
 183 #define EFI_TLS_VERIFY_FAIL_IF_NO_PEER_CERT  0x2
 184 ///
 185 /// TLS session only verify client once, and doesn't request certificate during
 186 /// re-negotiation.
 187 ///
 188 #define EFI_TLS_VERIFY_CLIENT_ONCE           0x4
 189
 190 ///
 191 /// EFI_TLS_RANDOM
 192 /// Note: The definition of EFI_TLS_RANDOM is from "RFC 5246 A.4.1.
 193 ///       Hello Messages".
 194 ///
 195 #pragma pack (1)
 196 typedef struct {
 197   UINT32                        GmtUnixTime;
 198   UINT8                         RandomBytes[28];
 199 } EFI_TLS_RANDOM;
 200 #pragma pack ()
 201
 202 ///
 203 /// EFI_TLS_MASTER_SECRET
 204 /// Note: The definition of EFI_TLS_MASTER_SECRET is from "RFC 5246 8.1.
 205 ///       Computing the Master Secret".
 206 ///
 207 #pragma pack (1)
 208 typedef struct {
 209   UINT8                         Data[48];
 210 } EFI_TLS_MASTER_SECRET;
 211 #pragma pack ()
 212
 213 ///
 214 /// EFI_TLS_SESSION_ID
 215 /// Note: The definition of EFI_TLS_SESSION_ID is from "RFC 5246 A.4.1. Hello Messages".
 216 ///
 217 #define MAX_TLS_SESSION_ID_LENGTH  32
 218 #pragma pack (1)
 219 typedef struct {
 220   UINT16                        Length;
 221   UINT8                         Data[MAX_TLS_SESSION_ID_LENGTH];
 222 } EFI_TLS_SESSION_ID;
 223 #pragma pack ()
 224
 225 ///
 226 /// EFI_TLS_SESSION_STATE
 227 ///
 228 typedef enum {
 229   ///
 230   /// When a new child of TLS protocol is created, the initial state of TLS session
 231   /// is EfiTlsSessionNotStarted.
 232   ///
 233   EfiTlsSessionNotStarted,
 234   ///
 235   /// The consumer can call BuildResponsePacket() with NULL to get ClientHello to
 236   /// start the TLS session. Then the status is EfiTlsSessionHandShaking.
 237   ///
 238   EfiTlsSessionHandShaking,
 239   ///
 240   /// During handshake, the consumer need call BuildResponsePacket() with input
 241   /// data from peer, then get response packet and send to peer. After handshake
 242   /// finish, the TLS session status becomes EfiTlsSessionDataTransferring, and
 243   /// consumer can use ProcessPacket() for data transferring.
 244   ///
 245   EfiTlsSessionDataTransferring,
 246   ///
 247   /// Finally, if consumer wants to active close TLS session, consumer need
 248   /// call SetSessionData to set TLS session state to EfiTlsSessionClosing, and
 249   /// call BuildResponsePacket() with NULL to get CloseNotify alert message,
 250   /// and sent it out.
 251   ///
 252   EfiTlsSessionClosing,
 253   ///
 254   /// If any error happen during parsing ApplicationData content type, EFI_ABORT
 255   /// will be returned by ProcessPacket(), and TLS session state will become
 256   /// EfiTlsSessionError. Then consumer need call BuildResponsePacket() with
 257   /// NULL to get alert message and sent it out.
 258   ///
 259   EfiTlsSessionError,
 260
 261   EfiTlsSessionStateMaximum
 262
 263 } EFI_TLS_SESSION_STATE;
 264
 265 ///
 266 /// EFI_TLS_FRAGMENT_DATA
 267 ///
 268 typedef struct {
 269   ///
 270   /// Length of data buffer in the fragment.
 271   ///
 272   UINT32                        FragmentLength;
 273   ///
 274   /// Pointer to the data buffer in the fragment.
 275   ///
 276   VOID                          *FragmentBuffer;
 277 } EFI_TLS_FRAGMENT_DATA;
 278
 279 ///
 280 /// EFI_TLS_CRYPT_MODE
 281 ///
 282 typedef enum {
 283   ///
 284   /// Encrypt data provided in the fragment buffers.
 285   ///
 286   EfiTlsEncrypt,
 287   ///
 288   /// Decrypt data provided in the fragment buffers.
 289   ///
 290   EfiTlsDecrypt,
 291 } EFI_TLS_CRYPT_MODE;
 292
 293 /**
 294   Set TLS session data.
 295
 296   The SetSessionData() function set data for a new TLS session. All session data should
 297   be set before BuildResponsePacket() invoked.
 298
 299   @param[in]  This                Pointer to the EFI_TLS_PROTOCOL instance.
 300   @param[in]  DataType            TLS session data type.
 301   @param[in]  Data                Pointer to session data.
 302   @param[in]  DataSize            Total size of session data.
 303
 304   @retval EFI_SUCCESS             The TLS session data is set successfully.
 305   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 306                                   This is NULL.
 307                                   Data is NULL.
 308                                   DataSize is 0.
 309   @retval EFI_UNSUPPORTED         The DataType is unsupported.
 310   @retval EFI_ACCESS_DENIED       If the DataType is one of below:
 311                                   EfiTlsClientRandom
 312                                   EfiTlsServerRandom
 313                                   EfiTlsKeyMaterial
 314   @retval EFI_NOT_READY           Current TLS session state is NOT
 315                                   EfiTlsSessionStateNotStarted.
 316   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.
 317 **/
 318 typedef
 319 EFI_STATUS
 320 (EFIAPI *EFI_TLS_SET_SESSION_DATA) (
 321   IN EFI_TLS_PROTOCOL                *This,
 322   IN EFI_TLS_SESSION_DATA_TYPE       DataType,
 323   IN VOID                            *Data,
 324   IN UINTN                           DataSize
 325   );
 326
 327 /**
 328   Get TLS session data.
 329
 330   The GetSessionData() function return the TLS session information.
 331
 332   @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.
 333   @param[in]       DataType       TLS session data type.
 334   @param[in, out]  Data           Pointer to session data.
 335   @param[in, out]  DataSize       Total size of session data. On input, it means
 336                                   the size of Data buffer. On output, it means the size
 337                                   of copied Data buffer if EFI_SUCCESS, and means the
 338                                   size of desired Data buffer if EFI_BUFFER_TOO_SMALL.
 339
 340   @retval EFI_SUCCESS             The TLS session data is got successfully.
 341   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 342                                   This is NULL.
 343                                   DataSize is NULL.
 344                                   Data is NULL if *DataSize is not zero.
 345   @retval EFI_UNSUPPORTED         The DataType is unsupported.
 346   @retval EFI_NOT_FOUND           The TLS session data is not found.
 347   @retval EFI_NOT_READY           The DataType is not ready in current session state.
 348   @retval EFI_BUFFER_TOO_SMALL    The buffer is too small to hold the data.
 349 **/
 350 typedef
 351 EFI_STATUS
 352 (EFIAPI *EFI_TLS_GET_SESSION_DATA) (
 353   IN EFI_TLS_PROTOCOL                *This,
 354   IN EFI_TLS_SESSION_DATA_TYPE       DataType,
 355   IN OUT VOID                        *Data,  OPTIONAL
 356   IN OUT UINTN                       *DataSize
 357   );
 358
 359 /**
 360   Build response packet according to TLS state machine. This function is only valid for
 361   alert, handshake and change_cipher_spec content type.
 362
 363   The BuildResponsePacket() function builds TLS response packet in response to the TLS
 364   request packet specified by RequestBuffer and RequestSize. If RequestBuffer is NULL and
 365   RequestSize is 0, and TLS session status is EfiTlsSessionNotStarted, the TLS session
 366   will be initiated and the response packet needs to be ClientHello. If RequestBuffer is
 367   NULL and RequestSize is 0, and TLS session status is EfiTlsSessionClosing, the TLS
 368   session will be closed and response packet needs to be CloseNotify. If RequestBuffer is
 369   NULL and RequestSize is 0, and TLS session status is EfiTlsSessionError, the TLS
 370   session has errors and the response packet needs to be Alert message based on error
 371   type.
 372
 373   @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.
 374   @param[in]       RequestBuffer  Pointer to the most recently received TLS packet. NULL
 375                                   means TLS need initiate the TLS session and response
 376                                   packet need to be ClientHello.
 377   @param[in]       RequestSize    Packet size in bytes for the most recently received TLS
 378                                   packet. 0 is only valid when RequestBuffer is NULL.
 379   @param[out]      Buffer         Pointer to the buffer to hold the built packet.
 380   @param[in, out]  BufferSize     Pointer to the buffer size in bytes. On input, it is
 381                                   the buffer size provided by the caller. On output, it
 382                                   is the buffer size in fact needed to contain the
 383                                   packet.
 384
 385   @retval EFI_SUCCESS             The required TLS packet is built successfully.
 386   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 387                                   This is NULL.
 388                                   RequestBuffer is NULL but RequestSize is NOT 0.
 389                                   RequestSize is 0 but RequestBuffer is NOT NULL.
 390                                   BufferSize is NULL.
 391                                   Buffer is NULL if *BufferSize is not zero.
 392   @retval EFI_BUFFER_TOO_SMALL    BufferSize is too small to hold the response packet.
 393   @retval EFI_NOT_READY           Current TLS session state is NOT ready to build
 394                                   ResponsePacket.
 395   @retval EFI_ABORTED             Something wrong build response packet.
 396 **/
 397 typedef
 398 EFI_STATUS
 399 (EFIAPI *EFI_TLS_BUILD_RESPONSE_PACKET) (
 400   IN EFI_TLS_PROTOCOL                *This,
 401   IN UINT8                           *RequestBuffer, OPTIONAL
 402   IN UINTN                           RequestSize, OPTIONAL
 403   OUT UINT8                          *Buffer, OPTIONAL
 404   IN OUT UINTN                       *BufferSize
 405   );
 406
 407 /**
 408   Decrypt or encrypt TLS packet during session. This function is only valid after
 409   session connected and for application_data content type.
 410
 411   The ProcessPacket () function process each inbound or outbound TLS APP packet.
 412
 413   @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.
 414   @param[in, out]  FragmentTable  Pointer to a list of fragment. The caller will take
 415                                   responsible to handle the original FragmentTable while
 416                                   it may be reallocated in TLS driver. If CryptMode is
 417                                   EfiTlsEncrypt, on input these fragments contain the TLS
 418                                   header and plain text TLS APP payload; on output these
 419                                   fragments contain the TLS header and cipher text TLS
 420                                   APP payload. If CryptMode is EfiTlsDecrypt, on input
 421                                   these fragments contain the TLS header and cipher text
 422                                   TLS APP payload; on output these fragments contain the
 423                                   TLS header and plain text TLS APP payload.
 424   @param[in]       FragmentCount  Number of fragment.
 425   @param[in]       CryptMode      Crypt mode.
 426
 427   @retval EFI_SUCCESS             The operation completed successfully.
 428   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 429                                   This is NULL.
 430                                   FragmentTable is NULL.
 431                                   FragmentCount is NULL.
 432                                   CryptoMode is invalid.
 433   @retval EFI_NOT_READY           Current TLS session state is NOT
 434                                   EfiTlsSessionDataTransferring.
 435   @retval EFI_ABORTED             Something wrong decryption the message. TLS session
 436                                   status will become EfiTlsSessionError. The caller need
 437                                   call BuildResponsePacket() to generate Error Alert
 438                                   message and send it out.
 439   @retval EFI_OUT_OF_RESOURCES    No enough resource to finish the operation.
 440 **/
 441 typedef
 442 EFI_STATUS
 443 (EFIAPI *EFI_TLS_PROCESS_PACKET) (
 444   IN EFI_TLS_PROTOCOL                *This,
 445   IN OUT EFI_TLS_FRAGMENT_DATA       **FragmentTable,
 446   IN UINT32                          *FragmentCount,
 447   IN EFI_TLS_CRYPT_MODE              CryptMode
 448   );
 449
 450 ///
 451 /// The EFI_TLS_PROTOCOL is used to create, destroy and manage TLS session.
 452 /// For detail of TLS, please refer to TLS related RFC.
 453 ///
 454 struct _EFI_TLS_PROTOCOL {
 455   EFI_TLS_SET_SESSION_DATA           SetSessionData;
 456   EFI_TLS_GET_SESSION_DATA           GetSessionData;
 457   EFI_TLS_BUILD_RESPONSE_PACKET      BuildResponsePacket;
 458   EFI_TLS_PROCESS_PACKET             ProcessPacket;
 459 };
 460
 461 extern EFI_GUID gEfiTlsServiceBindingProtocolGuid;
 462 extern EFI_GUID gEfiTlsProtocolGuid;
 463
 464 #endif  // __EFI_TLS_PROTOCOL_H__
 465