Skip to content

CAPABILITIES: Add SupportedAlgorithms #2968

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

CAPABILITIES: Add SupportedAlgorithms #2968

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions doc/api/requester_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,52 @@ returns early with value not equal to `LIBSPDM_STATUS_SUCCESS` then the SPDM con
before attempting establish a new connection.
<br/><br/>

---
### libspdm_get_supported_algorithms
---

### Description
Sends `GET_VERSION` and `GET_CAPABILITIES` requests to retrieve the Responder's supported algorithms before algorithm negotiation.

### Parameters

**spdm_context**<br/>
The SPDM context.

**responder_supported_algorithms_length**<br/>
On input, indicates the size, in bytes, of the buffer in which the supported algorithms will be stored.
The buffer must be at least sizeof(libspdm_responder_supported_algorithms_13_t) bytes.
On output, indicates the size, in bytes, of the supported algorithms data.

**responder_supported_algorithms_buffer**<br/>
A pointer to a buffer to store the Responder's supported algorithms. Must not be NULL.

**spdm_version**<br/>
A pointer to store the SPDM version used for the request. The Integrator should check this value
to determine which structure type to use when accessing the algorithms data.

### Details
Before calling this function the Integrator must ensure that the SPDM context is initialized
with proper configuration, including the Requester's capabilities. The Requester must support
at least one SPDM version >= 1.3 and have CHUNK_CAP capability enabled in its configuration.

When this function returns with value `LIBSPDM_STATUS_SUCCESS`, the Integrator should:
1. Check the `spdm_version` to determine which structure type to use
2. Cast `responder_supported_algorithms_buffer` to the appropriate structure type
3. Access the supported algorithms through the structure fields

For example, if `spdm_version` indicates SPDM 1.3 or above:
```c
libspdm_responder_supported_algorithms_13_t *algorithms;
algorithms = (libspdm_responder_supported_algorithms_13_t *)responder_supported_algorithms_buffer;
// Access algorithms through algorithms->ext_asym_count, algorithms->ext_hash_count, etc.
```

If this function returns with value `LIBSPDM_STATUS_UNSUPPORTED_CAP`, either the Requester
does not support version 1.3 or above, or CHUNK_CAP is not enabled.

The function will assert if responder_supported_algorithms_buffer is NULL.
<br/><br/>

---
### libspdm_get_digest
Expand Down
50 changes: 36 additions & 14 deletions include/industry_standard/spdm.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,8 +164,41 @@ typedef struct {
uint32_t max_spdm_msg_size;
} spdm_get_capabilities_request_t;

/* SPDM GET_CAPABILITIES response*/
/* SPDM extended algorithm */
typedef struct {
uint8_t registry_id;
uint8_t reserved;
uint16_t algorithm_id;
} spdm_extended_algorithm_t;

typedef struct {
uint8_t alg_type;
uint8_t alg_count;
uint16_t alg_supported;
} spdm_negotiate_algorithms_common_struct_table_t;

/* SPDM supported algorithms block */
typedef struct {
uint8_t param1; /* Number of Algorithms Structure Tables */
uint8_t param2; /* Reserved */
uint16_t length;
uint8_t measurement_specification;
uint8_t other_params_support;
uint32_t base_asym_algo;
uint32_t base_hash_algo;
uint8_t reserved2[12];
uint8_t ext_asym_count;
uint8_t ext_hash_count;
uint8_t reserved3;
uint8_t mel_specification;
/* Followed by dynamic arrays for ext_asym, ext_hash, and struct_tableif needed
* spdm_extended_algorithm_t ext_asym[ext_asym_count];
* spdm_extended_algorithm_t ext_hash[ext_hash_count];
* spdm_negotiate_algorithms_common_struct_table_t struct_table[
* SPDM_NEGOTIATE_ALGORITHMS_MAX_NUM_STRUCT_TABLE_ALG];*/
} spdm_supported_algorithms_block_t;

/* SPDM GET_CAPABILITIES response*/
typedef struct {
spdm_message_header_t header;
/* param1 == RSVD
Expand All @@ -177,6 +210,8 @@ typedef struct {
/* Below field is added in 1.2.*/
uint32_t data_transfer_size;
uint32_t max_spdm_msg_size;
/* Below field is added in 1.3.*/
spdm_supported_algorithms_block_t supported_algorithms;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I gave feedback before to remove spdm_supported_algorithms_block_t from spdm_capabilities_response_t.

You can comment this line here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your feedback and for referencing the earlier discussion.t - cbda82c#r2151455599

To summarize, I understand the concern about including spdm_supported_algorithms_block_t in spdm_capabilities_response_t, especially since it’s a variable-length structure and may be considered a special case.

However, I added it here because, based on my reading of the SPDM 1.3 specification, it seems that spdm_supported_algorithms_block_t was introduced specifically for version 1.3, and including it in the structure aligns with the spec for that version. That said, I may be wrong, so I’m just trying to understand how we make this decision.

I’m also looping in @steven-bellock to get his perspective.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I don't there is any requirement to add anything defined in the spec.
If a structure is variable size, then it is OK to comment it here.

I prefer to not include it for convenience.

} spdm_capabilities_response_t;

#define SPDM_MIN_DATA_TRANSFER_SIZE_VERSION_12 42
Expand Down Expand Up @@ -360,12 +395,6 @@ typedef struct {
#define SPDM_NEGOTIATE_ALGORITHMS_ALG_SUPPORTED_AEAD_12_MASK 0x000f
#define SPDM_NEGOTIATE_ALGORITHMS_ALG_SUPPORTED_REQ_BASE_ASYM_ALG_12_MASK 0x0fff

typedef struct {
uint8_t alg_type;
uint8_t alg_count;
uint16_t alg_supported;
} spdm_negotiate_algorithms_common_struct_table_t;


/* SPDM NEGOTIATE_ALGORITHMS request base_asym_algo/REQ_BASE_ASYM_ALG */
#define SPDM_ALGORITHMS_BASE_ASYM_ALGO_TPM_ALG_RSASSA_2048 0x00000001
Expand Down Expand Up @@ -484,13 +513,6 @@ typedef struct {
/*opaque_element_table_t opaque_list[];*/
} spdm_general_opaque_data_table_header_t;

/* SPDM extended algorithm */
typedef struct {
uint8_t registry_id;
uint8_t reserved;
uint16_t algorithm_id;
} spdm_extended_algorithm_t;

/* SPDM registry_id */
#define SPDM_REGISTRY_ID_DMTF 0x0
#define SPDM_REGISTRY_ID_TCG 0x1
Expand Down
47 changes: 46 additions & 1 deletion include/internal/libspdm_requester_lib.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,10 +129,35 @@ libspdm_return_t libspdm_get_version(libspdm_context_t *spdm_context,
uint8_t *version_number_entry_count,
spdm_version_number_t *version_number_entry);

#define LIBSPDM_MAX_EXT_ALG_COUNT 5
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

libspdm does not support ext_alg. I think we can ignore them totally.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See #2968 (comment).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I don't suggest to keep the complexity.

As we already said, libspdm does not support ext_alg.
What is the value to return ext_alg to the integrator?
The integrator cannot use ext_algo with libspdm anyway.


#pragma pack(1)
typedef struct {
spdm_negotiate_algorithms_common_struct_table_t alg_struct;
spdm_extended_algorithm_t alg_external[LIBSPDM_MAX_EXT_ALG_COUNT];
} libspdm_supported_algorithms_alg_struct_t;
#pragma pack()

typedef struct {
uint8_t spdm_version;
uint8_t measurement_specification;
uint8_t other_params_support;
uint32_t base_asym_algo;
uint32_t base_hash_algo;
uint8_t mel_specification;
uint8_t ext_asym_count;
spdm_extended_algorithm_t ext_asym[LIBSPDM_MAX_EXT_ALG_COUNT];
uint8_t ext_hash_count;
spdm_extended_algorithm_t ext_hash[LIBSPDM_MAX_EXT_ALG_COUNT];
uint8_t struct_table_count;
libspdm_supported_algorithms_alg_struct_t
struct_table[LIBSPDM_MAX_EXT_ALG_COUNT];
} libspdm_responder_supported_algorithms_13_t;

/**
* This function sends GET_CAPABILITIES and receives CAPABILITIES.
*
* @param spdm_context A pointer to the SPDM context.
* @param spdm_context A pointer to the SPDM context.
* @param RequesterCTExponent RequesterCTExponent to the GET_CAPABILITIES request.
* @param RequesterFlags RequesterFlags to the GET_CAPABILITIES request.
* @param ResponderCTExponent ResponderCTExponent from the CAPABILITIES response.
Expand All @@ -143,6 +168,26 @@ libspdm_return_t libspdm_get_version(libspdm_context_t *spdm_context,
**/
libspdm_return_t libspdm_get_capabilities(libspdm_context_t *spdm_context);

/**
* This function sends GET_CAPABILITIES and receives CAPABILITIES.
*
* @param spdm_context A pointer to the SPDM context.
* @param get_supported_algorithms If true, indicates that the requester wants the responder to include its supported algorithms in the CAPABILITIES response.
* @param supported_algs_length On input, the size of the supported_algs buffer.
* @param supported_algs A pointer to a buffer to store the supported algorithms.
* @param RequesterCTExponent RequesterCTExponent to the GET_CAPABILITIES request.
* @param RequesterFlags RequesterFlags to the GET_CAPABILITIES request.
* @param ResponderCTExponent ResponderCTExponent from the CAPABILITIES response.
* @param ResponderFlags ResponderFlags from the CAPABILITIES response.
*
* @retval RETURN_SUCCESS The GET_CAPABILITIES is sent and the CAPABILITIES is received.
* @retval RETURN_DEVICE_ERROR A device error occurs when communicates with the device.
**/
libspdm_return_t libspdm_get_capabilities_with_supported_algs(libspdm_context_t *spdm_context,
bool get_supported_algorithms,
size_t *supported_algs_length,
void *supported_algs);

/**
* This function sends NEGOTIATE_ALGORITHMS and receives ALGORITHMS.
*
Expand Down
27 changes: 27 additions & 0 deletions include/library/spdm_requester_lib.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -525,6 +525,33 @@ libspdm_return_t libspdm_start_session(void *spdm_context, bool use_psk,
uint8_t *heartbeat_period,
void *measurement_hash);

/**
* This function retrieves the supported algorithms from the responder.
* It sends the GET_VERSION and GET_CAPABILITIES requests, where GET_CAPABILITIES.Param1[0] is set.
* If the Responder supports this extended capability, the Responder will include the Supported
* Algorithms Block in its CAPABILITIES response.
*
* @param spdm_context A pointer to the SPDM context.
* @param responder_supported_algorithms_length On input, indicates the size in bytes of the provided buffer.
* The buffer must be at least sizeof(libspdm_responder_supported_algorithms_13_t) bytes.
* On output, the size in bytes of the supported algorithms data.
* @param responder_supported_algorithms_buffer A pointer to a destination buffer to store the supported algorithms.
* Must not be NULL. The buffer must be large enough to hold the supported algorithms data.
* @param spdm_version A pointer to store the SPDM version used for the request.
*
* @retval RETURN_SUCCESS The supported algorithms were successfully retrieved.
* @retval RETURN_DEVICE_ERROR A device error occurs when communicates with the device.
* @retval RETURN_UNSUPPORTED The operation is not supported by the device.
* @retval RETURN_SECURITY_VIOLATION Any verification fails.
*
* @note The buffer must be at least sizeof(libspdm_responder_supported_algorithms_13_t) bytes.
* The function will assert if responder_supported_algorithms_buffer is NULL.
*/
libspdm_return_t libspdm_get_supported_algorithms(void *spdm_context,
size_t *responder_supported_algorithms_length,
void *responder_supported_algorithms_buffer,
uint8_t *spdm_version);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you include spdm_version to libspdm_responder_supported_algorithms_13_t, then you can remove spdm_version parameter here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

then you can remove spdm_version parameter here.

The Integrator still needs to know what libspdm_responder_supported_algorithms_*_t to apply to responder_supported_algorithms_buffer. Without this parameter they would need to libspdm_get_data LIBSPDM_DATA_SPDM_VERSION, which is not the end of the world, but this makes it more convenient.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the suggestion! I think having the spdm_version parameter improves the convenience and usability of the API. Let me know if you have a strong preference here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we can guarantee that spdm_version is already the first byte of responder_supported_algorithms_buffer, then the integrator can just check the first byte.

Or we can define following libspdm_responder_supported_algorithms_common_header structure to ensure that every libspdm_responder_supported_algorithms_13_t or libspdm_responder_supported_algorithms_14_t will use the same common header.

typedef struct {
    uint8_t spdm_version;
    /* the rest of the field is spdm_version specific */
} libspdm_responder_supported_algorithms_common_header;

I really cannot see the need to have uint8_t *spdm_version


/**
* This function sends KEY_EXCHANGE/FINISH or PSK_EXCHANGE/PSK_FINISH to start an SPDM Session.
*
Expand Down
59 changes: 58 additions & 1 deletion library/spdm_requester_lib/libspdm_req_communication.c
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
/**
* Copyright Notice:
* Copyright 2021-2024 DMTF. All rights reserved.
* Copyright 2021-2025 DMTF. All rights reserved.
* License: BSD 3-Clause License. For full text see link: https://github.com/DMTF/libspdm/blob/main/LICENSE.md
**/

Expand Down Expand Up @@ -31,6 +31,63 @@ libspdm_return_t libspdm_init_connection(void *spdm_context, bool get_version_on
return LIBSPDM_STATUS_SUCCESS;
}

libspdm_return_t libspdm_get_supported_algorithms(void *spdm_context,
size_t *responder_supported_algorithms_length,
void *responder_supported_algorithms_buffer,
uint8_t *spdm_version)
{
libspdm_return_t status;
libspdm_context_t *context;
bool has_version_1_3_or_above;
size_t index;

context = spdm_context;
has_version_1_3_or_above = false;

/* Verify responder_supported_algorithms_buffer is not NULL */
LIBSPDM_ASSERT(responder_supported_algorithms_buffer != NULL);
LIBSPDM_ASSERT(responder_supported_algorithms_length != NULL);

/* Pre-check: Verify requester supports at least one version >= 1.3 */
for (index = 0; index < context->local_context.version.spdm_version_count; index++) {
if (libspdm_get_version_from_version_number(context->local_context.version.spdm_version[index]) >=
SPDM_MESSAGE_VERSION_13) {
has_version_1_3_or_above = true;
break;
}
}
if (!has_version_1_3_or_above) {
return LIBSPDM_STATUS_UNSUPPORTED_CAP;
}

LIBSPDM_ASSERT((context->local_context.capability.flags &
SPDM_GET_CAPABILITIES_REQUEST_FLAGS_CHUNK_CAP) != 0);

status = libspdm_get_version(context, NULL, NULL);

if (LIBSPDM_STATUS_IS_ERROR(status)) {
return status;
}

*spdm_version = libspdm_get_version_from_version_number(context->connection_info.version);

if (*spdm_version < SPDM_MESSAGE_VERSION_13) {
return LIBSPDM_STATUS_UNSUPPORTED_CAP;
}

if (*responder_supported_algorithms_length < sizeof(libspdm_responder_supported_algorithms_13_t)) {
return LIBSPDM_STATUS_UNSUPPORTED_CAP;
}

status = libspdm_get_capabilities_with_supported_algs(context, true, responder_supported_algorithms_length,
responder_supported_algorithms_buffer);
if (LIBSPDM_STATUS_IS_ERROR(status)) {
return status;
}

return LIBSPDM_STATUS_SUCCESS;
}

#if (LIBSPDM_ENABLE_CAPABILITY_KEY_EX_CAP) || (LIBSPDM_ENABLE_CAPABILITY_PSK_CAP)
libspdm_return_t libspdm_start_session(void *spdm_context, bool use_psk,
const void *psk_hint,
Expand Down
Loading