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