Tls.h File Reference

Go to the source code of this file.

Data Structures
struct	EFI_TLS_VERSION
struct	EFI_TLS_CIPHER
struct	EFI_TLS_EXTENSION
struct	EFI_TLS_VERIFY_HOST
struct	EFI_TLS_RANDOM
struct	EFI_TLS_MASTER_SECRET
struct	EFI_TLS_SESSION_ID
struct	EFI_TLS_FRAGMENT_DATA
struct	_EFI_TLS_PROTOCOL

Macros
#define	EFI_TLS_SERVICE_BINDING_PROTOCOL_GUID
#define	EFI_TLS_PROTOCOL_GUID
#define	EFI_TLS_VERIFY_NONE   0x0
#define	EFI_TLS_VERIFY_PEER   0x1
#define	EFI_TLS_VERIFY_FAIL_IF_NO_PEER_CERT   0x2
#define	EFI_TLS_VERIFY_CLIENT_ONCE   0x4
#define	EFI_TLS_VERIFY_FLAG_NONE   0x00
#define	EFI_TLS_VERIFY_FLAG_ALWAYS_CHECK_SUBJECT   0x01
#define	EFI_TLS_VERIFY_FLAG_NO_WILDCARDS   0x02
#define	EFI_TLS_VERIFY_FLAG_NO_PARTIAL_WILDCARDS   0x04
#define	EFI_TLS_VERIFY_FLAG_MULTI_LABEL_WILDCARDS   0x08
#define	EFI_TLS_VERIFY_FLAG_SINGLE_LABEL_SUBDOMAINS   0x10
#define	EFI_TLS_VERIFY_FLAG_NEVER_CHECK_SUBJECT   0x20
#define	MAX_TLS_SESSION_ID_LENGTH   32

Typedefs
typedef struct _EFI_TLS_PROTOCOL	EFI_TLS_PROTOCOL
typedef UINT8	EFI_TLS_COMPRESSION
typedef UINT32	EFI_TLS_VERIFY
typedef UINT32	EFI_TLS_VERIFY_HOST_FLAG
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)
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)
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)
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)

Enumerations
enum	EFI_TLS_SESSION_DATA_TYPE {   EfiTlsVersion , EfiTlsConnectionEnd , EfiTlsCipherList , EfiTlsCompressionMethod ,   EfiTlsExtensionData , EfiTlsVerifyMethod , EfiTlsSessionID , EfiTlsSessionState ,   EfiTlsClientRandom , EfiTlsServerRandom , EfiTlsKeyMaterial , EfiTlsVerifyHost ,   EfiTlsSessionDataTypeMaximum }
enum	EFI_TLS_CONNECTION_END { EfiTlsClient , EfiTlsServer }
enum	EFI_TLS_SESSION_STATE {   EfiTlsSessionNotStarted , EfiTlsSessionHandShaking , EfiTlsSessionDataTransferring , EfiTlsSessionClosing ,   EfiTlsSessionError , EfiTlsSessionStateMaximum }
enum	EFI_TLS_CRYPT_MODE { EfiTlsEncrypt , EfiTlsDecrypt }

Variables
EFI_GUID	gEfiTlsServiceBindingProtocolGuid
EFI_GUID	gEfiTlsProtocolGuid

Detailed Description

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.
SPDX-License-Identifier: BSD-2-Clause-Patent

Revision Reference:

This Protocol is introduced in UEFI Specification 2.5

Definition in file Tls.h.

Macro Definition Documentation

EFI_TLS_PROTOCOL_GUID

#define EFI_TLS_PROTOCOL_GUID

Value:

  { \
    0xca959f, 0x6cfa, 0x4db1, {0x95, 0xbc, 0xe4, 0x6c, 0x47, 0x51, 0x43, 0x90 } \
  }

The EFI TLS protocol provides the ability to manage TLS session.

Definition at line 33 of file Tls.h.

EFI_TLS_SERVICE_BINDING_PROTOCOL_GUID

#define EFI_TLS_SERVICE_BINDING_PROTOCOL_GUID

Value:

  { \
    0x952cb795, 0xff36, 0x48cf, {0xa2, 0x49, 0x4d, 0xf4, 0x86, 0xd6, 0xab, 0x8d } \
  }

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.

Definition at line 25 of file Tls.h.

EFI_TLS_VERIFY_CLIENT_ONCE

#define EFI_TLS_VERIFY_CLIENT_ONCE   0x4

TLS session only verify client once, and doesn't request certificate during re-negotiation.

Definition at line 186 of file Tls.h.

EFI_TLS_VERIFY_FAIL_IF_NO_PEER_CERT

#define EFI_TLS_VERIFY_FAIL_IF_NO_PEER_CERT   0x2

EFI_TLS_VERIFY_FAIL_IF_NO_PEER_CERT is only meaningful in the server mode. TLS session will fail if client certificate is absent.

Definition at line 181 of file Tls.h.

EFI_TLS_VERIFY_FLAG_ALWAYS_CHECK_SUBJECT

#define EFI_TLS_VERIFY_FLAG_ALWAYS_CHECK_SUBJECT   0x01

Always check the Subject Distinguished Name (DN) in the peer certificate even if the certificate contains Subject Alternative Name (SAN).

Definition at line 201 of file Tls.h.

EFI_TLS_VERIFY_FLAG_MULTI_LABEL_WILDCARDS

#define EFI_TLS_VERIFY_FLAG_MULTI_LABEL_WILDCARDS   0x08

Allow the "*" to match more than one labels. Otherwise, only matches a single label.

Definition at line 213 of file Tls.h.

EFI_TLS_VERIFY_FLAG_NEVER_CHECK_SUBJECT

#define EFI_TLS_VERIFY_FLAG_NEVER_CHECK_SUBJECT   0x20

Never check the Subject Distinguished Name (DN) even there is no Subject Alternative Name (SAN) in the certificate.

Definition at line 224 of file Tls.h.

EFI_TLS_VERIFY_FLAG_NO_PARTIAL_WILDCARDS

#define EFI_TLS_VERIFY_FLAG_NO_PARTIAL_WILDCARDS   0x04

Disable the "*" as wildcard in labels that have a prefix or suffix (e.g. "www*" or "*www").

Definition at line 209 of file Tls.h.

EFI_TLS_VERIFY_FLAG_NO_WILDCARDS

#define EFI_TLS_VERIFY_FLAG_NO_WILDCARDS   0x02

Disable the match of all wildcards.

Definition at line 205 of file Tls.h.

EFI_TLS_VERIFY_FLAG_NONE

#define EFI_TLS_VERIFY_FLAG_NONE   0x00

There is no additional flags set for hostname validation. Wildcards are supported and they match only in the left-most label.

Definition at line 196 of file Tls.h.

EFI_TLS_VERIFY_FLAG_SINGLE_LABEL_SUBDOMAINS

#define EFI_TLS_VERIFY_FLAG_SINGLE_LABEL_SUBDOMAINS   0x10

Restrict to only match direct child sub-domains which start with ".". For example, a name of ".example.com" would match "www.example.com" with this flag, but would not match "www.sub.example.com".

Definition at line 219 of file Tls.h.

EFI_TLS_VERIFY_NONE

#define EFI_TLS_VERIFY_NONE   0x0

No certificates will be sent or the TLS/SSL handshake will be continued regardless of the certificate verification result.

Definition at line 171 of file Tls.h.

EFI_TLS_VERIFY_PEER

#define EFI_TLS_VERIFY_PEER   0x1

The TLS/SSL handshake is immediately terminated with an alert message containing the reason for the certificate verification failure.

Definition at line 176 of file Tls.h.

MAX_TLS_SESSION_ID_LENGTH

#define MAX_TLS_SESSION_ID_LENGTH   32

EFI_TLS_SESSION_ID Note: The definition of EFI_TLS_SESSION_ID is from "RFC 5246 A.4.1. Hello Messages".

Definition at line 263 of file Tls.h.

Typedef Documentation

EFI_TLS_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)

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.

Parameters

[in]	This	Pointer to the EFI_TLS_PROTOCOL instance.
[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.
[in]	RequestSize	Packet size in bytes for the most recently received TLS packet. 0 is only valid when RequestBuffer is NULL.
[out]	Buffer	Pointer to the buffer to hold the built packet.
[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.

Return values

EFI_SUCCESS	The required TLS packet is built successfully.
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.
EFI_BUFFER_TOO_SMALL	BufferSize is too small to hold the response packet.
EFI_NOT_READY	Current TLS session state is NOT ready to build ResponsePacket.
EFI_ABORTED	Something wrong build response packet.

Definition at line 443 of file Tls.h.

EFI_TLS_COMPRESSION

typedef UINT8 EFI_TLS_COMPRESSION

EFI_TLS_COMPRESSION Note: The value of EFI_TLS_COMPRESSION definition is from "RFC 3749".

Definition at line 146 of file Tls.h.

EFI_TLS_GET_SESSION_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)

Get TLS session data.

The GetSessionData() function return the TLS session information.

Parameters

[in]	This	Pointer to the EFI_TLS_PROTOCOL instance.
[in]	DataType	TLS session data type.
[in,out]	Data	Pointer to session data.
[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.

Return values

EFI_SUCCESS	The TLS session data is got successfully.
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.
EFI_UNSUPPORTED	The DataType is unsupported.
EFI_NOT_FOUND	The TLS session data is not found.
EFI_NOT_READY	The DataType is not ready in current session state.
EFI_BUFFER_TOO_SMALL	The buffer is too small to hold the data.

Definition at line 396 of file Tls.h.

EFI_TLS_PROCESS_PACKET

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)

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.

Parameters

[in]	This	Pointer to the EFI_TLS_PROTOCOL instance.
[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.
[in]	FragmentCount	Number of fragment.
[in]	CryptMode	Crypt mode.

Return values

EFI_SUCCESS	The operation completed successfully.
EFI_INVALID_PARAMETER	One or more of the following conditions is TRUE: This is NULL. FragmentTable is NULL. FragmentCount is NULL. CryptoMode is invalid.
EFI_NOT_READY	Current TLS session state is NOT EfiTlsSessionDataTransferring.
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.
EFI_OUT_OF_RESOURCES	No enough resource to finish the operation.

Definition at line 487 of file Tls.h.

EFI_TLS_PROTOCOL

typedef struct _EFI_TLS_PROTOCOL EFI_TLS_PROTOCOL

Definition at line 38 of file Tls.h.

EFI_TLS_SET_SESSION_DATA

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)

Set TLS session data.

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

Parameters

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

Return values

EFI_SUCCESS	The TLS session data is set successfully.
EFI_INVALID_PARAMETER	One or more of the following conditions is TRUE: This is NULL. Data is NULL. DataSize is 0.
EFI_UNSUPPORTED	The DataType is unsupported.
EFI_ACCESS_DENIED	If the DataType is one of below: EfiTlsClientRandom EfiTlsServerRandom EfiTlsKeyMaterial
EFI_NOT_READY	Current TLS session state is NOT EfiTlsSessionStateNotStarted.
EFI_OUT_OF_RESOURCES	Required system resources could not be allocated.

Definition at line 364 of file Tls.h.

EFI_TLS_VERIFY

typedef UINT32 EFI_TLS_VERIFY

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.

Definition at line 166 of file Tls.h.

EFI_TLS_VERIFY_HOST_FLAG

typedef UINT32 EFI_TLS_VERIFY_HOST_FLAG

EFI_TLS_VERIFY_HOST_FLAG

Definition at line 191 of file Tls.h.

Enumeration Type Documentation

EFI_TLS_CONNECTION_END

enum EFI_TLS_CONNECTION_END

EFI_TLS_CONNECTION_END to define TLS session as client or server.

Definition at line 124 of file Tls.h.

EFI_TLS_CRYPT_MODE

enum EFI_TLS_CRYPT_MODE

EFI_TLS_CRYPT_MODE

Enumerator
EfiTlsEncrypt	Encrypt data provided in the fragment buffers.
EfiTlsDecrypt	Decrypt data provided in the fragment buffers.

Definition at line 327 of file Tls.h.

EFI_TLS_SESSION_DATA_TYPE

enum EFI_TLS_SESSION_DATA_TYPE

EFI_TLS_SESSION_DATA_TYPE

Enumerator
EfiTlsVersion	TLS session Version. The corresponding Data is of type EFI_TLS_VERSION.
EfiTlsConnectionEnd	TLS session as client or as server. The corresponding Data is of EFI_TLS_CONNECTION_END.
EfiTlsCipherList	A priority list of preferred algorithms for the TLS session. The corresponding Data is a list of EFI_TLS_CIPHER.
EfiTlsCompressionMethod	TLS session compression method. The corresponding Data is of type EFI_TLS_COMPRESSION.
EfiTlsExtensionData	TLS session extension data. The corresponding Data is a list of type EFI_TLS_EXTENSION .
EfiTlsVerifyMethod	TLS session verify method. The corresponding Data is of type EFI_TLS_VERIFY.
EfiTlsSessionID	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.
EfiTlsSessionState	TLS session data session state. The corresponding Data is of type EFI_TLS_SESSION_STATE.
EfiTlsClientRandom	TLS session data client random. The corresponding Data is of type EFI_TLS_RANDOM.
EfiTlsServerRandom	TLS session data server random. The corresponding Data is of type EFI_TLS_RANDOM.
EfiTlsKeyMaterial	TLS session data key material. The corresponding Data is of type EFI_TLS_MASTER_SECRET.
EfiTlsVerifyHost	TLS session hostname for validation which is used to verify whether the name within the peer certificate matches a given host name. This parameter is invalid when EfiTlsVerifyMethod is EFI_TLS_VERIFY_NONE. The corresponding Data is of type EFI_TLS_VERIFY_HOST.

Definition at line 43 of file Tls.h.

EFI_TLS_SESSION_STATE

enum EFI_TLS_SESSION_STATE

EFI_TLS_SESSION_STATE

Enumerator
EfiTlsSessionNotStarted	When a new child of TLS protocol is created, the initial state of TLS session is EfiTlsSessionNotStarted.
EfiTlsSessionHandShaking	The consumer can call BuildResponsePacket() with NULL to get ClientHello to start the TLS session. Then the status is EfiTlsSessionHandShaking.
EfiTlsSessionDataTransferring	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.
EfiTlsSessionClosing	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.
EfiTlsSessionError	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.

Definition at line 274 of file Tls.h.