1 /** 2 * Copyright Notice: 3 * Copyright 2021-2022 DMTF. All rights reserved. 4 * License: BSD 3-Clause License. For full text see link: https://github.com/DMTF/libspdm/blob/main/LICENSE.md 5 **/ 6 7 #ifndef SPDM_REQUESTER_LIB_H 8 #define SPDM_REQUESTER_LIB_H 9 10 #include "library/spdm_common_lib.h" 11 12 /** 13 * This function sends GET_VERSION, GET_CAPABILITIES, NEGOTIATE_ALGORITHMS 14 * to initialize the connection with SPDM responder. 15 * 16 * Before this function, the requester configuration data can be set via libspdm_set_data. 17 * After this function, the negotiated configuration data can be got via libspdm_get_data. 18 * 19 * @param spdm_context A pointer to the SPDM context. 20 * @param get_version_only If the requester sends GET_VERSION only or not. 21 * 22 * @retval RETURN_SUCCESS The connection is initialized successfully. 23 * @retval RETURN_DEVICE_ERROR A device error occurs when communicates with the device. 24 **/ 25 libspdm_return_t libspdm_init_connection(void *spdm_context, bool get_version_only); 26 27 #if LIBSPDM_SEND_GET_CERTIFICATE_SUPPORT 28 /** 29 * This function sends GET_DIGEST to get all digest of the certificate chains from device. 30 * 31 * TotalDigestSize = sizeof(digest) * count in slot_mask 32 * 33 * @param spdm_context A pointer to the SPDM context. 34 * @param session_id Indicates if it is a secured message protected via SPDM session. 35 * If session_id is NULL, it is a normal message. 36 * If session_id is not NULL, it is a secured message. 37 * @param slot_mask Bitmask of the slots that contain certificates. 38 * @param total_digest_buffer A pointer to a destination buffer to store the digests. 39 * 40 * @retval LIBSPDM_STATUS_SUCCESS 41 * GET_DIGESTS was sent and DIGESTS was received. 42 * @retval LIBSPDM_STATUS_INVALID_STATE_LOCAL 43 * Cannot send GET_DIGESTS due to Requester's state. 44 * @retval LIBSPDM_STATUS_UNSUPPORTED_CAP 45 * Cannot send GET_DIGESTS because the Requester's and/or Responder's CERT_CAP = 0. 46 * @retval LIBSPDM_STATUS_INVALID_MSG_SIZE 47 * The size of the DIGESTS response is invalid. 48 * @retval LIBSPDM_STATUS_INVALID_MSG_FIELD 49 * The DIGESTS response contains one or more invalid fields. 50 * @retval LIBSPDM_STATUS_ERROR_PEER 51 * The Responder returned an unexpected error. 52 * @retval LIBSPDM_STATUS_BUSY_PEER 53 * The Responder continually returned Busy error messages. 54 * @retval LIBSPDM_STATUS_RESYNCH_PEER 55 * The Responder returned a RequestResynch error message. 56 * @retval LIBSPDM_STATUS_BUFFER_FULL 57 * The buffer used to store transcripts is exhausted. 58 **/ 59 libspdm_return_t libspdm_get_digest(void *spdm_context, const uint32_t *session_id, 60 uint8_t *slot_mask, void *total_digest_buffer); 61 62 /** 63 * This function sends GET_CERTIFICATE to get certificate chain in one slot from device. 64 * 65 * This function verify the integrity of the certificate chain. 66 * root_hash -> Root certificate -> Intermediate certificate -> Leaf certificate. 67 * 68 * If the peer root certificate hash is deployed, 69 * this function also verifies the digest with the root hash in the certificate chain. 70 * 71 * @param spdm_context A pointer to the SPDM context. 72 * @param session_id Indicates if it is a secured message protected via SPDM session. 73 * If session_id is NULL, it is a normal message. 74 * @param slot_id The number of slot for the certificate chain. 75 * @param cert_chain_size On input, indicate the size in bytes of the destination buffer to store the digest buffer. 76 * On output, indicate the size in bytes of the certificate chain. 77 * @param cert_chain A pointer to a destination buffer to store the certificate chain. 78 * 79 * @retval LIBSPDM_STATUS_SUCCESS 80 * GET_CERTIFICATE was sent and CERTIFICATE was received. 81 * @retval LIBSPDM_STATUS_INVALID_STATE_LOCAL 82 * Cannot send GET_CERTIFICATE due to Requester's state. 83 * @retval LIBSPDM_STATUS_UNSUPPORTED_CAP 84 * Cannot send GET_CERTIFICATE because the Requester's and/or Responder's CERT_CAP = 0. 85 * @retval LIBSPDM_STATUS_INVALID_MSG_SIZE 86 * The size of the CERTIFICATE response is invalid. 87 * @retval LIBSPDM_STATUS_INVALID_MSG_FIELD 88 * The CERTIFICATE response contains one or more invalid fields. 89 * @retval LIBSPDM_STATUS_ERROR_PEER 90 * The Responder returned an unexpected error. 91 * @retval LIBSPDM_STATUS_BUSY_PEER 92 * The Responder continually returned Busy error messages. 93 * @retval LIBSPDM_STATUS_RESYNCH_PEER 94 * The Responder returned a RequestResynch error message. 95 * @retval LIBSPDM_STATUS_BUFFER_FULL 96 * The buffer used to store transcripts is exhausted. 97 * @retval LIBSPDM_STATUS_VERIF_FAIL 98 * Verification of the certificate chain failed. 99 * @retval LIBSPDM_STATUS_INVALID_CERT 100 * The certificate is unable to be parsed or contains invalid field values. 101 * @retval LIBSPDM_STATUS_CRYPTO_ERROR 102 * A generic cryptography error occurred. 103 **/ 104 libspdm_return_t libspdm_get_certificate(void *spdm_context, 105 const uint32_t *session_id, 106 uint8_t slot_id, 107 size_t *cert_chain_size, 108 void *cert_chain); 109 110 /** 111 * This function sends GET_CERTIFICATE to get certificate chain in one slot from device. 112 * 113 * This function verify the integrity of the certificate chain. 114 * root_hash -> Root certificate -> Intermediate certificate -> Leaf certificate. 115 * 116 * If the peer root certificate hash is deployed, 117 * this function also verifies the digest with the root hash in the certificate chain. 118 * 119 * @param spdm_context A pointer to the SPDM context. 120 * @param session_id Indicates if it is a secured message protected via SPDM session. 121 * If session_id is NULL, it is a normal message. 122 * @param slot_id The number of slot for the certificate chain. 123 * @param cert_chain_size On input, indicate the size in bytes of the destination buffer to store the digest buffer. 124 * On output, indicate the size in bytes of the certificate chain. 125 * @param cert_chain A pointer to a destination buffer to store the certificate chain. 126 * @param trust_anchor A buffer to hold the trust_anchor which is used to validate the peer certificate, if not NULL. 127 * @param trust_anchor_size A buffer to hold the trust_anchor_size, if not NULL. 128 * 129 * @retval RETURN_SUCCESS The certificate chain is got successfully. 130 * @retval RETURN_DEVICE_ERROR A device error occurs when communicates with the device. 131 * @retval RETURN_SECURITY_VIOLATION Any verification fails. 132 **/ 133 libspdm_return_t libspdm_get_certificate_ex(void *spdm_context, 134 const uint32_t *session_id, 135 uint8_t slot_id, 136 size_t *cert_chain_size, 137 void *cert_chain, 138 const void **trust_anchor, 139 size_t *trust_anchor_size); 140 #endif /* LIBSPDM_SEND_GET_CERTIFICATE_SUPPORT */ 141 142 /** 143 * This function sends CHALLENGE to authenticate the device based upon the key in one slot. 144 * 145 * This function verifies the signature in the challenge auth. 146 * 147 * If basic mutual authentication is requested from the responder, 148 * this function also perform the basic mutual authentication. 149 * 150 * @param spdm_context A pointer to the SPDM context. 151 * @param reserved Reserved for session_id and is ignored. 152 * @param slot_id The number of slot for the challenge. 153 * @param measurement_hash_type The type of the measurement hash. 154 * @param measurement_hash A pointer to a destination buffer to store the measurement hash. 155 * @param slot_mask A pointer to a destination to store the slot mask. 156 * 157 * @retval RETURN_SUCCESS The challenge auth is got successfully. 158 * @retval RETURN_DEVICE_ERROR A device error occurs when communicates with the device. 159 * @retval RETURN_SECURITY_VIOLATION Any verification fails. 160 **/ 161 libspdm_return_t libspdm_challenge(void *spdm_context, void *reserved, 162 uint8_t slot_id, 163 uint8_t measurement_hash_type, 164 void *measurement_hash, 165 uint8_t *slot_mask); 166 167 /** 168 * This function sends CHALLENGE to authenticate the device based upon the key in one slot. 169 * 170 * This function verifies the signature in the challenge auth. 171 * 172 * If basic mutual authentication is requested from the responder, 173 * this function also performs the basic mutual authentication. 174 * 175 * @param spdm_context A pointer to the SPDM context. 176 * @param reserved Reserved for session_id and is ignored. 177 * @param slot_id The number of slot for the challenge. 178 * @param measurement_hash_type The type of the measurement hash. 179 * @param measurement_hash A pointer to a destination buffer to store the measurement hash. 180 * @param slot_mask A pointer to a destination to store the slot mask. 181 * @param requester_nonce_in A buffer to hold the requester nonce (32 bytes) as input, if not NULL. 182 * @param requester_nonce A buffer to hold the requester nonce (32 bytes), if not NULL. 183 * @param responder_nonce A buffer to hold the responder nonce (32 bytes), if not NULL. 184 * @param opaque_data A buffer to hold the responder opaque data, if not NULL. 185 * @param opaque_data_size On input, the size of the opaque data buffer. 186 * Responder opaque data should be less than 1024 bytes. 187 * On output, the size of the opaque data. 188 **/ 189 libspdm_return_t libspdm_challenge_ex(void *spdm_context, void *reserved, 190 uint8_t slot_id, 191 uint8_t measurement_hash_type, 192 void *measurement_hash, 193 uint8_t *slot_mask, 194 const void *requester_nonce_in, 195 void *requester_nonce, 196 void *responder_nonce, 197 void *opaque_data, 198 size_t *opaque_data_size); 199 200 /** 201 * This function sends GET_MEASUREMENT 202 * to get measurement from the device. 203 * 204 * If the signature is requested, this function verifies the signature of the measurement. 205 * 206 * @param spdm_context A pointer to the SPDM context. 207 * @param session_id Indicates if it is a secured message protected via SPDM session. 208 * If session_id is NULL, it is a normal message. 209 * If session_id is NOT NULL, it is a secured message. 210 * @param request_attribute The request attribute of the request message. 211 * @param measurement_operation The measurement operation of the request message. 212 * @param slot_id The number of slot for the certificate chain. 213 * @param content_changed The measurement content changed output param. 214 * @param number_of_blocks The number of blocks of the measurement record. 215 * @param measurement_record_length On input, indicate the size in bytes of the destination buffer to store the measurement record. 216 * On output, indicate the size in bytes of the measurement record. 217 * @param measurement_record A pointer to a destination buffer to store the measurement record. 218 * 219 * @retval RETURN_SUCCESS The measurement is got successfully. 220 * @retval RETURN_DEVICE_ERROR A device error occurs when communicates with the device. 221 * @retval RETURN_SECURITY_VIOLATION Any verification fails. 222 **/ 223 libspdm_return_t libspdm_get_measurement(void *spdm_context, const uint32_t *session_id, 224 uint8_t request_attribute, 225 uint8_t measurement_operation, 226 uint8_t slot_id, 227 uint8_t *content_changed, 228 uint8_t *number_of_blocks, 229 uint32_t *measurement_record_length, 230 void *measurement_record); 231 232 /** 233 * This function sends GET_MEASUREMENT to get measurement from the device. 234 * 235 * If the signature is requested, this function verifies the signature of the measurement. 236 * 237 * @param spdm_context A pointer to the SPDM context. 238 * @param session_id Indicates if it is a secured message protected via SPDM session. 239 * If session_id is NULL, it is a normal message. 240 * If session_id is NOT NULL, it is a secured message. 241 * @param request_attribute The request attribute of the request message. 242 * @param measurement_operation The measurement operation of the request message. 243 * @param slot_id The number of slot for the certificate chain. 244 * @param content_changed The measurement content changed output param. 245 * @param number_of_blocks The number of blocks of the measurement record. 246 * @param measurement_record_length On input, indicate the size in bytes of the destination buffer to store the measurement record. 247 * On output, indicate the size in bytes of the measurement record. 248 * @param measurement_record A pointer to a destination buffer to store the measurement record. 249 * @param requester_nonce_in A buffer to hold the requester nonce (32 bytes) as input, if not NULL. 250 * @param requester_nonce A buffer to hold the requester nonce (32 bytes), if not NULL. 251 * @param responder_nonce A buffer to hold the responder nonce (32 bytes), if not NULL. 252 * @param opaque_data A buffer to hold the responder opaque data, if not NULL. 253 * @param opaque_data_size On input, the size of the opaque data buffer. 254 * Responder opaque data should be less than 1024 bytes. 255 * On output, the size of the opaque data. 256 **/ 257 libspdm_return_t libspdm_get_measurement_ex(void *spdm_context, const uint32_t *session_id, 258 uint8_t request_attribute, 259 uint8_t measurement_operation, 260 uint8_t slot_id, 261 uint8_t *content_changed, 262 uint8_t *number_of_blocks, 263 uint32_t *measurement_record_length, 264 void *measurement_record, 265 const void *requester_nonce_in, 266 void *requester_nonce, 267 void *responder_nonce, 268 void *opaque_data, 269 size_t *opaque_data_size); 270 271 #if (LIBSPDM_ENABLE_CAPABILITY_KEY_EX_CAP) || (LIBSPDM_ENABLE_CAPABILITY_PSK_CAP) 272 /** 273 * This function sends KEY_EXCHANGE/FINISH or PSK_EXCHANGE/PSK_FINISH 274 * to start an SPDM Session. 275 * 276 * If encapsulated mutual authentication is requested from the responder, 277 * this function also perform the encapsulated mutual authentication. 278 * 279 * @param spdm_context A pointer to the SPDM context. 280 * @param use_psk False means to use KEY_EXCHANGE/FINISH to start a session. 281 * True means to use PSK_EXCHANGE/PSK_FINISH to start a session. 282 * @param psk_hint The psk_hint in PSK_EXCHANGE. It is ignored if use_psk is false. 283 * @param psk_hint_size The size in bytes of psk_hint. It is ignored if use_psk is false. 284 * @param measurement_hash_type The type of the measurement hash. 285 * @param slot_id The number of slot for the certificate chain. 286 * @param session_policy The policy for the session. 287 * @param session_id The session ID of the session. 288 * @param heartbeat_period The heartbeat period for the session. 289 * @param measurement_hash A pointer to a destination buffer to store the measurement hash. 290 * 291 * @retval RETURN_SUCCESS The SPDM session is started. 292 * @retval RETURN_DEVICE_ERROR A device error occurs when communicates with the device. 293 * @retval RETURN_SECURITY_VIOLATION Any verification fails. 294 **/ 295 libspdm_return_t libspdm_start_session(void *spdm_context, bool use_psk, 296 const void *psk_hint, 297 uint16_t psk_hint_size, 298 uint8_t measurement_hash_type, 299 uint8_t slot_id, 300 uint8_t session_policy, 301 uint32_t *session_id, 302 uint8_t *heartbeat_period, 303 void *measurement_hash); 304 305 /** 306 * This function sends KEY_EXCHANGE/FINISH or PSK_EXCHANGE/PSK_FINISH to start an SPDM Session. 307 * 308 * If encapsulated mutual authentication is requested from the responder, 309 * this function also perform the encapsulated mutual authentication. 310 * 311 * @param spdm_context A pointer to the SPDM context. 312 * @param use_psk False means to use KEY_EXCHANGE/FINISH to start a session. 313 * True means to use PSK_EXCHANGE/PSK_FINISH to start a session. 314 * @param psk_hint The psk_hint in PSK_EXCHANGE. It is ignored if use_psk is false. 315 * @param psk_hint_size The size in bytes of psk_hint. It is ignored if use_psk is false. 316 * @param measurement_hash_type The type of the measurement hash. 317 * @param slot_id The number of slot for the certificate chain. 318 * @param session_policy The policy for the session. 319 * @param session_id The session ID of the session. 320 * @param heartbeat_period The heartbeat period for the session. 321 * @param measurement_hash A pointer to a destination buffer to store the measurement hash. 322 * @param requester_random_in A buffer to hold the requester random as input, if not NULL. 323 * @param requester_random_in_size The size of requester_random_in. 324 * If use_psk is false, it must be 32 bytes. 325 * If use_psk is true, it means the PSK context and must be 32 bytes at least, 326 * but not exceed LIBSPDM_PSK_CONTEXT_LENGTH. 327 * @param requester_random A buffer to hold the requester random, if not NULL. 328 * @param requester_random_size On input, the size of requester_random buffer. 329 * On output, the size of data returned in requester_random buffer. 330 * If use_psk is false, it must be 32 bytes. 331 * If use_psk is true, it means the PSK context and must be 32 bytes at least. 332 * @param responder_random A buffer to hold the responder random, if not NULL. 333 * @param responder_random_size On input, the size of requester_random buffer. 334 * On output, the size of data returned in requester_random buffer. 335 * If use_psk is false, it must be 32 bytes. 336 * If use_psk is true, it means the PSK context. It could be 0 if device does not support context. 337 * @param requester_opaque_data A buffer to hold the requester opaque data, if not NULL. 338 * If not NULL, this function will not generate any opaque data, 339 * including secured message versions. 340 * @param requester_opaque_data_size The size of the opaque data, if requester_opaque_data is not NULL. 341 * @param responder_opaque_data A buffer to hold the responder opaque data, if not NULL. 342 * @param responder_opaque_data_size On input, the size of the opaque data buffer. 343 * Opaque data should be less than 1024 bytes. 344 * On output, the size of the opaque data. 345 **/ 346 libspdm_return_t libspdm_start_session_ex(void *spdm_context, bool use_psk, 347 const void *psk_hint, 348 uint16_t psk_hint_size, 349 uint8_t measurement_hash_type, 350 uint8_t slot_id, 351 uint8_t session_policy, 352 uint32_t *session_id, 353 uint8_t *heartbeat_period, 354 void *measurement_hash, 355 const void *requester_random_in, 356 size_t requester_random_in_size, 357 void *requester_random, 358 size_t *requester_random_size, 359 void *responder_random, 360 size_t *responder_random_size, 361 const void *requester_opaque_data, 362 size_t requester_opaque_data_size, 363 void *responder_opaque_data, 364 size_t *responder_opaque_data_size); 365 366 /** 367 * This function sends END_SESSION to stop an SPDM Session. 368 * 369 * @param spdm_context A pointer to the SPDM context. 370 * @param session_id The session ID of the session. 371 * @param end_session_attributes The end session attribute for the session. 372 * 373 * @retval RETURN_SUCCESS The SPDM session is stopped. 374 * @retval RETURN_DEVICE_ERROR A device error occurs when communicates with the device. 375 * @retval RETURN_SECURITY_VIOLATION Any verification fails. 376 **/ 377 libspdm_return_t libspdm_stop_session(void *spdm_context, uint32_t session_id, 378 uint8_t end_session_attributes); 379 #endif /* (LIBSPDM_ENABLE_CAPABILITY_KEY_EX_CAP) || (LIBSPDM_ENABLE_CAPABILITY_PSK_CAP) */ 380 381 /** 382 * Send an SPDM or APP message. 383 * 384 * The SPDM message can be a normal message or a secured message in SPDM session. 385 * 386 * The APP message is encoded to a secured message directly in SPDM session. 387 * The APP message format is defined by the transport layer. 388 * Take MCTP as example: APP message == MCTP header (MCTP_MESSAGE_TYPE_SPDM) + SPDM message 389 * 390 * @param spdm_context A pointer to the SPDM context. 391 * @param session_id Indicates if it is a secured message protected via SPDM session. 392 * If session_id is NULL, it is a normal message. 393 * If session_id is NOT NULL, it is a secured message. 394 * @param is_app_message Indicates if it is an APP message or SPDM message. 395 * @param request A pointer to the request data. 396 * @param request_size Size in bytes of the request data. 397 **/ 398 libspdm_return_t libspdm_send_data(void *spdm_context, const uint32_t *session_id, 399 bool is_app_message, 400 const void *request, size_t request_size); 401 402 /** 403 * Receive an SPDM or APP message. 404 * 405 * The SPDM message can be a normal message or a secured message in SPDM session. 406 * 407 * The APP message is encoded to a secured message directly in SPDM session. 408 * The APP message format is defined by the transport layer. 409 * Take MCTP as example: APP message == MCTP header (MCTP_MESSAGE_TYPE_SPDM) + SPDM message 410 * 411 * @param spdm_context A pointer to the SPDM context. 412 * @param session_id Indicates if it is a secured message protected via SPDM session. 413 * If session_id is NULL, it is a normal message. 414 * If session_id is NOT NULL, it is a secured message. 415 * @param is_app_message Indicates if it is an APP message or SPDM message. 416 * @param response A pointer to the response data. 417 * @param response_size Size in bytes of the response data. 418 * On input, it means the size in bytes of response data buffer. 419 * On output, it means the size in bytes of copied response data buffer if 420 * LIBSPDM_STATUS_SUCCESS is returned, and means the size in bytes of 421 * desired response data buffer if LIBSPDM_STATUS_BUFFER_TOO_SMALL is 422 * returned. 423 **/ 424 libspdm_return_t libspdm_receive_data(void *spdm_context, const uint32_t *session_id, 425 bool is_app_message, 426 void *response, size_t *response_size); 427 428 /** 429 * Send and receive an SPDM or APP message. 430 * 431 * The SPDM message can be a normal message or a secured message in SPDM session. 432 * 433 * The APP message is encoded to a secured message directly in SPDM session. 434 * The APP message format is defined by the transport layer. 435 * Take MCTP as example: APP message == MCTP header (MCTP_MESSAGE_TYPE_SPDM) + SPDM message 436 * 437 * @param spdm_context A pointer to the SPDM context. 438 * @param session_id Indicates if it is a secured message protected via SPDM session. 439 * If session_id is NULL, it is a normal message. 440 * If session_id is NOT NULL, it is a secured message. 441 * @param is_app_message Indicates if it is an APP message or SPDM message. 442 * @param request A pointer to the request data. 443 * @param request_size Size in bytes of the request data. 444 * @param response A pointer to the response data. 445 * @param response_size Size in bytes of the response data. 446 * On input, it means the size in bytes of response data buffer. 447 * On output, it means the size in bytes of copied response data buffer if 448 * LIBSPDM_STATUS_SUCCESS is returned, and means the size in bytes of 449 * desired response data buffer if LIBSPDM_STATUS_BUFFER_TOO_SMALL is 450 * returned. 451 **/ 452 libspdm_return_t libspdm_send_receive_data(void *spdm_context, 453 const uint32_t *session_id, 454 bool is_app_message, 455 const void *request, size_t request_size, 456 void *response, size_t *response_size); 457 458 /** 459 * This function sends HEARTBEAT 460 * to an SPDM Session. 461 * 462 * @param spdm_context A pointer to the SPDM context. 463 * @param session_id The session ID of the session. 464 * 465 * @retval RETURN_SUCCESS The heartbeat is sent and received. 466 * @retval RETURN_DEVICE_ERROR A device error occurs when communicates with the device. 467 * @retval RETURN_SECURITY_VIOLATION Any verification fails. 468 **/ 469 libspdm_return_t libspdm_heartbeat(void *spdm_context, uint32_t session_id); 470 471 /** 472 * This function sends KEY_UPDATE 473 * to update keys for an SPDM Session. 474 * 475 * After keys are updated, this function also uses VERIFY_NEW_KEY to verify the key. 476 * 477 * @param spdm_context A pointer to the SPDM context. 478 * @param session_id The session ID of the session. 479 * @param single_direction true means the operation is UPDATE_KEY. 480 * false means the operation is UPDATE_ALL_KEYS. 481 * 482 * @retval RETURN_SUCCESS The keys of the session are updated. 483 * @retval RETURN_DEVICE_ERROR A device error occurs when communicates with the device. 484 * @retval RETURN_SECURITY_VIOLATION Any verification fails. 485 **/ 486 libspdm_return_t libspdm_key_update(void *spdm_context, uint32_t session_id, bool single_direction); 487 488 /** 489 * This function executes a series of SPDM encapsulated requests and receives SPDM encapsulated responses. 490 * 491 * This function starts with the first encapsulated request (such as GET_ENCAPSULATED_REQUEST) 492 * and ends with last encapsulated response (such as RESPONSE_PAYLOAD_TYPE_ABSENT or RESPONSE_PAYLOAD_TYPE_SLOT_NUMBER). 493 * 494 * @param spdm_context A pointer to the SPDM context. 495 * @param session_id Indicate if the encapsulated request is a secured message. 496 * If session_id is NULL, it is a normal message. 497 * If session_id is not NULL, it is a secured message. 498 * 499 * @retval RETURN_SUCCESS The SPDM Encapsulated requests are sent and the responses are received. 500 * @retval RETURN_DEVICE_ERROR A device error occurs when communicates with the device. 501 **/ 502 libspdm_return_t libspdm_send_receive_encap_request(void *spdm_context, const uint32_t *session_id); 503 504 /** 505 * Process the encapsulated request and return the encapsulated response. 506 * 507 * @param spdm_context A pointer to the SPDM context. 508 * @param spdm_request_size Size in bytes of the request data. 509 * @param spdm_request A pointer to the request data. 510 * @param spdm_response_size Size in bytes of the response data. 511 * On input, it means the size in bytes of response data buffer. 512 * On output, it means the size in bytes of copied response data buffer if RETURN_SUCCESS is returned, 513 * and means the size in bytes of desired response data buffer if RETURN_BUFFER_TOO_SMALL is returned. 514 * @param spdm_response A pointer to the response data. 515 * 516 * @retval RETURN_SUCCESS The request is processed and the response is returned. 517 * @retval RETURN_BUFFER_TOO_SMALL The buffer is too small to hold the data. 518 * @retval RETURN_DEVICE_ERROR A device error occurs when communicates with the device. 519 * @retval RETURN_SECURITY_VIOLATION Any verification fails. 520 **/ 521 typedef libspdm_return_t (*libspdm_get_encap_response_func)( 522 void *spdm_context, size_t spdm_request_size, 523 void *spdm_request, size_t *spdm_response_size, 524 void *spdm_response); 525 526 /** 527 * Register an SPDM encapsulated message process function. 528 * 529 * If the default encapsulated message process function cannot handle the encapsulated message, 530 * this function will be invoked. 531 * 532 * @param spdm_context A pointer to the SPDM context. 533 * @param get_encap_response_func The function to process the encapsuled message. 534 **/ 535 void libspdm_register_get_encap_response_func(void *spdm_context, 536 const libspdm_get_encap_response_func 537 get_encap_response_func); 538 539 /** 540 * Generate encapsulated ERROR message. 541 * 542 * This function can be called in libspdm_get_encap_response_func. 543 * 544 * @param spdm_context A pointer to the SPDM context. 545 * @param error_code The error code of the message. 546 * @param error_data The error data of the message. 547 * @param spdm_response_size Size in bytes of the response data. 548 * On input, it means the size in bytes of data buffer. 549 * On output, it means the size in bytes of copied data buffer if RETURN_SUCCESS is returned, 550 * and means the size in bytes of desired data buffer if RETURN_BUFFER_TOO_SMALL is returned. 551 * @param spdm_response A pointer to the response data. 552 * 553 * @retval RETURN_SUCCESS The error message is generated. 554 * @retval RETURN_BUFFER_TOO_SMALL The buffer is too small to hold the data. 555 **/ 556 libspdm_return_t libspdm_generate_encap_error_response( 557 const void *spdm_context, uint8_t error_code, uint8_t error_data, 558 size_t *spdm_response_size, void *spdm_response); 559 560 /** 561 * Generate encapsulated ERROR message with extended error data. 562 * 563 * This function can be called in libspdm_get_encap_response_func. 564 * 565 * @param spdm_context A pointer to the SPDM context. 566 * @param error_code The error code of the message. 567 * @param error_data The error data of the message. 568 * @param extended_error_data_size The size in bytes of the extended error data. 569 * @param extended_error_data A pointer to the extended error data. 570 * @param spdm_response_size Size in bytes of the response data. 571 * On input, it means the size in bytes of response data buffer. 572 * On output, it means the size in bytes of copied response data buffer if RETURN_SUCCESS is returned, 573 * and means the size in bytes of desired response data buffer if RETURN_BUFFER_TOO_SMALL is returned. 574 * @param spdm_response A pointer to the response data. 575 * 576 * @retval RETURN_SUCCESS The error message is generated. 577 * @retval RETURN_BUFFER_TOO_SMALL The buffer is too small to hold the data. 578 **/ 579 libspdm_return_t libspdm_generate_encap_extended_error_response( 580 const void *spdm_context, uint8_t error_code, uint8_t error_data, 581 size_t extended_error_data_size, const uint8_t *extended_error_data, 582 size_t *spdm_response_size, void *spdm_response); 583 584 #if LIBSPDM_ENABLE_CAPABILITY_CSR_CAP 585 /** 586 * This function sends GET_CSR 587 * to get csr from the device. 588 * 589 * @param[in] context A pointer to the SPDM context. 590 * @param[in] session_id Indicates if it is a secured message protected via SPDM session. 591 * If session_id is NULL, it is a normal message. 592 * If session_id is NOT NULL, it is a secured message. 593 * @param[in] requester_info Requester info to gen CSR 594 * @param[in] requester_info_length The length of requester info 595 * @param[in] opaque_data Opaque data from requester. 596 * @param[in] opaque_data_length The length of opaque_data. 597 * @param[out] csr Address to store CSR. 598 * @param[out] csr_len On input, *csr_len indicates the max csr buffer size. 599 * On output, *csr_len indicates the actual csr buffer size. 600 **/ 601 libspdm_return_t libspdm_get_csr(void *spdm_context, 602 const uint32_t *session_id, 603 void *requester_info, uint16_t requester_info_length, 604 void *opaque_data, uint16_t opaque_data_length, 605 void *csr, size_t *csr_len); 606 #endif /*LIBSPDM_ENABLE_CAPABILITY_CSR_CAP*/ 607 608 #if LIBSPDM_ENABLE_CAPABILITY_SET_CERT_CAP 609 /** 610 * This function try to send SET_CERTIFICATE 611 * to set certificate from the device. 612 * 613 * @param context A pointer to the SPDM context. 614 * @param session_id Indicates if it is a secured message protected via SPDM session. 615 * If session_id is NULL, it is a normal message. 616 * If session_id is NOT NULL, it is a secured message. 617 * @param slot_id The number of slot for the certificate chain. 618 * @param cert_chain The pointer for the certificate chain to set. 619 * The cert chain is a full SPDM certificate chain, including Length and Root Cert Hash. 620 * @param cert_chain_size The size of the certificate chain to set. 621 * 622 * @retval RETURN_SUCCESS The measurement is got successfully. 623 * @retval RETURN_DEVICE_ERROR A device error occurs when communicates with the device. 624 * @retval RETURN_SECURITY_VIOLATION Any verification fails. 625 **/ 626 libspdm_return_t libspdm_set_certificate(void *spdm_context, 627 const uint32_t *session_id, uint8_t slot_id, 628 void *cert_chain, size_t cert_chain_size); 629 630 #endif /* LIBSPDM_ENABLE_CAPABILITY_SET_CERT_CAP */ 631 632 #if LIBSPDM_ENABLE_MSG_LOG 633 /* For now these functions are only available to the Requester. They may become available to the 634 * Responder at a later time. 635 */ 636 637 /** 638 * This function initializes message logging. The caller must provide a buffer and the buffer's 639 * size. 640 * 641 * @param context A pointer to the SPDM context. 642 * @param msg_buffer A pointer to a caller-provided buffer. 643 * @param msg_buffer_size The size of the buffer in bytes. It must be greater than zero. 644 **/ 645 void libspdm_init_msg_log (void *spdm_context, void *msg_buffer, size_t msg_buffer_size); 646 647 /** 648 * This function sets the mode in which the message logger operates. 649 * 650 * @param context A pointer to the SPDM context. 651 * @param mode A bitmask specifying the mode in which the message logger operates. 652 * LIBSPDM_MSG_LOG_MODE_ENABLE - when set the message logger is active. 653 */ 654 void libspdm_set_msg_log_mode (void *spdm_context, uint32_t mode); 655 656 /** 657 * This function returns the status of the message logger. 658 * 659 * @param context A pointer to the SPDM context. 660 * 661 * @retval uint32_t A bitmask giving the status of the message logger. 662 * LIBSPDM_MSG_LOG_STATUS_BUFFER_FULL - if set the message logging buffer has 663 * reached capacity. 664 */ 665 uint32_t libspdm_get_msg_log_status (void *spdm_context); 666 667 /** 668 * This function returns the size of the message log. 669 * 670 * @param context A pointer to the SPDM context. 671 * @retval size_t The size of the message log in bytes. 672 */ 673 size_t libspdm_get_msg_log_size (void *spdm_context); 674 675 /** 676 * This function resets the message log while retaining the message buffer and maximum size given in 677 * libspdm_init_msg_log. 678 * 679 * @param context A pointer to the SPDM context. 680 */ 681 void libspdm_reset_msg_log (void *spdm_context); 682 #endif /* LIBSPDM_ENABLE_MSG_LOG */ 683 684 #endif /* SPDM_REQUESTER_LIB_H */ 685