#include <Protocol/DeviceSecurity.h>
#include <Protocol/DeviceSecurityPolicy.h>

Data Structures
struct	EDKII_SPDM_DEVICE_INFO

Typedefs
typedef SPDM_RETURN(*	SPDM_DEVICE_SEND_MESSAGE_FUNC) (IN VOID SpdmContext, IN UINTN MessageSize, IN OUT CONST VOID Message, IN UINT64 Timeout)

typedef SPDM_RETURN(*	SPDM_DEVICE_RECEIVE_MESSAGE_FUNC) (IN VOID SpdmContext, IN OUT UINTN MessageSize, IN OUT VOID **Message, IN UINT64 Timeout)

typedef SPDM_RETURN(*	SPDM_TRANSPORT_ENCODE_MESSAGE_FUNC) (IN VOID SpdmContext, IN OUT CONST UINT32 SessionId, IN BOOLEAN IsAppMessage, IN BOOLEAN IsRequester, IN UINTN MessageSize, IN OUT VOID Message, IN OUT UINTN TransportMessageSize, IN VOID **TransportMessage)

typedef SPDM_RETURN(*	SPDM_TRANSPORT_DECODE_MESSAGE_FUNC) (IN VOID SpdmContext, IN OUT UINT32 SessionId, IN BOOLEAN IsAppMessage, IN BOOLEAN IsRequester, IN UINTN TransportMessageSize, IN OUT VOID TransportMessage, IN OUT UINTN MessageSize, IN OUT VOID **Message)

typedef SPDM_RETURN(*	SPDM_DEVICE_ACQUIRE_SENDER_BUFFER_FUNC) (IN VOID SpdmContext, IN OUT VOID *MsgBufPtr)

typedef VOID(*	SPDM_DEVICE_RELEASE_SENDER_BUFFER_FUNC) (IN VOID SpdmContext, IN CONST VOID MsgBufPtr)

typedef SPDM_RETURN(*	SPDM_DEVICE_ACQUIRE_RECEIVER_BUFFER_FUNC) (IN VOID SpdmContext, IN OUT VOID *MsgBufPtr)

typedef VOID(*	SPDM_DEVICE_RELEASE_RECEIVER_BUFFER_FUNC) (IN VOID SpdmContext, IN CONST VOID MsgBufPtr)

Functions
RETURN_STATUS EFIAPI	SpdmDeviceAuthenticationAndMeasurement (IN EDKII_SPDM_DEVICE_INFO SpdmDeviceInfo, IN EDKII_DEVICE_SECURITY_POLICY SecurityPolicy, OUT EDKII_DEVICE_SECURITY_STATE *SecurityState)

VOID *EFIAPI	SpdmGetIoProtocolViaSpdmContext (IN VOID *SpdmContext)

BOOLEAN EFIAPI	IsDeviceAuthBootEnabled (VOID)

Detailed Description

EDKII Device Security library for SPDM device. It follows the SPDM Specification.

Copyright (c) 2024, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file SpdmSecurityLib.h.

Typedef Documentation

◆ SPDM_DEVICE_ACQUIRE_RECEIVER_BUFFER_FUNC

typedef SPDM_RETURN(* SPDM_DEVICE_ACQUIRE_RECEIVER_BUFFER_FUNC) (IN VOID *SpdmContext, IN OUT VOID **MsgBufPtr)

Acquire a device receiver buffer for transport layer message.

The max_msg_size must be larger than MAX (non-secure Transport Message Header Size + SPDM_CAPABILITIES.DataTransferSize + max alignment pad size (transport specific), secure Transport Message Header Size + sizeof(spdm_secured_message_a_data_header1_t) + length of sequence_number (transport specific) + sizeof(spdm_secured_message_a_data_header2_t) + sizeof(spdm_secured_message_cipher_header_t) + App Message Header Size (transport specific) + SPDM_CAPABILITIES.DataTransferSize + maximum random data size (transport specific) + AEAD MAC size (16) + max alignment pad size (transport specific))

For MCTP, Transport Message Header Size = sizeof(mctp_message_header_t) length of sequence_number = 2 App Message Header Size = sizeof(mctp_message_header_t) maximum random data size = MCTP_MAX_RANDOM_NUMBER_COUNT max alignment pad size = 0 For PCI_DOE, Transport Message Header Size = sizeof(pci_doe_data_object_header_t) length of sequence_number = 0 App Message Header Size = 0 maximum random data size = 0 max alignment pad size = 3

Parameters

context	A pointer to the SPDM context.
max_msg_size	size in bytes of the maximum size of receiver buffer.
msg_buf_pt	A pointer to a receiver buffer.

Return values

RETURN_SUCCESS The receiver buffer is acquired.

Definition at line 281 of file SpdmSecurityLib.h.

◆ SPDM_DEVICE_ACQUIRE_SENDER_BUFFER_FUNC

typedef SPDM_RETURN(* SPDM_DEVICE_ACQUIRE_SENDER_BUFFER_FUNC) (IN VOID *SpdmContext, IN OUT VOID **MsgBufPtr)

Acquire a device sender buffer for transport layer message.

The max_msg_size must be larger than MAX (non-secure Transport Message Header Size + SPDM_CAPABILITIES.DataTransferSize + max alignment pad size (transport specific), secure Transport Message Header Size + sizeof(spdm_secured_message_a_data_header1_t) + length of sequence_number (transport specific) + sizeof(spdm_secured_message_a_data_header2_t) + sizeof(spdm_secured_message_cipher_header_t) + App Message Header Size (transport specific) + SPDM_CAPABILITIES.DataTransferSize + maximum random data size (transport specific) + AEAD MAC size (16) + max alignment pad size (transport specific))

For MCTP, Transport Message Header Size = sizeof(mctp_message_header_t) length of sequence_number = 2 App Message Header Size = sizeof(mctp_message_header_t) maximum random data size = MCTP_MAX_RANDOM_NUMBER_COUNT max alignment pad size = 0 For PCI_DOE, Transport Message Header Size = sizeof(pci_doe_data_object_header_t) length of sequence_number = 0 App Message Header Size = 0 maximum random data size = 0 max alignment pad size = 3

Parameters

context	A pointer to the SPDM context.
max_msg_size	size in bytes of the maximum size of sender buffer.
msg_buf_ptr	A pointer to a sender buffer.

Return values

RETURN_SUCCESS The sender buffer is acquired.

Definition at line 222 of file SpdmSecurityLib.h.

◆ SPDM_DEVICE_RECEIVE_MESSAGE_FUNC

typedef SPDM_RETURN(* SPDM_DEVICE_RECEIVE_MESSAGE_FUNC) (IN VOID *SpdmContext, IN OUT UINTN *MessageSize, IN OUT VOID **Message, IN UINT64 Timeout)

Receive an SPDM transport layer message from a device.

The message is an SPDM message with transport layer wrapper, or a secured SPDM message with transport layer wrapper.

For requester, the message is a transport layer SPDM response. For responder, the message is a transport layer SPDM request.

Parameters

spdm_context	A pointer to the SPDM context.
message_size	size in bytes of the message data buffer.
message	A pointer to a destination buffer to store the message. The caller is responsible for having either implicit or explicit ownership of the buffer. On input, the message pointer shall be msg_buf_ptr from acquired receiver_buffer. On output, the message pointer shall be inside of [msg_buf_ptr, msg_buf_ptr + max_msg_size] from acquired receiver_buffer.
timeout	The timeout, in 100ns units, to use for the execution of the message. A timeout value of 0 means that this function will wait indefinitely for the message to execute. If timeout is greater than zero, then this function will return RETURN_TIMEOUT if the time required to execute the message is greater than timeout.

Return values

RETURN_SUCCESS	The SPDM message is received successfully.
RETURN_DEVICE_ERROR	A device error occurs when the SPDM message is received from the device.
RETURN_INVALID_PARAMETER	The message is NULL, message_size is NULL or the *message_size is zero.
RETURN_TIMEOUT	A timeout occurred while waiting for the SPDM message to execute.

Definition at line 91 of file SpdmSecurityLib.h.

◆ SPDM_DEVICE_RELEASE_RECEIVER_BUFFER_FUNC

typedef VOID(* SPDM_DEVICE_RELEASE_RECEIVER_BUFFER_FUNC) (IN VOID *SpdmContext, IN CONST VOID *MsgBufPtr)

Release a device receiver buffer for transport layer message.

Parameters

context	A pointer to the SPDM context.
msg_buf_ptr	A pointer to a receiver buffer.

Return values

RETURN_SUCCESS The receiver buffer is Released.

Definition at line 296 of file SpdmSecurityLib.h.

◆ SPDM_DEVICE_RELEASE_SENDER_BUFFER_FUNC

typedef VOID(* SPDM_DEVICE_RELEASE_SENDER_BUFFER_FUNC) (IN VOID *SpdmContext, IN CONST VOID *MsgBufPtr)

Release a device sender buffer for transport layer message.

Parameters

context	A pointer to the SPDM context.
msg_buf_ptr	A pointer to a sender buffer.

Return values

RETURN_SUCCESS The sender buffer is Released.

Definition at line 237 of file SpdmSecurityLib.h.

◆ SPDM_DEVICE_SEND_MESSAGE_FUNC

typedef SPDM_RETURN(* SPDM_DEVICE_SEND_MESSAGE_FUNC) (IN VOID *SpdmContext, IN UINTN MessageSize, IN OUT CONST VOID *Message, IN UINT64 Timeout)

Send an SPDM transport layer message to a device.

The message is an SPDM message with transport layer wrapper, or a secured SPDM message with transport layer wrapper.

For requester, the message is a transport layer SPDM request. For responder, the message is a transport layer SPDM response.

Parameters

spdm_context	A pointer to the SPDM context.
message_size	size in bytes of the message data buffer.
message	A pointer to a destination buffer to store the message. The caller is responsible for having either implicit or explicit ownership of the buffer. The message pointer shall be inside of [msg_buf_ptr, msg_buf_ptr + max_msg_size] from acquired sender_buffer.
timeout	The timeout, in 100ns units, to use for the execution of the message. A timeout value of 0 means that this function will wait indefinitely for the message to execute. If timeout is greater than zero, then this function will return RETURN_TIMEOUT if the time required to execute the message is greater than timeout.

Return values

RETURN_SUCCESS	The SPDM message is sent successfully.
RETURN_DEVICE_ERROR	A device error occurs when the SPDM message is sent to the device.
RETURN_INVALID_PARAMETER	The message is NULL or the message_size is zero.
RETURN_TIMEOUT	A timeout occurred while waiting for the SPDM message to execute.

Definition at line 48 of file SpdmSecurityLib.h.

◆ SPDM_TRANSPORT_DECODE_MESSAGE_FUNC

typedef SPDM_RETURN(* SPDM_TRANSPORT_DECODE_MESSAGE_FUNC) (IN VOID *SpdmContext, IN OUT UINT32 **SessionId, IN BOOLEAN *IsAppMessage, IN BOOLEAN IsRequester, IN UINTN TransportMessageSize, IN OUT VOID *TransportMessage, IN OUT UINTN *MessageSize, IN OUT VOID **Message)

Decode an SPDM or APP message from a transport layer message.

For normal SPDM message, it removes the transport layer wrapper, For secured SPDM message, it removes the transport layer wrapper, then decrypts and verifies a secured message. For secured APP message, it removes the transport layer wrapper, then decrypts and verifies a secured message.

The APP message is decoded from a secured message directly in SPDM session. The APP message format is defined by the transport layer. Take MCTP as example: APP message == MCTP header (MCTP_MESSAGE_TYPE_SPDM) + SPDM message

Parameters

spdm_context	A pointer to the SPDM context.
session_id	Indicates if it is a secured message protected via SPDM session. If session_id is NULL, it is a normal message. If session_id is NOT NULL, it is a secured message.
is_app_message	Indicates if it is an APP message or SPDM message.
is_requester	Indicates if it is a requester message.
transport_message_size	size in bytes of the transport message data buffer.
transport_message	A pointer to a source buffer to store the transport message. For normal message or secured message, it shall point to acquired receiver buffer.
message_size	size in bytes of the message data buffer.
message	A pointer to a destination buffer to store the message. On input, it shall point to the scratch buffer in spdm_context. On output, for normal message, it will point to the original receiver buffer. On output, for secured message, it will point to the scratch buffer in spdm_context.

Return values

RETURN_SUCCESS	The message is decoded successfully.
RETURN_INVALID_PARAMETER	The message is NULL or the message_size is zero.
RETURN_UNSUPPORTED	The transport_message is unsupported.

Definition at line 172 of file SpdmSecurityLib.h.

◆ SPDM_TRANSPORT_ENCODE_MESSAGE_FUNC

typedef SPDM_RETURN(* SPDM_TRANSPORT_ENCODE_MESSAGE_FUNC) (IN VOID *SpdmContext, IN OUT CONST UINT32 *SessionId, IN BOOLEAN IsAppMessage, IN BOOLEAN IsRequester, IN UINTN MessageSize, IN OUT VOID *Message, IN OUT UINTN *TransportMessageSize, IN VOID **TransportMessage)

Encode an SPDM or APP message to a transport layer message.

For normal SPDM message, it adds the transport layer wrapper. For secured SPDM message, it encrypts a secured message then adds the transport layer wrapper. For secured APP message, it encrypts a secured message then adds the transport layer wrapper.

The APP message is encoded to a secured message directly in SPDM session. The APP message format is defined by the transport layer. Take MCTP as example: APP message == MCTP header (MCTP_MESSAGE_TYPE_SPDM) + SPDM message

Parameters

spdm_context	A pointer to the SPDM context.
session_id	Indicates if it is a secured message protected via SPDM session. If session_id is NULL, it is a normal message. If session_id is NOT NULL, it is a secured message.
is_app_message	Indicates if it is an APP message or SPDM message.
is_requester	Indicates if it is a requester message.
message_size	size in bytes of the message data buffer.
message	A pointer to a source buffer to store the message. For normal message, it shall point to the acquired sender buffer. For secured message, it shall point to the scratch buffer in spdm_context.
transport_message_size	size in bytes of the transport message data buffer.
transport_message	A pointer to a destination buffer to store the transport message. On input, it shall be msg_buf_ptr from sender buffer. On output, it will point to acquired sender buffer.

Return values

RETURN_SUCCESS	The message is encoded successfully.
RETURN_INVALID_PARAMETER	The message is NULL or the message_size is zero.

Definition at line 129 of file SpdmSecurityLib.h.

Function Documentation

◆ IsDeviceAuthBootEnabled()

BOOLEAN EFIAPI IsDeviceAuthBootEnabled ( VOID )

Helper function to quickly determine whether device authentication boot is enabled.

Return values

TRUE	device authentication boot is verifiably enabled.
FALSE	device authentication boot is either disabled or an error prevented checking.

Definition at line 21 of file SpdmSecurityLib.c.

◆ SpdmDeviceAuthenticationAndMeasurement()

RETURN_STATUS EFIAPI SpdmDeviceAuthenticationAndMeasurement	(	IN EDKII_SPDM_DEVICE_INFO *	SpdmDeviceInfo,
		IN EDKII_DEVICE_SECURITY_POLICY *	SecurityPolicy,
		OUT EDKII_DEVICE_SECURITY_STATE *	SecurityState
	)

This function will send SPDM VCA, GET_CERTIFICATE, CHALLENGE, GET_MEASUREMENT, The certificate and measurement will be extended to TPM PCR/NvIndex.

The device driver uses this service to authenticate and measure an SPDM device.

Parameters

[in]	SpdmDeviceInfo	The SPDM context for the device.
[in]	SecurityPolicy	The security policy of this device.
[out]	SecurityState	A pointer to security state if this device.

Return values

EFI_SUCCESS	The TCG SPDM device measurement context is returned.
EFI_UNSUPPORTED	The TCG SPDM device measurement context is unsupported.

Definition at line 64 of file SpdmSecurityLib.c.

◆ SpdmGetIoProtocolViaSpdmContext()

VOID *EFIAPI SpdmGetIoProtocolViaSpdmContext ( IN VOID * SpdmContext )

This function will get SpdmIoProtocol via Context.

Parameters

[in] SpdmContext The SPDM context for the device.

return the pointer of Spdm Io protocol

Definition at line 143 of file SpdmSecurityLib.c.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ SPDM_DEVICE_ACQUIRE_RECEIVER_BUFFER_FUNC

◆ SPDM_DEVICE_ACQUIRE_SENDER_BUFFER_FUNC

◆ SPDM_DEVICE_RECEIVE_MESSAGE_FUNC

◆ SPDM_DEVICE_RELEASE_RECEIVER_BUFFER_FUNC

◆ SPDM_DEVICE_RELEASE_SENDER_BUFFER_FUNC

◆ SPDM_DEVICE_SEND_MESSAGE_FUNC

◆ SPDM_TRANSPORT_DECODE_MESSAGE_FUNC

◆ SPDM_TRANSPORT_ENCODE_MESSAGE_FUNC

Function Documentation

◆ IsDeviceAuthBootEnabled()

◆ SpdmDeviceAuthenticationAndMeasurement()

◆ SpdmGetIoProtocolViaSpdmContext()