mirror of
https://github.com/tianocore/edk2
synced 2026-08-27 00:23:19 -04:00
9326c0eb0a
Replace traditional `#ifndef`/`#define`/`#endif` include guards with
`#pragma` once.
`#pragma once` is a widely supported preprocessor directive that
prevents header files from being included multiple times. It is
supported by all toolchains used to build edk2: GCC, Clang/LLVM, and
MSVC.
Compared to macro-based include guards, `#pragma once`:
- Eliminates the risk of macro name collisions or copy/paste errors
where two headers inadvertently use the same guard macro.
- Eliminate inconsistency in the way include guard macros are named
(e.g., some files use `__FILE_H__`, others use `FILE_H_`, etc.).
- Reduces boilerplate (three lines replaced by one).
- Avoids polluting the macro namespace with guard symbols.
- Can improve build times as the preprocessor can skip re-opening the
file entirely, rather than re-reading it to find the matching
`#endif` ("multiple-include optimization").
- Note that some compilers may already optimize traditional include
guards, by recognzining the idiomatic pattern.
This change is made acknowledging that overall portability of the
code will technically be reduced, as `#pragma once` is not part of the
C/C++ standards.
However, this is considered acceptable given:
1. edk2 already defines a subset of supported compilers in
BaseTools/Conf/tools_def.template, all of which have supported
`#pragma once` for over two decades.
2. There have been concerns raised to the project about inconsistent
include guard naming and potential macro collisions.
Approximate compiler support dates:
- MSVC: Supported since Visual C++ 4.2 (1996)
- GCC: Supported since 3.4 (2004)
(http://gnu.ist.utl.pt/software/gcc/gcc-3.4/changes.html)
- Clang (LLVM based): Since initial release in 2007
Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>
434 lines
20 KiB
C
434 lines
20 KiB
C
/** @file
|
|
EDKII Device Security library for SPDM device.
|
|
It follows the SPDM Specification.
|
|
|
|
Copyright (c) 2024, Intel Corporation. All rights reserved.<BR>
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
|
|
**/
|
|
|
|
#pragma once
|
|
|
|
#include <Protocol/DeviceSecurity.h>
|
|
#include <Protocol/DeviceSecurityPolicy.h>
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param spdm_context A pointer to the SPDM context.
|
|
* @param message_size size in bytes of the message data buffer.
|
|
* @param 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.
|
|
* @param 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.
|
|
*
|
|
* @retval RETURN_SUCCESS The SPDM message is sent successfully.
|
|
* @retval RETURN_DEVICE_ERROR A device error occurs when the SPDM message is sent to the device.
|
|
* @retval RETURN_INVALID_PARAMETER The message is NULL or the message_size is zero.
|
|
* @retval RETURN_TIMEOUT A timeout occurred while waiting for the SPDM message
|
|
* to execute.
|
|
**/
|
|
typedef
|
|
SPDM_RETURN
|
|
(*SPDM_DEVICE_SEND_MESSAGE_FUNC)(
|
|
IN VOID *SpdmContext,
|
|
IN UINTN MessageSize,
|
|
IN OUT CONST 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.
|
|
*
|
|
* @param spdm_context A pointer to the SPDM context.
|
|
* @param message_size size in bytes of the message data buffer.
|
|
* @param 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.
|
|
* @param 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.
|
|
*
|
|
* @retval RETURN_SUCCESS The SPDM message is received successfully.
|
|
* @retval RETURN_DEVICE_ERROR A device error occurs when the SPDM message is received from the device.
|
|
* @retval RETURN_INVALID_PARAMETER The message is NULL, message_size is NULL or
|
|
* the *message_size is zero.
|
|
* @retval RETURN_TIMEOUT A timeout occurred while waiting for the SPDM message
|
|
* to execute.
|
|
**/
|
|
typedef
|
|
SPDM_RETURN
|
|
(*SPDM_DEVICE_RECEIVE_MESSAGE_FUNC)(
|
|
IN VOID *SpdmContext,
|
|
IN OUT UINTN *MessageSize,
|
|
IN OUT VOID **Message,
|
|
IN UINT64 Timeout
|
|
);
|
|
|
|
/**
|
|
* 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
|
|
*
|
|
* @param spdm_context A pointer to the SPDM context.
|
|
* @param 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.
|
|
* @param is_app_message Indicates if it is an APP message or SPDM message.
|
|
* @param is_requester Indicates if it is a requester message.
|
|
* @param message_size size in bytes of the message data buffer.
|
|
* @param 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.
|
|
* @param transport_message_size size in bytes of the transport message data buffer.
|
|
* @param 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.
|
|
*
|
|
* @retval RETURN_SUCCESS The message is encoded successfully.
|
|
* @retval RETURN_INVALID_PARAMETER The message is NULL or the message_size is zero.
|
|
**/
|
|
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
|
|
);
|
|
|
|
/**
|
|
* 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
|
|
*
|
|
* @param spdm_context A pointer to the SPDM context.
|
|
* @param 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.
|
|
* @param is_app_message Indicates if it is an APP message or SPDM message.
|
|
* @param is_requester Indicates if it is a requester message.
|
|
* @param transport_message_size size in bytes of the transport message data buffer.
|
|
* @param 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.
|
|
* @param message_size size in bytes of the message data buffer.
|
|
* @param 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.
|
|
*
|
|
* @retval RETURN_SUCCESS The message is decoded successfully.
|
|
* @retval RETURN_INVALID_PARAMETER The message is NULL or the message_size is zero.
|
|
* @retval RETURN_UNSUPPORTED The transport_message is unsupported.
|
|
**/
|
|
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
|
|
);
|
|
|
|
/**
|
|
* 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
|
|
*
|
|
* @param context A pointer to the SPDM context.
|
|
* @param max_msg_size size in bytes of the maximum size of sender buffer.
|
|
* @param msg_buf_ptr A pointer to a sender buffer.
|
|
*
|
|
* @retval RETURN_SUCCESS The sender buffer is acquired.
|
|
**/
|
|
typedef
|
|
SPDM_RETURN
|
|
(*SPDM_DEVICE_ACQUIRE_SENDER_BUFFER_FUNC)(
|
|
IN VOID *SpdmContext,
|
|
IN OUT VOID **MsgBufPtr
|
|
);
|
|
|
|
/**
|
|
* Release a device sender buffer for transport layer message.
|
|
*
|
|
* @param context A pointer to the SPDM context.
|
|
* @param msg_buf_ptr A pointer to a sender buffer.
|
|
*
|
|
* @retval RETURN_SUCCESS The sender buffer is Released.
|
|
**/
|
|
typedef
|
|
VOID
|
|
(*SPDM_DEVICE_RELEASE_SENDER_BUFFER_FUNC)(
|
|
IN VOID *SpdmContext,
|
|
IN CONST 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
|
|
*
|
|
* @param context A pointer to the SPDM context.
|
|
* @param max_msg_size size in bytes of the maximum size of receiver buffer.
|
|
* @param msg_buf_pt A pointer to a receiver buffer.
|
|
*
|
|
* @retval RETURN_SUCCESS The receiver buffer is acquired.
|
|
**/
|
|
typedef
|
|
SPDM_RETURN
|
|
(*SPDM_DEVICE_ACQUIRE_RECEIVER_BUFFER_FUNC)(
|
|
IN VOID *SpdmContext,
|
|
IN OUT VOID **MsgBufPtr
|
|
);
|
|
|
|
/**
|
|
* Release a device receiver buffer for transport layer message.
|
|
*
|
|
* @param context A pointer to the SPDM context.
|
|
* @param msg_buf_ptr A pointer to a receiver buffer.
|
|
*
|
|
* @retval RETURN_SUCCESS The receiver buffer is Released.
|
|
**/
|
|
typedef
|
|
VOID
|
|
(*SPDM_DEVICE_RELEASE_RECEIVER_BUFFER_FUNC)(
|
|
IN VOID *SpdmContext,
|
|
IN CONST VOID *MsgBufPtr
|
|
);
|
|
|
|
typedef struct {
|
|
UINT32 Version;
|
|
//
|
|
// DeviceType is used to create TCG event log context_data.
|
|
// DeviceHandle is used to create TCG event log device_path information.
|
|
//
|
|
EDKII_DEVICE_IDENTIFIER *DeviceId;
|
|
|
|
//
|
|
// TRUE means to use PCR 0 (code) / 1 (config).
|
|
// FALSE means to use PCR 2 (code) / 3 (config).
|
|
//
|
|
BOOLEAN IsEmbeddedDevice;
|
|
|
|
//
|
|
// Below 9 APIs are used to send/receive SPDM request/response.
|
|
//
|
|
// The request flow is:
|
|
// |<--- SenderBufferSize --->|
|
|
// |<--- TransportRequestBufferSize --->|
|
|
// |<---MaxHeaderSize--->|<-SpdmRequestBufferSize ->|
|
|
// +--+------------------+==========================+----------------+--+
|
|
// | | Transport Header | SPDM Message | Transport Tail | |
|
|
// +--+------------------+==========================+----------------+--+
|
|
// ^ ^ ^
|
|
// | | | SpdmRequestBuffer
|
|
// | | TransportRequestBuffer
|
|
// | SenderBuffer
|
|
//
|
|
// AcquireSenderBuffer (&SenderBuffer, &SenderBufferSize);
|
|
// SpdmRequestBuffer = SenderBuffer + TransportHeaderSize;
|
|
// /* build SPDM request in SpdmRequestBuffer */
|
|
// TransportEncodeMessage (SpdmRequestBuffer, SpdmRequestBufferSize,
|
|
// &TransportRequestBuffer, &TransportRequestBufferSize);
|
|
// SendMessage (TransportRequestBuffer, TransportRequestBufferSize);
|
|
// ReleaseSenderBuffer (SenderBuffer);
|
|
//
|
|
// The response flow is:
|
|
// |<--- ReceiverBufferSize --->|
|
|
// |<--- TransportResponseBufferSize --->|
|
|
// |<-SpdmResponseBufferSize->|
|
|
// +--+------------------+==========================+----------------+--+
|
|
// | | Transport Header | SPDM Message | Transport Tail | |
|
|
// +--+------------------+==========================+----------------+--+
|
|
// ^ ^ ^
|
|
// | | | SpdmResponseBuffer
|
|
// | | TransportResponseBuffer
|
|
// | ReceiverBuffer
|
|
//
|
|
// AcquireReceiverBuffer (&ReceiverBuffer, &ReceiverBufferSize);
|
|
// TransportResponseBuffer = ReceiverBuffer;
|
|
// ReceiveMessage (&TransportResponseBuffer, &TransportResponseBufferSize);
|
|
// TransportDecodeMessage (TransportResponseBuffer, TransportResponseBufferSize,
|
|
// &SpdmResponseBuffer, &SpdmResponseBufferSize);
|
|
// /* process SPDM response in SpdmResponseBuffer */
|
|
// ReleaseReceiverBuffer (ReceiverBuffer);
|
|
//
|
|
|
|
//
|
|
// API required by SpdmRegisterDeviceIoFunc in libspdm
|
|
// It is used to send/receive transport message (SPDM + transport header).
|
|
//
|
|
SPDM_DEVICE_SEND_MESSAGE_FUNC SendMessage;
|
|
SPDM_DEVICE_RECEIVE_MESSAGE_FUNC ReceiveMessage;
|
|
//
|
|
// API required by SpdmRegisterTransportLayerFunc in libspdm
|
|
// It is used to add/remove transport header for SPDM.
|
|
//
|
|
SPDM_TRANSPORT_ENCODE_MESSAGE_FUNC TransportEncodeMessage;
|
|
SPDM_TRANSPORT_DECODE_MESSAGE_FUNC TransportDecodeMessage;
|
|
//
|
|
// API required by SpdmRegisterDeviceBufferFunc in libspdm
|
|
// It is used to get the sender/receiver buffer for transport message (SPDM + transport header).
|
|
// The size MUST be big enough to send or receive one transport message (SPDM + transport header).
|
|
// Tthe sender/receiver buffer MAY be overlapped.
|
|
//
|
|
SPDM_DEVICE_ACQUIRE_SENDER_BUFFER_FUNC AcquireSenderBuffer;
|
|
SPDM_DEVICE_RELEASE_SENDER_BUFFER_FUNC ReleaseSenderBuffer;
|
|
SPDM_DEVICE_ACQUIRE_RECEIVER_BUFFER_FUNC AcquireReceiverBuffer;
|
|
SPDM_DEVICE_RELEASE_RECEIVER_BUFFER_FUNC ReleaseReceiverBuffer;
|
|
|
|
//
|
|
// Preferred Algorithm List for SPDM negotiation.
|
|
// If it is none zero, it will be used directly.
|
|
// If it is zero, then the SpdmSecurityLib will set the default value.
|
|
//
|
|
UINT32 BaseHashAlgo;
|
|
UINT32 BaseAsymAlgo;
|
|
|
|
//
|
|
// transfer size
|
|
//
|
|
UINT32 MaxSpdmMsgSize;
|
|
UINT32 TransportHeaderSize;
|
|
UINT32 TransportTailSize;
|
|
UINT32 SenderBufferSize;
|
|
UINT32 ReceiverBufferSize;
|
|
|
|
EFI_GUID *SpdmIoProtocolGuid;
|
|
} EDKII_SPDM_DEVICE_INFO;
|
|
|
|
/**
|
|
This function will send SPDM VCA, GET_CERTIFICATE, CHALLENGE, GET_MEASUREMENT,
|
|
The certificate and measurement will be extended to TPM PCR/NvIndex.
|
|
**/
|
|
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 get SpdmIoProtocol via Context.
|
|
**/
|
|
VOID *
|
|
EFIAPI
|
|
SpdmGetIoProtocolViaSpdmContext (
|
|
IN VOID *SpdmContext
|
|
);
|
|
|
|
/**
|
|
Helper function to quickly determine whether device authentication boot is enabled.
|
|
|
|
@retval TRUE device authentication boot is verifiably enabled.
|
|
@retval FALSE device authentication boot is either disabled or an error prevented checking.
|
|
|
|
**/
|
|
BOOLEAN
|
|
EFIAPI
|
|
IsDeviceAuthBootEnabled (
|
|
VOID
|
|
);
|