[mirror_edk2.git] / MdePkg / Include / Protocol / Tls.h

/** @file
  EFI TLS Protocols as defined in UEFI 2.5.

  The EFI TLS Service Binding Protocol is used to locate EFI TLS Protocol drivers
  to create and destroy child of the driver to communicate with other host using
  TLS protocol.
  The EFI TLS Protocol provides the ability to manage TLS session.

  Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>
  This program and the accompanying materials
  are licensed and made available under the terms and conditions of the BSD License
  which accompanies this distribution. The full text of the license may be found at
  http://opensource.org/licenses/bsd-license.php

  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

  @par Revision Reference:
  This Protocol is introduced in UEFI Specification 2.5

**/

#ifndef __EFI_TLS_PROTOCOL_H__
#define __EFI_TLS_PROTOCOL_H__

///
/// The EFI TLS Service Binding Protocol is used to locate EFI TLS Protocol drivers to
/// create and destroy child of the driver to communicate with other host using TLS
/// protocol.
///
#define EFI_TLS_SERVICE_BINDING_PROTOCOL_GUID \
  { \
    0x952cb795, 0xff36, 0x48cf, {0xa2, 0x49, 0x4d, 0xf4, 0x86, 0xd6, 0xab, 0x8d } \
  }

///
/// The EFI TLS protocol provides the ability to manage TLS session.
///
#define EFI_TLS_PROTOCOL_GUID \
  { \
    0xca959f, 0x6cfa, 0x4db1, {0x95, 0xbc, 0xe4, 0x6c, 0x47, 0x51, 0x43, 0x90 } \
  }

typedef struct _EFI_TLS_PROTOCOL EFI_TLS_PROTOCOL;

///
/// EFI_TLS_SESSION_DATA_TYPE
///
typedef enum {
  ///
  /// Session Configuration
  ///

  ///
  /// TLS session Version. The corresponding Data is of type EFI_TLS_VERSION.
  ///
  EfiTlsVersion,
  ///
  /// TLS session as client or as server. The corresponding Data is of
  /// EFI_TLS_CONNECTION_END.
  ///
  EfiTlsConnectionEnd,
  ///
  /// A priority list of preferred algorithms for the TLS session.
  /// The corresponding Data is a list of EFI_TLS_CIPHER.
  ///
  EfiTlsCipherList,
  ///
  /// TLS session compression method.
  /// The corresponding Data is of type EFI_TLS_COMPRESSION.
  ///
  EfiTlsCompressionMethod,
  ///
  /// TLS session extension data.
  /// The corresponding Data is a list of type EFI_TLS_EXTENSION .
  ///
  EfiTlsExtensionData,
  ///
  /// TLS session verify method.
  /// The corresponding Data is of type EFI_TLS_VERIFY.
  ///
  EfiTlsVerifyMethod,
  ///
  /// TLS session data session ID.
  /// For SetSessionData(), it is TLS session ID used for session resumption.
  /// For GetSessionData(), it is the TLS session ID used for current session.
  /// The corresponding Data is of type EFI_TLS_SESSION_ID.
  ///
  EfiTlsSessionID,
  ///
  /// TLS session data session state.
  /// The corresponding Data is of type EFI_TLS_SESSION_STATE.
  ///
  EfiTlsSessionState,

  ///
  /// Session information
  ///

  ///
  /// TLS session data client random.
  /// The corresponding Data is of type EFI_TLS_RANDOM.
  ///
  EfiTlsClientRandom,
  ///
  /// TLS session data server random.
  /// The corresponding Data is of type EFI_TLS_RANDOM.
  ///
  EfiTlsServerRandom,
  ///
  /// TLS session data key material.
  /// The corresponding Data is of type EFI_TLS_MASTER_SECRET.
  ///
  EfiTlsKeyMaterial,

  EfiTlsSessionDataTypeMaximum

} EFI_TLS_SESSION_DATA_TYPE;

///
/// EFI_TLS_VERSION
/// Note: The TLS version definition is from SSL3.0 to the latest TLS (e.g. 1.2).
///       SSL2.0 is obsolete and should not be used.
///
typedef struct {
  UINT8                         Major;
  UINT8                         Minor;
} EFI_TLS_VERSION;

///
/// EFI_TLS_CONNECTION_END to define TLS session as client or server.
///
typedef enum {
  EfiTlsClient,
  EfiTlsServer,
} EFI_TLS_CONNECTION_END;

///
/// EFI_TLS_CIPHER
/// Note: The definition of EFI_TLS_CIPHER definition is from "RFC 5246, A.4.1.
///       Hello Messages". The value of EFI_TLS_CIPHER is from TLS Cipher
///       Suite Registry of IANA.
///
typedef struct {
  UINT8                         Data1;
  UINT8                         Data2;
} EFI_TLS_CIPHER;

///
/// EFI_TLS_COMPRESSION
/// Note: The value of EFI_TLS_COMPRESSION definition is from "RFC 3749".
///
typedef UINT8 EFI_TLS_COMPRESSION;

///
/// EFI_TLS_EXTENSION
/// Note: The definition of EFI_TLS_EXTENSION if from "RFC 5246 A.4.1.
///       Hello Messages".
///
typedef struct {
  UINT16                        ExtensionType;
  UINT16                        Length;
  UINT8                         Data[1];
} EFI_TLS_EXTENSION;

///
/// EFI_TLS_VERIFY
/// Use either EFI_TLS_VERIFY_NONE or EFI_TLS_VERIFY_PEER, the last two options
/// are 'ORed' with EFI_TLS_VERIFY_PEER if they are desired.
///
typedef UINT32  EFI_TLS_VERIFY;
///
/// No certificates will be sent or the TLS/SSL handshake will be continued regardless
/// of the certificate verification result.
///
#define EFI_TLS_VERIFY_NONE                  0x0
///
/// The TLS/SSL handshake is immediately terminated with an alert message containing
/// the reason for the certificate verification failure.
///
#define EFI_TLS_VERIFY_PEER                  0x1
///
/// TLS session will fail peer certificate is absent.
///
#define EFI_TLS_VERIFY_FAIL_IF_NO_PEER_CERT  0x2
///
/// TLS session only verify client once, and doesn't request certificate during
/// re-negotiation.
///
#define EFI_TLS_VERIFY_CLIENT_ONCE           0x4

///
/// EFI_TLS_RANDOM
/// Note: The definition of EFI_TLS_RANDOM is from "RFC 5246 A.4.1.
///       Hello Messages".
///
typedef struct {
  UINT32                        GmtUnixTime;
  UINT8                         RandomBytes[28];
} EFI_TLS_RANDOM;

///
/// EFI_TLS_MASTER_SECRET
/// Note: The definition of EFI_TLS_MASTER_SECRET is from "RFC 5246 8.1.
///       Computing the Master Secret".
///
typedef struct {
  UINT8                         Data[48];
} EFI_TLS_MASTER_SECRET;

///
/// EFI_TLS_SESSION_ID
/// Note: The definition of EFI_TLS_SESSION_ID is from "RFC 5246 A.4.1. Hello Messages".
///
#define MAX_TLS_SESSION_ID_LENGTH  32
typedef struct {
  UINT16                        Length;
  UINT8                         Data[MAX_TLS_SESSION_ID_LENGTH];
} EFI_TLS_SESSION_ID;

///
/// EFI_TLS_SESSION_STATE
///
typedef enum {
  ///
  /// When a new child of TLS protocol is created, the initial state of TLS session
  /// is EfiTlsSessionNotStarted.
  ///
  EfiTlsSessionNotStarted,
  ///
  /// The consumer can call BuildResponsePacket() with NULL to get ClientHello to
  /// start the TLS session. Then the status is EfiTlsSessionHandShaking.
  ///
  EfiTlsSessionHandShaking,
  ///
  /// During handshake, the consumer need call BuildResponsePacket() with input
  /// data from peer, then get response packet and send to peer. After handshake
  /// finish, the TLS session status becomes EfiTlsSessionDataTransferring, and
  /// consumer can use ProcessPacket() for data transferring.
  ///
  EfiTlsSessionDataTransferring,
  ///
  /// Finally, if consumer wants to active close TLS session, consumer need
  /// call SetSessionData to set TLS session state to EfiTlsSessionClosing, and
  /// call BuildResponsePacket() with NULL to get CloseNotify alert message,
  /// and sent it out.
  ///
  EfiTlsSessionClosing,
  ///
  /// If any error happen during parsing ApplicationData content type, EFI_ABORT
  /// will be returned by ProcessPacket(), and TLS session state will become
  /// EfiTlsSessionError. Then consumer need call BuildResponsePacket() with
  /// NULL to get alert message and sent it out.
  ///
  EfiTlsSessionError,

  EfiTlsSessionStateMaximum

} EFI_TLS_SESSION_STATE;

///
/// EFI_TLS_FRAGMENT_DATA
///
typedef struct {
  ///
  /// Length of data buffer in the fragment.
  ///
  UINT32                        FragmentLength;
  ///
  /// Pointer to the data buffer in the fragment.
  ///
  VOID                          *FragmentBuffer;
} EFI_TLS_FRAGMENT_DATA;

///
/// EFI_TLS_CRYPT_MODE
///
typedef enum {
  ///
  /// Encrypt data provided in the fragment buffers.
  ///
  EfiTlsEncrypt,
  ///
  /// Decrypt data provided in the fragment buffers.
  ///
  EfiTlsDecrypt,
} EFI_TLS_CRYPT_MODE;

/**
  Set TLS session data.

  The SetSessionData() function set data for a new TLS session. All session data should
  be set before BuildResponsePacket() invoked.

  @param[in]  This                Pointer to the EFI_TLS_PROTOCOL instance.
  @param[in]  DataType            TLS session data type.
  @param[in]  Data                Pointer to session data.
  @param[in]  DataSize            Total size of session data.

  @retval EFI_SUCCESS             The TLS session data is set successfully.
  @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
                                  This is NULL.
                                  Data is NULL.
                                  DataSize is 0.
  @retval EFI_UNSUPPORTED         The DataType is unsupported.
  @retval EFI_ACCESS_DENIED       If the DataType is one of below:
                                  EfiTlsClientRandom
                                  EfiTlsServerRandom
                                  EfiTlsKeyMaterial
  @retval EFI_NOT_READY           Current TLS session state is NOT
                                  EfiTlsSessionStateNotStarted.
  @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_TLS_SET_SESSION_DATA) (
  IN EFI_TLS_PROTOCOL                *This,
  IN EFI_TLS_SESSION_DATA_TYPE       DataType,
  IN VOID                            *Data,
  IN UINTN                           DataSize
  );

/**
  Get TLS session data.

  The GetSessionData() function return the TLS session information.

  @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.
  @param[in]       DataType       TLS session data type.
  @param[in, out]  Data           Pointer to session data.
  @param[in, out]  DataSize       Total size of session data. On input, it means
                                  the size of Data buffer. On output, it means the size
                                  of copied Data buffer if EFI_SUCCESS, and means the
                                  size of desired Data buffer if EFI_BUFFER_TOO_SMALL.

  @retval EFI_SUCCESS             The TLS session data is got successfully.
  @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
                                  This is NULL.
                                  DataSize is NULL.
                                  Data is NULL if *DataSize is not zero.
  @retval EFI_UNSUPPORTED         The DataType is unsupported.
  @retval EFI_NOT_FOUND           The TLS session data is not found.
  @retval EFI_NOT_READY           The DataType is not ready in current session state.
  @retval EFI_BUFFER_TOO_SMALL    The buffer is too small to hold the data.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_TLS_GET_SESSION_DATA) (
  IN EFI_TLS_PROTOCOL                *This,
  IN EFI_TLS_SESSION_DATA_TYPE       DataType,
  IN OUT VOID                        *Data,  OPTIONAL
  IN OUT UINTN                       *DataSize
  );

/**
  Build response packet according to TLS state machine. This function is only valid for
  alert, handshake and change_cipher_spec content type.

  The BuildResponsePacket() function builds TLS response packet in response to the TLS
  request packet specified by RequestBuffer and RequestSize. If RequestBuffer is NULL and
  RequestSize is 0, and TLS session status is EfiTlsSessionNotStarted, the TLS session
  will be initiated and the response packet needs to be ClientHello. If RequestBuffer is
  NULL and RequestSize is 0, and TLS session status is EfiTlsSessionClosing, the TLS
  session will be closed and response packet needs to be CloseNotify. If RequestBuffer is
  NULL and RequestSize is 0, and TLS session status is EfiTlsSessionError, the TLS
  session has errors and the response packet needs to be Alert message based on error
  type.

  @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.
  @param[in]       RequestBuffer  Pointer to the most recently received TLS packet. NULL
                                  means TLS need initiate the TLS session and response
                                  packet need to be ClientHello.
  @param[in]       RequestSize    Packet size in bytes for the most recently received TLS
                                  packet. 0 is only valid when RequestBuffer is NULL.
  @param[out]      Buffer         Pointer to the buffer to hold the built packet.
  @param[in, out]  BufferSize     Pointer to the buffer size in bytes. On input, it is
                                  the buffer size provided by the caller. On output, it
                                  is the buffer size in fact needed to contain the
                                  packet.

  @retval EFI_SUCCESS             The required TLS packet is built successfully.
  @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
                                  This is NULL.
                                  RequestBuffer is NULL but RequestSize is NOT 0.
                                  RequestSize is 0 but RequestBuffer is NOT NULL.
                                  BufferSize is NULL.
                                  Buffer is NULL if *BufferSize is not zero.
  @retval EFI_BUFFER_TOO_SMALL    BufferSize is too small to hold the response packet.
  @retval EFI_NOT_READY           Current TLS session state is NOT ready to build
                                  ResponsePacket.
  @retval EFI_ABORTED             Something wrong build response packet.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_TLS_BUILD_RESPONSE_PACKET) (
  IN EFI_TLS_PROTOCOL                *This,
  IN UINT8                           *RequestBuffer, OPTIONAL
  IN UINTN                           RequestSize, OPTIONAL
  OUT UINT8                          *Buffer, OPTIONAL
  IN OUT UINTN                       *BufferSize
  );

/**
  Decrypt or encrypt TLS packet during session. This function is only valid after
  session connected and for application_data content type.

  The ProcessPacket () function process each inbound or outbound TLS APP packet.

  @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.
  @param[in, out]  FragmentTable  Pointer to a list of fragment. The caller will take
                                  responsible to handle the original FragmentTable while
                                  it may be reallocated in TLS driver. If CryptMode is
                                  EfiTlsEncrypt, on input these fragments contain the TLS
                                  header and plain text TLS APP payload; on output these
                                  fragments contain the TLS header and cipher text TLS
                                  APP payload. If CryptMode is EfiTlsDecrypt, on input
                                  these fragments contain the TLS header and cipher text
                                  TLS APP payload; on output these fragments contain the
                                  TLS header and plain text TLS APP payload.
  @param[in]       FragmentCount  Number of fragment.
  @param[in]       CryptMode      Crypt mode.

  @retval EFI_SUCCESS             The operation completed successfully.
  @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
                                  This is NULL.
                                  FragmentTable is NULL.
                                  FragmentCount is NULL.
                                  CryptoMode is invalid.
  @retval EFI_NOT_READY           Current TLS session state is NOT
                                  EfiTlsSessionDataTransferring.
  @retval EFI_ABORTED             Something wrong decryption the message. TLS session
                                  status will become EfiTlsSessionError. The caller need
                                  call BuildResponsePacket() to generate Error Alert
                                  message and send it out.
  @retval EFI_OUT_OF_RESOURCES    No enough resource to finish the operation.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_TLS_PROCESS_PACKET) (
  IN EFI_TLS_PROTOCOL                *This,
  IN OUT EFI_TLS_FRAGMENT_DATA       **FragmentTable,
  IN UINT32                          *FragmentCount,
  IN EFI_TLS_CRYPT_MODE              CryptMode
  );

///
/// The EFI_TLS_PROTOCOL is used to create, destroy and manage TLS session.
/// For detail of TLS, please refer to TLS related RFC.
///
struct _EFI_TLS_PROTOCOL {
  EFI_TLS_SET_SESSION_DATA           SetSessionData;
  EFI_TLS_GET_SESSION_DATA           GetSessionData;
  EFI_TLS_BUILD_RESPONSE_PACKET      BuildResponsePacket;
  EFI_TLS_PROCESS_PACKET             ProcessPacket;
};

extern EFI_GUID gEfiTlsServiceBindingProtocolGuid;
extern EFI_GUID gEfiTlsProtocolGuid;

#endif  // __EFI_TLS_PROTOCOL_H__
Commit	Line	Data
	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	typedef struct {
	145	UINT8 Data1;
	146	UINT8 Data2;
	147	} EFI_TLS_CIPHER;
	148
	149	///
	150	/// EFI_TLS_COMPRESSION
	151	/// Note: The value of EFI_TLS_COMPRESSION definition is from "RFC 3749".
	152	///
	153	typedef UINT8 EFI_TLS_COMPRESSION;
	154
	155	///
	156	/// EFI_TLS_EXTENSION
	157	/// Note: The definition of EFI_TLS_EXTENSION if from "RFC 5246 A.4.1.
	158	/// Hello Messages".
	159	///
	160	typedef struct {
	161	UINT16 ExtensionType;
	162	UINT16 Length;
	163	UINT8 Data[1];
	164	} EFI_TLS_EXTENSION;
	165
	166	///
	167	/// EFI_TLS_VERIFY
	168	/// Use either EFI_TLS_VERIFY_NONE or EFI_TLS_VERIFY_PEER, the last two options
	169	/// are 'ORed' with EFI_TLS_VERIFY_PEER if they are desired.
	170	///
	171	typedef UINT32 EFI_TLS_VERIFY;
	172	///
	173	/// No certificates will be sent or the TLS/SSL handshake will be continued regardless
	174	/// of the certificate verification result.
	175	///
	176	#define EFI_TLS_VERIFY_NONE 0x0
	177	///
	178	/// The TLS/SSL handshake is immediately terminated with an alert message containing
	179	/// the reason for the certificate verification failure.
	180	///
	181	#define EFI_TLS_VERIFY_PEER 0x1
	182	///
	183	/// TLS session will fail peer certificate is absent.
	184	///
	185	#define EFI_TLS_VERIFY_FAIL_IF_NO_PEER_CERT 0x2
	186	///
	187	/// TLS session only verify client once, and doesn't request certificate during
	188	/// re-negotiation.
	189	///
	190	#define EFI_TLS_VERIFY_CLIENT_ONCE 0x4
	191
	192	///
	193	/// EFI_TLS_RANDOM
	194	/// Note: The definition of EFI_TLS_RANDOM is from "RFC 5246 A.4.1.
	195	/// Hello Messages".
	196	///
	197	typedef struct {
	198	UINT32 GmtUnixTime;
	199	UINT8 RandomBytes[28];
	200	} EFI_TLS_RANDOM;
	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	typedef struct {
	208	UINT8 Data[48];
	209	} EFI_TLS_MASTER_SECRET;
	210
	211	///
	212	/// EFI_TLS_SESSION_ID
	213	/// Note: The definition of EFI_TLS_SESSION_ID is from "RFC 5246 A.4.1. Hello Messages".
	214	///
	215	#define MAX_TLS_SESSION_ID_LENGTH 32
	216	typedef struct {
	217	UINT16 Length;
	218	UINT8 Data[MAX_TLS_SESSION_ID_LENGTH];
	219	} EFI_TLS_SESSION_ID;
	220
	221	///
	222	/// EFI_TLS_SESSION_STATE
	223	///
	224	typedef enum {
	225	///
	226	/// When a new child of TLS protocol is created, the initial state of TLS session
	227	/// is EfiTlsSessionNotStarted.
	228	///
	229	EfiTlsSessionNotStarted,
	230	///
	231	/// The consumer can call BuildResponsePacket() with NULL to get ClientHello to
	232	/// start the TLS session. Then the status is EfiTlsSessionHandShaking.
	233	///
	234	EfiTlsSessionHandShaking,
	235	///
	236	/// During handshake, the consumer need call BuildResponsePacket() with input
	237	/// data from peer, then get response packet and send to peer. After handshake
	238	/// finish, the TLS session status becomes EfiTlsSessionDataTransferring, and
	239	/// consumer can use ProcessPacket() for data transferring.
	240	///
	241	EfiTlsSessionDataTransferring,
	242	///
	243	/// Finally, if consumer wants to active close TLS session, consumer need
	244	/// call SetSessionData to set TLS session state to EfiTlsSessionClosing, and
	245	/// call BuildResponsePacket() with NULL to get CloseNotify alert message,
	246	/// and sent it out.
	247	///
	248	EfiTlsSessionClosing,
	249	///
	250	/// If any error happen during parsing ApplicationData content type, EFI_ABORT
	251	/// will be returned by ProcessPacket(), and TLS session state will become
	252	/// EfiTlsSessionError. Then consumer need call BuildResponsePacket() with
	253	/// NULL to get alert message and sent it out.
	254	///
	255	EfiTlsSessionError,
	256
	257	EfiTlsSessionStateMaximum
	258
	259	} EFI_TLS_SESSION_STATE;
	260
	261	///
	262	/// EFI_TLS_FRAGMENT_DATA
	263	///
	264	typedef struct {
	265	///
	266	/// Length of data buffer in the fragment.
	267	///
	268	UINT32 FragmentLength;
	269	///
	270	/// Pointer to the data buffer in the fragment.
	271	///
	272	VOID *FragmentBuffer;
	273	} EFI_TLS_FRAGMENT_DATA;
	274
	275	///
	276	/// EFI_TLS_CRYPT_MODE
	277	///
	278	typedef enum {
	279	///
	280	/// Encrypt data provided in the fragment buffers.
	281	///
	282	EfiTlsEncrypt,
	283	///
	284	/// Decrypt data provided in the fragment buffers.
	285	///
	286	EfiTlsDecrypt,
	287	} EFI_TLS_CRYPT_MODE;
	288
	289	/**
	290	Set TLS session data.
	291
	292	The SetSessionData() function set data for a new TLS session. All session data should
	293	be set before BuildResponsePacket() invoked.
	294
	295	@param[in] This Pointer to the EFI_TLS_PROTOCOL instance.
	296	@param[in] DataType TLS session data type.
	297	@param[in] Data Pointer to session data.
	298	@param[in] DataSize Total size of session data.
	299
	300	@retval EFI_SUCCESS The TLS session data is set successfully.
	301	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
	302	This is NULL.
	303	Data is NULL.
	304	DataSize is 0.
	305	@retval EFI_UNSUPPORTED The DataType is unsupported.
	306	@retval EFI_ACCESS_DENIED If the DataType is one of below:
	307	EfiTlsClientRandom
	308	EfiTlsServerRandom
	309	EfiTlsKeyMaterial
	310	@retval EFI_NOT_READY Current TLS session state is NOT
	311	EfiTlsSessionStateNotStarted.
	312	@retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
	313	**/
	314	typedef
	315	EFI_STATUS
	316	(EFIAPI *EFI_TLS_SET_SESSION_DATA) (
	317	IN EFI_TLS_PROTOCOL *This,
	318	IN EFI_TLS_SESSION_DATA_TYPE DataType,
	319	IN VOID *Data,
	320	IN UINTN DataSize
	321	);
	322
	323	/**
	324	Get TLS session data.
	325
	326	The GetSessionData() function return the TLS session information.
	327
	328	@param[in] This Pointer to the EFI_TLS_PROTOCOL instance.
	329	@param[in] DataType TLS session data type.
	330	@param[in, out] Data Pointer to session data.
	331	@param[in, out] DataSize Total size of session data. On input, it means
	332	the size of Data buffer. On output, it means the size
	333	of copied Data buffer if EFI_SUCCESS, and means the
	334	size of desired Data buffer if EFI_BUFFER_TOO_SMALL.
	335
	336	@retval EFI_SUCCESS The TLS session data is got successfully.
	337	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
	338	This is NULL.
	339	DataSize is NULL.
	340	Data is NULL if *DataSize is not zero.
	341	@retval EFI_UNSUPPORTED The DataType is unsupported.
	342	@retval EFI_NOT_FOUND The TLS session data is not found.
	343	@retval EFI_NOT_READY The DataType is not ready in current session state.
	344	@retval EFI_BUFFER_TOO_SMALL The buffer is too small to hold the data.
	345	**/
	346	typedef
	347	EFI_STATUS
	348	(EFIAPI *EFI_TLS_GET_SESSION_DATA) (
	349	IN EFI_TLS_PROTOCOL *This,
	350	IN EFI_TLS_SESSION_DATA_TYPE DataType,
	351	IN OUT VOID *Data, OPTIONAL
	352	IN OUT UINTN *DataSize
	353	);
	354
	355	/**
	356	Build response packet according to TLS state machine. This function is only valid for
	357	alert, handshake and change_cipher_spec content type.
	358
	359	The BuildResponsePacket() function builds TLS response packet in response to the TLS
	360	request packet specified by RequestBuffer and RequestSize. If RequestBuffer is NULL and
	361	RequestSize is 0, and TLS session status is EfiTlsSessionNotStarted, the TLS session
	362	will be initiated and the response packet needs to be ClientHello. If RequestBuffer is
	363	NULL and RequestSize is 0, and TLS session status is EfiTlsSessionClosing, the TLS
	364	session will be closed and response packet needs to be CloseNotify. If RequestBuffer is
	365	NULL and RequestSize is 0, and TLS session status is EfiTlsSessionError, the TLS
	366	session has errors and the response packet needs to be Alert message based on error
	367	type.
	368
	369	@param[in] This Pointer to the EFI_TLS_PROTOCOL instance.
	370	@param[in] RequestBuffer Pointer to the most recently received TLS packet. NULL
	371	means TLS need initiate the TLS session and response
	372	packet need to be ClientHello.
	373	@param[in] RequestSize Packet size in bytes for the most recently received TLS
	374	packet. 0 is only valid when RequestBuffer is NULL.
	375	@param[out] Buffer Pointer to the buffer to hold the built packet.
	376	@param[in, out] BufferSize Pointer to the buffer size in bytes. On input, it is
	377	the buffer size provided by the caller. On output, it
	378	is the buffer size in fact needed to contain the
	379	packet.
	380
	381	@retval EFI_SUCCESS The required TLS packet is built successfully.
	382	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
	383	This is NULL.
	384	RequestBuffer is NULL but RequestSize is NOT 0.
	385	RequestSize is 0 but RequestBuffer is NOT NULL.
	386	BufferSize is NULL.
	387	Buffer is NULL if *BufferSize is not zero.
	388	@retval EFI_BUFFER_TOO_SMALL BufferSize is too small to hold the response packet.
	389	@retval EFI_NOT_READY Current TLS session state is NOT ready to build
	390	ResponsePacket.
	391	@retval EFI_ABORTED Something wrong build response packet.
	392	**/
	393	typedef
	394	EFI_STATUS
	395	(EFIAPI *EFI_TLS_BUILD_RESPONSE_PACKET) (
	396	IN EFI_TLS_PROTOCOL *This,
	397	IN UINT8 *RequestBuffer, OPTIONAL
	398	IN UINTN RequestSize, OPTIONAL
	399	OUT UINT8 *Buffer, OPTIONAL
	400	IN OUT UINTN *BufferSize
	401	);
	402
	403	/**
	404	Decrypt or encrypt TLS packet during session. This function is only valid after
	405	session connected and for application_data content type.
	406
	407	The ProcessPacket () function process each inbound or outbound TLS APP packet.
	408
	409	@param[in] This Pointer to the EFI_TLS_PROTOCOL instance.
	410	@param[in, out] FragmentTable Pointer to a list of fragment. The caller will take
	411	responsible to handle the original FragmentTable while
	412	it may be reallocated in TLS driver. If CryptMode is
	413	EfiTlsEncrypt, on input these fragments contain the TLS
	414	header and plain text TLS APP payload; on output these
	415	fragments contain the TLS header and cipher text TLS
	416	APP payload. If CryptMode is EfiTlsDecrypt, on input
	417	these fragments contain the TLS header and cipher text
	418	TLS APP payload; on output these fragments contain the
	419	TLS header and plain text TLS APP payload.
	420	@param[in] FragmentCount Number of fragment.
	421	@param[in] CryptMode Crypt mode.
	422
	423	@retval EFI_SUCCESS The operation completed successfully.
	424	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
	425	This is NULL.
	426	FragmentTable is NULL.
	427	FragmentCount is NULL.
	428	CryptoMode is invalid.
	429	@retval EFI_NOT_READY Current TLS session state is NOT
	430	EfiTlsSessionDataTransferring.
	431	@retval EFI_ABORTED Something wrong decryption the message. TLS session
	432	status will become EfiTlsSessionError. The caller need
	433	call BuildResponsePacket() to generate Error Alert
	434	message and send it out.
	435	@retval EFI_OUT_OF_RESOURCES No enough resource to finish the operation.
	436	**/
	437	typedef
	438	EFI_STATUS
	439	(EFIAPI *EFI_TLS_PROCESS_PACKET) (
	440	IN EFI_TLS_PROTOCOL *This,
	441	IN OUT EFI_TLS_FRAGMENT_DATA **FragmentTable,
	442	IN UINT32 *FragmentCount,
	443	IN EFI_TLS_CRYPT_MODE CryptMode
	444	);
	445
	446	///
	447	/// The EFI_TLS_PROTOCOL is used to create, destroy and manage TLS session.
	448	/// For detail of TLS, please refer to TLS related RFC.
	449	///
	450	struct _EFI_TLS_PROTOCOL {
	451	EFI_TLS_SET_SESSION_DATA SetSessionData;
	452	EFI_TLS_GET_SESSION_DATA GetSessionData;
	453	EFI_TLS_BUILD_RESPONSE_PACKET BuildResponsePacket;
	454	EFI_TLS_PROCESS_PACKET ProcessPacket;
	455	};
	456
	457	extern EFI_GUID gEfiTlsServiceBindingProtocolGuid;
	458	extern EFI_GUID gEfiTlsProtocolGuid;
	459
	460	#endif // __EFI_TLS_PROTOCOL_H__