SPDM

API for the DMTF Security Protocol and Data Model Specification v1.4.0

Common Method Parameters

spdm_versionint

Defaults to 0x10, or the latest version returned by get_version.

request_response_codeint

Defaults to the correct request code for each method.

param1int

Defaults to 0 unless specified.

param2int

Defaults to 0 unless specified.

All other parameters default to 0 unless otherwise specified.

Method arguments can be int, bytes, bytearray, str, or lists/tuples of these. List contents will be concatenated during buffer construction.

Integers will be reversed automatically if the corresponding field is little-endian. Given 0xAABB, byte 0 will be AA in a big-endian context, and byte 1 will be AA in a little-endian context. Arguments passed as bytes will not be altered.

Child fields will always overwrite parent field contents when specified in addition to their parent field.

This API is under development. Some methods defined in the SPDM specification are not yet supported.

  1. 2025 SANBlaze Technology

class SPDM(target=None, port=None, remote_address=None, **kw)
challenge(spdm_version=None, request_response_code=131, param1=0, param2=0, nonce=0, context=None)

Execute the CALLENGE command

Parameters:

  • nonce (int) – Should be a random value

  • context (int) – Optional application-specific information

chunk_get(spdm_version: int | None = None, request_response_code: int = 134, param1: int = 0, handle: int = 0, chunk_seq_no: int = 0)

Execute the CHUNK_GET command (SPDM 1.2+).

Requests the next chunk of a large response from the responder, which replies with CHUNK_RESPONSE. Used with the Large SPDM message transfer mechanism; the responder must advertise CHUNK_CAP. A CHUNK_GET issued outside an in-progress large transfer typically yields ERROR.

Parameters:

  • param1 (int) – Reserved.

  • handle (int) – Handle (Param2) identifying the large response transfer.

  • chunk_seq_no (int) – Sequence number of the chunk being requested. This field is a uint16 in SPDM 1.2/1.3 and a uint32 in SPDM 1.4.

chunk_send(spdm_version: int | None = None, request_response_code: int = 133, param1: int = 0, handle: int = 0, chunk_seq_no: int = 0, chunk: bytes = b'', large_message_size: int | None = None, last_chunk: bool = True)

Execute the CHUNK_SEND command (SPDM 1.2+).

Sends a chunk of a large request to the responder, which replies with CHUNK_SEND_ACK. Used with the Large SPDM message transfer mechanism; the responder must advertise CHUNK_CAP.

Parameters:

  • param1 (int) – Request Attributes. Bit 0 (LastChunk) is set automatically when last_chunk is True.

  • handle (int) – Handle (Param2) identifying the large request transfer.

  • chunk_seq_no (int) – Sequence number of this chunk (uint16 in 1.2/1.3, uint32 in 1.4).

  • chunk (bytes) – The SpdmChunk payload for this chunk.

  • large_message_size (int, optional) – Total size of the large request; only sent in the first chunk (ChunkSeqNo == 0). Defaults to len(chunk) for the first chunk.

  • last_chunk (bool) – Whether this is the final chunk (sets the LastChunk attribute).

deliver_encapsulated_response(spdm_version: int | None = None, request_response_code: int = 235, param1: int | None = None, param2: int = 0, request_id: int = 0, encapsulated_response: bytes = b'')

Execute the DELIVER_ENCAPSULATED_RESPONSE command (SPDM 1.1+).

Delivers the requester’s response to a previously received encapsulated request; the responder replies with ENCAPSULATED_RESPONSE_ACK (which may carry the next encapsulated request). The responder must advertise ENCAP_CAP.

Parameters:

  • param1 (int, optional) – RequestID. Defaults to request_id.

  • param2 (int) – Reserved.

  • request_id (int) – RequestID being responded to (Param1).

  • encapsulated_response (bytes) – The SPDM response message to the encapsulated request.

get_capabilities(spdm_version=None, request_response_code=225, param1=0, param2=0, ct_exponent=0, ext_flags=0, flags=0, cert_cap=None, chal_cap=None, encrypt_cap=None, mac_cap=None, mut_auth_cap=None, key_ex_cap=None, psk_cap=None, encap_cap=None, hbeat_cap=None, key_upd_cap=None, handshake_in_the_clear_cap=None, pub_key_id_cap=None, chunk_cap=None, ep_info_cap=None, event_cap=None, multi_key_cap=None, large_resp_cap=None, data_transfer_size=8192, max_spdm_msg_size=65536)

Execute the GET_CAPABILITIES command

Parameters:

  • ct_exponent (int) – Exponent of base 2, used to calculate CT

  • ext_flags (int) – Reserved

  • flags (int) –

    The following parameters may be used for these byte/bit offsets:

    0/1 - cert_cap
    0/2 - chal_cap
    0/6 - encrypt_cap
    0/7 - mac_cap
    1/0 - mut_auth_cap
    1/1 - key_ex_cap
    1/3:2 - psk_cap,
    1/4 - encap_cap
    1/5 - hbeat_cap
    1/6 - key_upd_cap
    1/7 - handshake_in_the_clear_cap
    2/0 - pub_key_id_cap
    2/1 - chunk_cap
    2/7:6 - ep_info_cap
    3/1 - event_cap
    3/3:2 - multi_key_cap
    3/7 - large_resp_cap

  • data_transfer_size (int) – Maximum buffer size of incoming messages from responder

  • max_spdm_msg_size (int) – Maximum buffer size used to reassemble 1 Large SPDM message. Larger than data_transfer_size so that a response too big for a single transfer is answered with ERROR(LargeResponse) and can be fetched with get_large_response(), rather than refused outright with ERROR(ResponseTooLarge). A post-quantum certificate chain does not fit in 8 KiB, so leaving the two equal made those chains unreachable. Only valid when the requester advertises CHUNK_CAP; with CHUNK_CAP clear the two must be equal.

get_certificate(spdm_version=None, request_response_code=130, param1=0, use_large=None, slot_id=None, param2=0, slot_size_requested=None, offset=0, length=0, large_offset=None, large_length=None)

Execute the GET_CERTIFICATE command

Parameters:

  • param1 (int) –

    The following parameters may be used for these bit offsets:

    3:0 - slot_id
    7 - use_large

  • param2 (int) –

    The following parameters may be used for these bit offsets:

    0 - slot_size_requested

  • offset (int) – Read offset in bytes from start of certificate chain

  • length (int) – Length of certificate chain data in bytes

  • large_offset (int) – Read offset in bytes from start of large certificate chain

  • large_length (int) – Length of large certificate chain data in bytes

get_csr(spdm_version: int | None = None, request_response_code: int = 237, param1: int = 0, param2: int = 0, requester_info: bytes = b'', opaque_data: bytes = b'')

Execute the GET_CSR command (SPDM 1.2+).

Requests a certificate signing request from the responder, returned as CSR. The responder must advertise CSR_CAP.

Parameters:

  • param1 (int) – Reserved in 1.2; KeyPairID in SPDM 1.3+.

  • param2 (int) – Reserved in 1.2; Request Attributes in SPDM 1.3+.

  • requester_info (bytes) – RequesterInfo to be included in the CSR.

  • opaque_data (bytes) – Opaque data for the request.

get_digests(spdm_version=None, request_response_code=129, param1=0, param2=0)

Execute the GET_DIGESTS command

get_encapsulated_request(spdm_version: int | None = None, request_response_code: int = 234, param1: int = 0, param2: int = 0)

Execute the GET_ENCAPSULATED_REQUEST command (SPDM 1.1+).

Starts the encapsulated request flow; the responder replies with ENCAPSULATED_REQUEST carrying the request it wants the requester to service. The responder must advertise ENCAP_CAP.

Parameters:

  • param1 (int) – Reserved.

  • param2 (int) – Reserved.

get_endpoint_info(spdm_version: int | None = None, request_response_code: int = 135, param1: int = 1, param2: int = 0, slot_id: int | None = None, request_attributes: int = 0, signature_requested: int | None = None, nonce: int | None = None)

Execute the GET_ENDPOINT_INFO command (SPDM 1.3+).

Retrieves endpoint information from the responder. The responder must advertise EP_INFO_CAP in CAPABILITIES; otherwise it returns ERROR/UnsupportedRequest.

Parameters:

  • param1 (int) – SubCode of the request. 0x01 = DeviceClassIdentifier.

  • param2 (int) – Bit[3:0] SlotID (identifies the certificate chain used when a signature is requested), Bit[7:4] reserved.

  • slot_id (int, optional) – Convenience override for the SlotID nibble of param2.

  • request_attributes (int) – Bit[0] signature requested; other bits reserved.

  • signature_requested (int, optional) – Convenience override for bit 0 of request_attributes.

  • nonce (int, optional) – 32-byte random value. Only present when a signature is requested.

get_key_pair_info(spdm_version: int | None = None, request_response_code: int = 252, param1: int = 0, param2: int = 0, key_pair_id: int = 1)

Execute the GET_KEY_PAIR_INFO command (SPDM 1.3+).

Retrieves information about the key pair identified by KeyPairID, returned as KEY_PAIR_INFO. The responder must advertise GET_KEY_PAIR_INFO_CAP in CAPABILITIES.

Parameters:

  • param1 (int) – Reserved.

  • param2 (int) – Reserved.

  • key_pair_id (int) – The key pair ID whose information to retrieve.

get_large_response(structure: str, handle: int = 0, spdm_version: int | None = None, max_chunks: int = 4096)

Reassemble a large response with successive CHUNK_GET requests.

A response bigger than the DataTransferSize the requester advertised is not returned directly. A responder that supports chunking answers the original request with ERROR(LargeResponse) and a Handle, and the response is then collected as a series of CHUNK_RESPONSE messages. This method walks that series and parses the concatenated SpdmChunk payloads as structure, so the caller gets the same result it would have got had the response arrived in one piece.

Parameters:

  • structure (str) – Name of the response being reassembled, e.g. 'SLOT_MANAGEMENT_RESP'.

  • handle (int) – Handle from the ERROR(LargeResponse) ExtendedErrorData.

  • max_chunks (int) – Upper bound on the CHUNK_GET requests issued, so a responder that never sets LastChunk cannot loop forever.

get_measurement_extension_log(spdm_version: int | None = None, request_response_code: int = 239, param1: int = 0, param2: int = 0, offset: int = 0, length: int = 4294967295)

Execute the GET_MEASUREMENT_EXTENSION_LOG command (SPDM 1.3+).

Retrieves the Measurement Extension Log (MEL). The responder must advertise MEL_CAP in CAPABILITIES; otherwise it returns ERROR/UnsupportedRequest.

Parameters:

  • param1 (int) – Reserved.

  • param2 (int) – Reserved.

  • offset (int) – Offset in bytes from the start of the MEL at which the returned portion begins. Offset 0 is the first byte of the MEL.

  • length (int) – Number of MEL bytes to return. Defaults to 0xFFFFFFFF to request the whole log; the responder may return fewer (see PortionLength and RemainderLength in the response).

get_measurements(spdm_version=None, request_response_code=224, param1=0, signature_requested=None, raw_bit_stream_requested=None, new_measurement_requested=None, param2=0, nonce=None, slot_id_param=None, slot_id=None, context=None)

Execute the GET_MEASUREMENTS command

Parameters:

  • param1 (int) –

    The following parameters may be used for these bit offsets:

    0 - signature_requested
    1 - raw_bit_stream_requested
    2 - new_measurement_requested

  • nonce (int) – Should be a random value

  • sold_id_param (int) –

    The following parameters may be used for these bit offsets:

    3:0 - slot_id

  • context (int) – Optional application specific information

get_supported_event_types(spdm_version: int | None = None, request_response_code: int = 226, param1: int = 0, param2: int = 0)

Execute the GET_SUPPORTED_EVENT_TYPES command (SPDM 1.3+).

Retrieves the list of event types supported by the Event Notifier, returned as SUPPORTED_EVENT_TYPES. The responder must advertise EVENT_CAP in CAPABILITIES.

Parameters:

  • param1 (int) – Reserved.

  • param2 (int) – Reserved.

get_version(spdm_version=16, request_response_code=132, param1=0, param2=0)

Execute the GET_VERSION command

negotiate_algorithms(spdm_version=None, request_response_code=227, param1=0, param2=0, length=None, measurement_specification=0, dmtf_meas_spec=None, other_params_support=0, opaque_data_fmt_0=None, opaque_data_fmt_1=None, responder_multi_key_conn=None, base_asym_algo=0, tpm_alg_rsassa_2048=None, tpm_alg_rsapss_2048=None, tpm_alg_rsassa_3072=None, tpm_alg_rsapss_3072=None, tpm_alg_ecdsa_ecc_nist_p256=None, tpm_alg_rsassa_4096=None, tpm_alg_rsapss_4096=None, tpm_alg_ecdsa_ecc_nist_p384=None, tpm_alg_ecdsa_ecc_nist_p521=None, tpm_alg_sm2_ecc_sm2_p256=None, ed_dsa_ed25519=None, ed_dsa_ed448=None, base_hash_algo=0, tpm_alg_sha_256=None, tpm_alg_sha_384=None, tpm_alg_sha_512=None, tpm_alg_sha3_256=None, tpm_alg_sha3_384=None, tpm_alg_sha3_512=None, tpm_alg_sm3_256=None, pqc_asym_algo=0, ml_dsa_44=None, ml_dsa_65=None, ml_dsa_87=None, slh_dsa_sha2_128s=None, slh_dsa_shake_128s=None, slh_dsa_sha2_128f=None, slh_dsa_shake_128f=None, slh_dsa_sha2_192s=None, slh_dsa_shake_192s=None, slh_dsa_sha2_192f=None, slh_dsa_shake_192f=None, slh_dsa_sha2_256s=None, slh_dsa_shake_256s=None, slh_dsa_sha2_256f=None, slh_dsa_shake_256f=None, ext_asym_count=0, ext_hash_count=0, mel_specification=0, dmtf_mel_spec=None, ext_asym=None, ext_hash=None, req_alg_struct=None)

Execute the NEGOTIATE_ALGORITHMS command

Parameters:

lengthint

Message length. Automatically populated unless specified by user

measurement_specificationint

The following parameters may be used for these bit offsets:

0 - dmtf_meas_spec
other_params_supportint

The following parameters may be used for these bit offsets:

0 - opaque_data_fmt_0
1 - opaque_data_fmt_1
4 - responder_multi_key_conn
base_asym_algoint

Requester-supported assymetric key signature algorithms. The following parameters may be used for these byte/bit offsets:

0/0 - tpm_alg_rsassa_2048
0/1 - tpm_alg_rsapss_2048
0/2 - tpm_alg_rsassa_3072
0/3 - tpm_alg_rsapss_3072
0/4 - tpm_alg_ecdsa_ecc_nist_p256
0/5 - tpm_alg_rsassa_4096
0/6 - tpm_alg_rsapss_4096
0/7 - tpm_alg_ecdsa_ecc_nist_p384
1/0 - tpm_alg_ecdsa_ecc_nist_p521
1/1 - tpm_alg_sm2_ecc_sm2_p256
1/2 - ed_dsa_ed25519
1/3 - ed_dsa_ed448
base_hash_algoint

Requester-supported cryptographic hashing algorithms. The following parameters may be used for these byte/bit offsets:

0/0 - tpm_alg_sha_256
0/1 - tpm_alg_sha_384
0/2 - tpm_alg_sha_512
0/3 - tpm_alg_sha3_256
0/4 - tpm_alg_sha3_384
0/5 - tpm_alg_sha3_512
0/6 - tpm_alg_sm3_256
pqc_asym_algoint

Requester-supported PQC assymetric key signature algorithms. The following parameters may be used for these byte/bit offsets:

0/0 - ml_dsa_44
0/1 - ml_dsa_65
0/2 - ml_dsa_87
0/3 - slh_dsa_sha2_128s
0/4 - slh_dsa_shake_128s
0/5 - slh_dsa_sha2_128f
0/6 - slh_dsa_shake_128f
0/7 - slh_dsa_sha2_192s
1/0 - slh_dsa_shake_192s
1/1 - slh_dsa_sha2_192f
1/2 - slh_dsa_shake_192f
1/3 - slh_dsa_sha2_256s
1/4 - slh_dsa_shake_256s
1/5 - slh_dsa_sha2_256f
1/6 - slh_dsa_shake_256f
ext_asym_countint

Number of Requester-supported extended asymmetric key signature algorithms.

ext_hash_countint

Number of Requester-supported extended hashing algorithms.

mel_specificationint

The following parameters may be used for these bit offsets:

0 - dmtf_mel_spec
ext_asymlist

List of Requester-supported extended asymmetric key signature algorithms.

ext_hashlist

List of Requester-supported extended hashing algorithms.

req_alg_structlist

Algorithm request structures. Helper functions can be found in sanblaze.dmtf.spdm.templates: dhe, aead, req_base_asym_alg, key_schedule, req_pqc_asym_alg, kem_alg, extended_algorithm

psk_finish(spdm_version: int | None = None, request_response_code: int = 231, param1: int = 0, param2: int = 0, requester_verify_data: bytes = b'')

Execute the PSK_FINISH command (SPDM 1.1+).

Completes a PSK-based session handshake; the responder replies with PSK_FINISH_RSP. The responder must advertise PSK_CAP. A valid RequesterVerifyData is an HMAC over the session transcript, so this is normally issued only after a PSK_EXCHANGE within the same session.

Parameters:

  • param1 (int) – Reserved.

  • param2 (int) – Reserved.

  • requester_verify_data (bytes) – The RequesterVerifyData (HMAC). In SPDM 1.4 an OpaqueLength / OpaqueData pair precedes this field; that variant is not built here.

send_event(spdm_version: int | None = None, request_response_code: int = 241, param1: int = 0, param2: int = 0, event_count: int = 1, event_instance_id: int = 1, event_group_standard_id: int = 0, event_group_vendor_id: int | None = None, event_type_id: int = 1, event_detail: int | bytes = 0, event_detail_len: int = 8, events_list: bytes | None = None)

Execute the SEND_EVENT command (SPDM 1.3+).

Delivers one or more events to the Event Recipient, which acknowledges with EVENT_ACK. The recipient must advertise EVENT_CAP in CAPABILITIES.

By default a single DMTF EventLost event (EventTypeId=1, 8-byte detail) is sent. Pass events_list to supply a fully pre-built EventsList and bypass the single-event construction.

Parameters:

  • event_count (int) – Number of elements in EventsList (Table 116).

  • event_instance_id (int) – Event instance id of the single event (Table 117).

  • event_group_standard_id (int) – SVH registry/standard id of EventGroupId (0 = DMTF).

  • event_group_vendor_id (int, optional) – SVH vendor id; its byte length sets VendorIDLen. None => VendorIDLen 0 (as used by the DMTF event group).

  • event_type_id (int) – Event type within the event group (1 = EventLost).

  • event_detail (int or bytes) – Event-specific details, event_detail_len bytes.

  • event_detail_len (int) – Length of EventDetail.

  • events_list (bytes, optional) – Pre-built EventsList; overrides the single-event fields above.

set_certificate(spdm_version: int | None = None, request_response_code: int = 238, param1: int = 0, param2: int = 0, slot_id: int = 0, cert_chain: bytes = b'')

Execute the SET_CERTIFICATE command (SPDM 1.2+).

Provisions (or, in SPDM 1.3+ via the Erase attribute, removes) the certificate chain in the given slot; the responder acknowledges with SET_CERTIFICATE_RSP. The responder must advertise SET_CERT_CAP.

Note: SET_CERTIFICATE modifies responder certificate state.

Parameters:

  • param1 (int) – Request attributes. Bits 0-3 are the SlotID; in SPDM 1.3+ bits 4-6 are SetCertModel and bit 7 is Erase. The SlotID nibble is overlaid from slot_id.

  • param2 (int) – Reserved in 1.2; KeyPairID in SPDM 1.3+.

  • slot_id (int) – Certificate slot to set (0-15).

  • cert_chain (bytes) – The certificate chain to provision. Absent for an Erase request.

set_key_pair_info(spdm_version: int | None = None, request_response_code: int = 253, param1: int = 0, param2: int = 0, operation: int | None = None, key_pair_id: int = 1, desired_key_usage: int = 0, desired_asym_algo: int = 0, desired_assoc_cert_slot_mask: int = 0)

Execute the SET_KEY_PAIR_INFO command (SPDM 1.3+).

Changes, erases, or generates the key pair identified by KeyPairID; the responder acknowledges with SET_KEY_PAIR_INFO_ACK. The responder must advertise SET_KEY_PAIR_INFO_CAP in CAPABILITIES.

Parameters:

  • param1 (int) – Operation (Table 107): 0 = ParameterChange, 1 = KeyPairErase, 2 = GenerateKeyPair.

  • operation (int, optional) – Convenience override for param1 (Operation).

  • key_pair_id (int) – The key pair ID to modify.

  • desired_key_usage (int) – Desired key usage bit mask. With ParameterChange, 0 leaves the current usage unchanged.

  • desired_asym_algo (int) – Desired asymmetric algorithm. 0 leaves the current value unchanged.

  • desired_assoc_cert_slot_mask (int) – Desired certificate-slot association bit mask.

Notes

For the KeyPairErase operation, DesiredKeyUsage, DesiredAsymAlgo, and DesiredAssocCertSlotMask are absent (Table 106); the request is then just the header plus KeyPairID.

slot_management(spdm_version: int | None = None, request_response_code: int = 136, param1: int = 0, param2: int = 0, mgmt_struct_offset: int = 0, slot_mgmt_req_struct: bytes | bytearray | None = None)

Execute the SLOT_MANAGEMENT command (SPDM 1.4+).

slot_mgmt_req_struct carries the SubCode-specific request body. Build it with the helpers in sanblaze.dmtf.spdm.templates:

0x02 GetBankDetails - templates.slot_address
0x03 GetCertificateChain - templates.slot_address
0x04 GetCSR - templates.get_csr
0x20 ManageBank - templates.manage_bank
0x21 ManageSlot - templates.manage_slot
0x22 SetCertificate - templates.set_certificate

SubCodes 0x00 (SupportedSubCodes) and 0x01 (GetBankInfo) do not use a SlotMgmtReqStruct.

Parameters:

  • param1 (int) –

    SubCode value (Table 142):

    0x00 - SupportedSubCodes
    0x01 - GetBankInfo
    0x02 - GetBankDetails
    0x03 - GetCertificateChain
    0x04 - GetCSR
    0x20 - ManageBank
    0x21 - ManageSlot
    0x22 - SetCertificate

  • param2 (int) – Reserved.

  • mgmt_struct_offset (int) – Offset, in bytes, of SlotMgmtReqStruct from the start of the request. Auto-set to 8 when slot_mgmt_req_struct is provided, otherwise 0. Set independently to send malformed messages.

  • slot_mgmt_req_struct (bytes) – Pre-built SlotMgmtReqStruct. When provided, the struct is placed at byte 8 of the request regardless of mgmt_struct_offset.

subscribe_event_types(spdm_version: int | None = None, request_response_code: int = 240, param1: int = 0, param2: int = 0, subscribe_event_group_count: int | None = None, subscribe_list: bytes | None = None)

Execute the SUBSCRIBE_EVENT_TYPES command (SPDM 1.3+).

Subscribes (or unsubscribes) the Event Recipient to event groups. The responder acknowledges with SUBSCRIBE_EVENT_TYPES_ACK. The responder must advertise EVENT_CAP in CAPABILITIES.

With the default SubscribeEventGroupCount of 0 this unsubscribes from all events (Table 113); SubscribeListLen and SubscribeList are then absent and the request is just the 4-byte header.

Parameters:

  • param1 (int) – SubscribeEventGroupCount - number of event groups in SubscribeList. 0 removes all subscriptions.

  • subscribe_event_group_count (int, optional) – Convenience override for param1 (SubscribeEventGroupCount).

  • subscribe_list (bytes, optional) – The SubscribeList (a list of Event group structures). Only sent when the group count is non-zero; its length sets SubscribeListLen.

class Utils(api)