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   /// TLS session Version. The corresponding Data is of type EFI_TLS_VERSION.
  46   ///
  47   EfiTlsVersion,
  48   ///
  49   /// TLS session as client or as server. The corresponding Data is of
  50   /// EFI_TLS_CONNECTION_END.
  51   ///
  52   EfiTlsConnectionEnd,
  53   ///
  54   /// A priority list of preferred algorithms for the TLS session.
  55   /// The corresponding Data is a list of EFI_TLS_CIPHER.
  56   ///
  57   EfiTlsCipherList,
  58   ///
  59   /// TLS session compression method.
  60   /// The corresponding Data is of type EFI_TLS_COMPRESSION.
  61   ///
  62   EfiTlsCompressionMethod,
  63   ///
  64   /// TLS session extension data.
  65   /// The corresponding Data is a list of type EFI_TLS_EXTENSION .
  66   ///
  67   EfiTlsExtensionData,
  68   ///
  69   /// TLS session verify method.
  70   /// The corresponding Data is of type EFI_TLS_VERIFY.
  71   ///
  72   EfiTlsVerifyMethod,
  73   ///
  74   /// TLS session data session ID.
  75   /// For SetSessionData(), it is TLS session ID used for session resumption.
  76   /// For GetSessionData(), it is the TLS session ID used for current session.
  77   /// The corresponding Data is of type EFI_TLS_SESSION_ID.
  78   ///
  79   EfiTlsSessionID,
  80   ///
  81   /// TLS session data session state.
  82   /// The corresponding Data is of type EFI_TLS_SESSION_STATE.
  83   ///
  84   EfiTlsSessionState,
  85   ///
  86   /// TLS session data client random.
  87   /// The corresponding Data is of type EFI_TLS_RANDOM.
  88   ///
  89   EfiTlsClientRandom,
  90   ///
  91   /// TLS session data server random.
  92   /// The corresponding Data is of type EFI_TLS_RANDOM.
  93   ///
  94   EfiTlsServerRandom,
  95   ///
  96   /// TLS session data key material.
  97   /// The corresponding Data is of type EFI_TLS_MASTER_SECRET.
  98   ///
  99   EfiTlsKeyMaterial,
 100   ///
 101   /// TLS session hostname for validation which is used to verify whether the name
 102   /// within the peer certificate matches a given host name.
 103   /// This parameter is invalid when EfiTlsVerifyMethod is EFI_TLS_VERIFY_NONE.
 104   /// The corresponding Data is of type EFI_TLS_VERIFY_HOST.
 105   ///
 106   EfiTlsVerifyHost,
 107
 108   EfiTlsSessionDataTypeMaximum
 109 } EFI_TLS_SESSION_DATA_TYPE;
 110
 111 ///
 112 /// EFI_TLS_VERSION
 113 /// Note: The TLS version definition is from SSL3.0 to the latest TLS (e.g. 1.2).
 114 ///       SSL2.0 is obsolete and should not be used.
 115 ///
 116 typedef struct {
 117   UINT8    Major;
 118   UINT8    Minor;
 119 } EFI_TLS_VERSION;
 120
 121 ///
 122 /// EFI_TLS_CONNECTION_END to define TLS session as client or server.
 123 ///
 124 typedef enum {
 125   EfiTlsClient,
 126   EfiTlsServer,
 127 } EFI_TLS_CONNECTION_END;
 128
 129 ///
 130 /// EFI_TLS_CIPHER
 131 /// Note: The definition of EFI_TLS_CIPHER definition is from "RFC 5246, A.4.1.
 132 ///       Hello Messages". The value of EFI_TLS_CIPHER is from TLS Cipher
 133 ///       Suite Registry of IANA.
 134 ///
 135 #pragma pack (1)
 136 typedef struct {
 137   UINT8    Data1;
 138   UINT8    Data2;
 139 } EFI_TLS_CIPHER;
 140 #pragma pack ()
 141
 142 ///
 143 /// EFI_TLS_COMPRESSION
 144 /// Note: The value of EFI_TLS_COMPRESSION definition is from "RFC 3749".
 145 ///
 146 typedef UINT8 EFI_TLS_COMPRESSION;
 147
 148 ///
 149 /// EFI_TLS_EXTENSION
 150 /// Note: The definition of EFI_TLS_EXTENSION if from "RFC 5246 A.4.1.
 151 ///       Hello Messages".
 152 ///
 153 #pragma pack (1)
 154 typedef struct {
 155   UINT16    ExtensionType;
 156   UINT16    Length;
 157   UINT8     Data[1];
 158 } EFI_TLS_EXTENSION;
 159 #pragma pack ()
 160
 161 ///
 162 /// EFI_TLS_VERIFY
 163 /// Use either EFI_TLS_VERIFY_NONE or EFI_TLS_VERIFY_PEER, the last two options
 164 /// are 'ORed' with EFI_TLS_VERIFY_PEER if they are desired.
 165 ///
 166 typedef UINT32 EFI_TLS_VERIFY;
 167 ///
 168 /// No certificates will be sent or the TLS/SSL handshake will be continued regardless
 169 /// of the certificate verification result.
 170 ///
 171 #define EFI_TLS_VERIFY_NONE  0x0
 172 ///
 173 /// The TLS/SSL handshake is immediately terminated with an alert message containing
 174 /// the reason for the certificate verification failure.
 175 ///
 176 #define EFI_TLS_VERIFY_PEER  0x1
 177 ///
 178 /// EFI_TLS_VERIFY_FAIL_IF_NO_PEER_CERT is only meaningful in the server mode.
 179 /// TLS session will fail if client certificate is absent.
 180 ///
 181 #define EFI_TLS_VERIFY_FAIL_IF_NO_PEER_CERT  0x2
 182 ///
 183 /// TLS session only verify client once, and doesn't request certificate during
 184 /// re-negotiation.
 185 ///
 186 #define EFI_TLS_VERIFY_CLIENT_ONCE  0x4
 187
 188 ///
 189 /// EFI_TLS_VERIFY_HOST_FLAG
 190 ///
 191 typedef UINT32 EFI_TLS_VERIFY_HOST_FLAG;
 192 ///
 193 /// There is no additional flags set for hostname validation.
 194 /// Wildcards are supported and they match only in the left-most label.
 195 ///
 196 #define EFI_TLS_VERIFY_FLAG_NONE  0x00
 197 ///
 198 /// Always check the Subject Distinguished Name (DN) in the peer certificate even if the
 199 /// certificate contains Subject Alternative Name (SAN).
 200 ///
 201 #define EFI_TLS_VERIFY_FLAG_ALWAYS_CHECK_SUBJECT  0x01
 202 ///
 203 /// Disable the match of all wildcards.
 204 ///
 205 #define EFI_TLS_VERIFY_FLAG_NO_WILDCARDS  0x02
 206 ///
 207 /// Disable the "*" as wildcard in labels that have a prefix or suffix (e.g. "www*" or "*www").
 208 ///
 209 #define EFI_TLS_VERIFY_FLAG_NO_PARTIAL_WILDCARDS  0x04
 210 ///
 211 /// Allow the "*" to match more than one labels. Otherwise, only matches a single label.
 212 ///
 213 #define EFI_TLS_VERIFY_FLAG_MULTI_LABEL_WILDCARDS  0x08
 214 ///
 215 /// Restrict to only match direct child sub-domains which start with ".".
 216 /// For example, a name of ".example.com" would match "www.example.com" with this flag,
 217 /// but would not match "www.sub.example.com".
 218 ///
 219 #define EFI_TLS_VERIFY_FLAG_SINGLE_LABEL_SUBDOMAINS  0x10
 220 ///
 221 /// Never check the Subject Distinguished Name (DN) even there is no
 222 /// Subject Alternative Name (SAN) in the certificate.
 223 ///
 224 #define EFI_TLS_VERIFY_FLAG_NEVER_CHECK_SUBJECT  0x20
 225
 226 ///
 227 /// EFI_TLS_VERIFY_HOST
 228 ///
 229 #pragma pack (1)
 230 typedef struct {
 231   EFI_TLS_VERIFY_HOST_FLAG    Flags;
 232   CHAR8                       *HostName;
 233 } EFI_TLS_VERIFY_HOST;
 234 #pragma pack ()
 235
 236 ///
 237 /// EFI_TLS_RANDOM
 238 /// Note: The definition of EFI_TLS_RANDOM is from "RFC 5246 A.4.1.
 239 ///       Hello Messages".
 240 ///
 241 #pragma pack (1)
 242 typedef struct {
 243   UINT32    GmtUnixTime;
 244   UINT8     RandomBytes[28];
 245 } EFI_TLS_RANDOM;
 246 #pragma pack ()
 247
 248 ///
 249 /// EFI_TLS_MASTER_SECRET
 250 /// Note: The definition of EFI_TLS_MASTER_SECRET is from "RFC 5246 8.1.
 251 ///       Computing the Master Secret".
 252 ///
 253 #pragma pack (1)
 254 typedef struct {
 255   UINT8    Data[48];
 256 } EFI_TLS_MASTER_SECRET;
 257 #pragma pack ()
 258
 259 ///
 260 /// EFI_TLS_SESSION_ID
 261 /// Note: The definition of EFI_TLS_SESSION_ID is from "RFC 5246 A.4.1. Hello Messages".
 262 ///
 263 #define MAX_TLS_SESSION_ID_LENGTH  32
 264 #pragma pack (1)
 265 typedef struct {
 266   UINT16    Length;
 267   UINT8     Data[MAX_TLS_SESSION_ID_LENGTH];
 268 } EFI_TLS_SESSION_ID;
 269 #pragma pack ()
 270
 271 ///
 272 /// EFI_TLS_SESSION_STATE
 273 ///
 274 typedef enum {
 275   ///
 276   /// When a new child of TLS protocol is created, the initial state of TLS session
 277   /// is EfiTlsSessionNotStarted.
 278   ///
 279   EfiTlsSessionNotStarted,
 280   ///
 281   /// The consumer can call BuildResponsePacket() with NULL to get ClientHello to
 282   /// start the TLS session. Then the status is EfiTlsSessionHandShaking.
 283   ///
 284   EfiTlsSessionHandShaking,
 285   ///
 286   /// During handshake, the consumer need call BuildResponsePacket() with input
 287   /// data from peer, then get response packet and send to peer. After handshake
 288   /// finish, the TLS session status becomes EfiTlsSessionDataTransferring, and
 289   /// consumer can use ProcessPacket() for data transferring.
 290   ///
 291   EfiTlsSessionDataTransferring,
 292   ///
 293   /// Finally, if consumer wants to active close TLS session, consumer need
 294   /// call SetSessionData to set TLS session state to EfiTlsSessionClosing, and
 295   /// call BuildResponsePacket() with NULL to get CloseNotify alert message,
 296   /// and sent it out.
 297   ///
 298   EfiTlsSessionClosing,
 299   ///
 300   /// If any error happen during parsing ApplicationData content type, EFI_ABORT
 301   /// will be returned by ProcessPacket(), and TLS session state will become
 302   /// EfiTlsSessionError. Then consumer need call BuildResponsePacket() with
 303   /// NULL to get alert message and sent it out.
 304   ///
 305   EfiTlsSessionError,
 306
 307   EfiTlsSessionStateMaximum
 308 } EFI_TLS_SESSION_STATE;
 309
 310 ///
 311 /// EFI_TLS_FRAGMENT_DATA
 312 ///
 313 typedef struct {
 314   ///
 315   /// Length of data buffer in the fragment.
 316   ///
 317   UINT32    FragmentLength;
 318   ///
 319   /// Pointer to the data buffer in the fragment.
 320   ///
 321   VOID      *FragmentBuffer;
 322 } EFI_TLS_FRAGMENT_DATA;
 323
 324 ///
 325 /// EFI_TLS_CRYPT_MODE
 326 ///
 327 typedef enum {
 328   ///
 329   /// Encrypt data provided in the fragment buffers.
 330   ///
 331   EfiTlsEncrypt,
 332   ///
 333   /// Decrypt data provided in the fragment buffers.
 334   ///
 335   EfiTlsDecrypt,
 336 } EFI_TLS_CRYPT_MODE;
 337
 338 /**
 339   Set TLS session data.
 340
 341   The SetSessionData() function set data for a new TLS session. All session data should
 342   be set before BuildResponsePacket() invoked.
 343
 344   @param[in]  This                Pointer to the EFI_TLS_PROTOCOL instance.
 345   @param[in]  DataType            TLS session data type.
 346   @param[in]  Data                Pointer to session data.
 347   @param[in]  DataSize            Total size of session data.
 348
 349   @retval EFI_SUCCESS             The TLS session data is set successfully.
 350   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 351                                   This is NULL.
 352                                   Data is NULL.
 353                                   DataSize is 0.
 354   @retval EFI_UNSUPPORTED         The DataType is unsupported.
 355   @retval EFI_ACCESS_DENIED       If the DataType is one of below:
 356                                   EfiTlsClientRandom
 357                                   EfiTlsServerRandom
 358                                   EfiTlsKeyMaterial
 359   @retval EFI_NOT_READY           Current TLS session state is NOT
 360                                   EfiTlsSessionStateNotStarted.
 361   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.
 362 **/
 363 typedef
 364 EFI_STATUS
 365 (EFIAPI *EFI_TLS_SET_SESSION_DATA)(
 366   IN EFI_TLS_PROTOCOL                *This,
 367   IN EFI_TLS_SESSION_DATA_TYPE       DataType,
 368   IN VOID                            *Data,
 369   IN UINTN                           DataSize
 370   );
 371
 372 /**
 373   Get TLS session data.
 374
 375   The GetSessionData() function return the TLS session information.
 376
 377   @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.
 378   @param[in]       DataType       TLS session data type.
 379   @param[in, out]  Data           Pointer to session data.
 380   @param[in, out]  DataSize       Total size of session data. On input, it means
 381                                   the size of Data buffer. On output, it means the size
 382                                   of copied Data buffer if EFI_SUCCESS, and means the
 383                                   size of desired Data buffer if EFI_BUFFER_TOO_SMALL.
 384
 385   @retval EFI_SUCCESS             The TLS session data is got successfully.
 386   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 387                                   This is NULL.
 388                                   DataSize is NULL.
 389                                   Data is NULL if *DataSize is not zero.
 390   @retval EFI_UNSUPPORTED         The DataType is unsupported.
 391   @retval EFI_NOT_FOUND           The TLS session data is not found.
 392   @retval EFI_NOT_READY           The DataType is not ready in current session state.
 393   @retval EFI_BUFFER_TOO_SMALL    The buffer is too small to hold the data.
 394 **/
 395 typedef
 396 EFI_STATUS
 397 (EFIAPI *EFI_TLS_GET_SESSION_DATA)(
 398   IN EFI_TLS_PROTOCOL                *This,
 399   IN EFI_TLS_SESSION_DATA_TYPE       DataType,
 400   IN OUT VOID                        *Data   OPTIONAL,
 401   IN OUT UINTN                       *DataSize
 402   );
 403
 404 /**
 405   Build response packet according to TLS state machine. This function is only valid for
 406   alert, handshake and change_cipher_spec content type.
 407
 408   The BuildResponsePacket() function builds TLS response packet in response to the TLS
 409   request packet specified by RequestBuffer and RequestSize. If RequestBuffer is NULL and
 410   RequestSize is 0, and TLS session status is EfiTlsSessionNotStarted, the TLS session
 411   will be initiated and the response packet needs to be ClientHello. If RequestBuffer is
 412   NULL and RequestSize is 0, and TLS session status is EfiTlsSessionClosing, the TLS
 413   session will be closed and response packet needs to be CloseNotify. If RequestBuffer is
 414   NULL and RequestSize is 0, and TLS session status is EfiTlsSessionError, the TLS
 415   session has errors and the response packet needs to be Alert message based on error
 416   type.
 417
 418   @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.
 419   @param[in]       RequestBuffer  Pointer to the most recently received TLS packet. NULL
 420                                   means TLS need initiate the TLS session and response
 421                                   packet need to be ClientHello.
 422   @param[in]       RequestSize    Packet size in bytes for the most recently received TLS
 423                                   packet. 0 is only valid when RequestBuffer is NULL.
 424   @param[out]      Buffer         Pointer to the buffer to hold the built packet.
 425   @param[in, out]  BufferSize     Pointer to the buffer size in bytes. On input, it is
 426                                   the buffer size provided by the caller. On output, it
 427                                   is the buffer size in fact needed to contain the
 428                                   packet.
 429
 430   @retval EFI_SUCCESS             The required TLS packet is built successfully.
 431   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 432                                   This is NULL.
 433                                   RequestBuffer is NULL but RequestSize is NOT 0.
 434                                   RequestSize is 0 but RequestBuffer is NOT NULL.
 435                                   BufferSize is NULL.
 436                                   Buffer is NULL if *BufferSize is not zero.
 437   @retval EFI_BUFFER_TOO_SMALL    BufferSize is too small to hold the response packet.
 438   @retval EFI_NOT_READY           Current TLS session state is NOT ready to build
 439                                   ResponsePacket.
 440   @retval EFI_ABORTED             Something wrong build response packet.
 441 **/
 442 typedef
 443 EFI_STATUS
 444 (EFIAPI *EFI_TLS_BUILD_RESPONSE_PACKET)(
 445   IN EFI_TLS_PROTOCOL                *This,
 446   IN UINT8                           *RequestBuffer  OPTIONAL,
 447   IN UINTN                           RequestSize  OPTIONAL,
 448   OUT UINT8                          *Buffer  OPTIONAL,
 449   IN OUT UINTN                       *BufferSize
 450   );
 451
 452 /**
 453   Decrypt or encrypt TLS packet during session. This function is only valid after
 454   session connected and for application_data content type.
 455
 456   The ProcessPacket () function process each inbound or outbound TLS APP packet.
 457
 458   @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.
 459   @param[in, out]  FragmentTable  Pointer to a list of fragment. The caller will take
 460                                   responsible to handle the original FragmentTable while
 461                                   it may be reallocated in TLS driver. If CryptMode is
 462                                   EfiTlsEncrypt, on input these fragments contain the TLS
 463                                   header and plain text TLS APP payload; on output these
 464                                   fragments contain the TLS header and cipher text TLS
 465                                   APP payload. If CryptMode is EfiTlsDecrypt, on input
 466                                   these fragments contain the TLS header and cipher text
 467                                   TLS APP payload; on output these fragments contain the
 468                                   TLS header and plain text TLS APP payload.
 469   @param[in]       FragmentCount  Number of fragment.
 470   @param[in]       CryptMode      Crypt mode.
 471
 472   @retval EFI_SUCCESS             The operation completed successfully.
 473   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 474                                   This is NULL.
 475                                   FragmentTable is NULL.
 476                                   FragmentCount is NULL.
 477                                   CryptoMode is invalid.
 478   @retval EFI_NOT_READY           Current TLS session state is NOT
 479                                   EfiTlsSessionDataTransferring.
 480   @retval EFI_ABORTED             Something wrong decryption the message. TLS session
 481                                   status will become EfiTlsSessionError. The caller need
 482                                   call BuildResponsePacket() to generate Error Alert
 483                                   message and send it out.
 484   @retval EFI_OUT_OF_RESOURCES    No enough resource to finish the operation.
 485 **/
 486 typedef
 487 EFI_STATUS
 488 (EFIAPI *EFI_TLS_PROCESS_PACKET)(
 489   IN EFI_TLS_PROTOCOL                *This,
 490   IN OUT EFI_TLS_FRAGMENT_DATA       **FragmentTable,
 491   IN UINT32                          *FragmentCount,
 492   IN EFI_TLS_CRYPT_MODE              CryptMode
 493   );
 494
 495 ///
 496 /// The EFI_TLS_PROTOCOL is used to create, destroy and manage TLS session.
 497 /// For detail of TLS, please refer to TLS related RFC.
 498 ///
 499 struct _EFI_TLS_PROTOCOL {
 500   EFI_TLS_SET_SESSION_DATA         SetSessionData;
 501   EFI_TLS_GET_SESSION_DATA         GetSessionData;
 502   EFI_TLS_BUILD_RESPONSE_PACKET    BuildResponsePacket;
 503   EFI_TLS_PROCESS_PACKET           ProcessPacket;
 504 };
 505
 506 extern EFI_GUID  gEfiTlsServiceBindingProtocolGuid;
 507 extern EFI_GUID  gEfiTlsProtocolGuid;
 508
 509 #endif // __EFI_TLS_PROTOCOL_H__