Enhanced basic mutual authentication flow

include/internal/libspdm_common_lib.h

@@ -1,6 +1,6 @@
 /**
  *  Copyright Notice:
- *  Copyright 2021-2025 DMTF. All rights reserved.
+ *  Copyright 2021-2026 DMTF. All rights reserved.
  *  License: BSD 3-Clause License. For full text see link: https://github.com/DMTF/libspdm/blob/main/LICENSE.md
  **/
 
@@ -490,6 +490,7 @@ typedef struct {
     uint8_t req_context[SPDM_REQ_CONTEXT_SIZE];
     uint32_t session_id;
     bool use_large_cert_chain;
+    libspdm_encap_flow_type_t flow_type;
 } libspdm_encap_context_t;
 
 #if LIBSPDM_ENABLE_CAPABILITY_CHUNK_CAP
@@ -603,6 +604,9 @@ typedef struct {
      * Register can know when session keys are updated during KEY_UPDATE operations. */
     void *spdm_key_update_callback;
 
+    /* Callback function so that Integrator can specify encapsulated requests (responder only) */
+    void *encap_flow_handler_callback;
+
     libspdm_local_context_t local_context;
 
     libspdm_connection_info_t connection_info;

include/internal/libspdm_responder_lib.h

@@ -1,6 +1,6 @@
 /**
  *  Copyright Notice:
- *  Copyright 2021-2025 DMTF. All rights reserved.
+ *  Copyright 2021-2026 DMTF. All rights reserved.
  *  License: BSD 3-Clause License. For full text see link: https://github.com/DMTF/libspdm/blob/main/LICENSE.md
  **/
 
@@ -485,9 +485,9 @@ libspdm_return_t libspdm_get_response_encapsulated_response_ack(
  * @retval RETURN_SUCCESS               The encapsulated request is returned.
  * @retval RETURN_BUFFER_TOO_SMALL      The buffer is too small to hold the data.
  **/
-libspdm_return_t libspdm_get_encap_request_get_digest(libspdm_context_t *spdm_context,
-                                                      size_t *encap_request_size,
-                                                      void *encap_request);
+libspdm_return_t libspdm_get_encap_request_get_digests(libspdm_context_t *spdm_context,
+                                                       size_t *encap_request_size,
+                                                       void *encap_request);
 
 /**
  * Process the SPDM encapsulated DIGESTS response.
@@ -520,6 +520,7 @@ libspdm_return_t libspdm_process_encap_response_digest(
  * @retval RETURN_BUFFER_TOO_SMALL      The buffer is too small to hold the data.
  **/
 libspdm_return_t libspdm_get_encap_request_get_certificate(libspdm_context_t *spdm_context,
+                                                           uint8_t slot_id,
                                                            size_t *encap_request_size,
                                                            void *encap_request);
 
@@ -555,6 +556,8 @@ libspdm_return_t libspdm_process_encap_response_certificate(
  * @retval RETURN_BUFFER_TOO_SMALL      The buffer is too small to hold the data.
  **/
 libspdm_return_t libspdm_get_encap_request_challenge(libspdm_context_t *spdm_context,
+                                                     uint8_t req_slot_id,
+                                                     const void *requester_context,
                                                      size_t *encap_request_size,
                                                      void *encap_request);
 

include/library/spdm_common_lib.h

@@ -1,6 +1,6 @@
 /**
  *  Copyright Notice:
- *  Copyright 2021-2025 DMTF. All rights reserved.
+ *  Copyright 2021-2026 DMTF. All rights reserved.
  *  License: BSD 3-Clause License. For full text see link: https://github.com/DMTF/libspdm/blob/main/LICENSE.md
  **/
 
@@ -244,6 +244,23 @@ typedef enum {
     LIBSPDM_RESPONSE_STATE_MAX
 } libspdm_response_state_t;
 
+typedef enum {
+    /* Endpoint is not in an encapsulated flow. */
+    LIBSPDM_ENCAP_FLOW_NONE,
+
+    /* Endpoint is in the basic mutual authentication encapsulated flow.
+     * This state is triggered by the Responder via its CHALLENGE_AUTH response. */
+    LIBSPDM_ENCAP_FLOW_BASIC_MUT_AUTH,
+
+    /* Endpoint is in the session-based mutual authentication encapsulated flow.
+     * This state is is triggered by the Responder via its KEY_EXCHANGE_RSP response. */
+    LIBSPDM_ENCAP_FLOW_SESS_MUT_AUTH,
+
+    /* Endpoint is in a requester-initiated encapsulated flow.
+     * This state is triggered by the Requester when it sends GET_ENCAPSULATED_REQUEST. */
+    LIBSPDM_ENCAP_FLOW_REQ_INITIATED
+} libspdm_encap_flow_type_t;
+
 /* These macros apply only if the negotiated SPDM version is 1.0 or 1.1.
  * The default verification mode is big endian only. */
 #define LIBSPDM_SPDM_10_11_VERIFY_SIGNATURE_ENDIAN_BIG_ONLY 0

include/library/spdm_responder_lib.h

@@ -1,6 +1,6 @@
 /**
  *  Copyright Notice:
- *  Copyright 2021-2025 DMTF. All rights reserved.
+ *  Copyright 2021-2026 DMTF. All rights reserved.
  *  License: BSD 3-Clause License. For full text see link: https://github.com/DMTF/libspdm/blob/main/LICENSE.md
  **/
 
@@ -243,6 +243,31 @@ void libspdm_init_key_update_encap_state_with_session(
     void *spdm_context, uint32_t session_id);
 
 #if LIBSPDM_ENABLE_CAPABILITY_ENCAP_CAP
+/**
+ * This function is called when the Responder receives a GET_ENCAPSULATED_REQUEST or
+ * DELIVER_ENCAPSULATED_RESPONSE.
+ *
+ * @param  spdm_context       A pointer to the SPDM context.
+ * @param  session_id         If non-NULL, the session ID.
+ * @param  encap_flow_type    One of the LIBSPDM_ENCAP_FLOW_* values.
+ * @param  last_request_code  One of the SPDM_* request codes. If this function is called due to
+ *                            GET_ENCAPSULATED_REQUEST then its value is 0x00.
+ * @param  terminate_flow     Specifies whether to terminate the encapsulated flow or not.
+ * @param  encap_request_size Size, in bytes, of the encapsulated request.
+ * @param  encap_request      The encapsulated request.
+ **/
+typedef libspdm_return_t (*libspdm_encap_flow_handler_func)(
+    void *spdm_context,
+    const uint32_t *session_id,
+    libspdm_encap_flow_type_t encap_flow_type,
+    uint8_t last_request_code,
+    bool *terminate_flow,
+    size_t *encap_request_size,
+    void *encap_request);
+
+void libspdm_register_encap_flow_handler(void *spdm_context,
+                                         libspdm_encap_flow_handler_func encap_flow_handler);
+
 #if LIBSPDM_SEND_GET_ENDPOINT_INFO_SUPPORT
 /**
  * This function initializes the get_endpoint_info encapsulated state.

library/spdm_responder_lib/libspdm_rsp_encap_challenge.c

@@ -10,6 +10,8 @@
     (LIBSPDM_SEND_CHALLENGE_SUPPORT)
 
 libspdm_return_t libspdm_get_encap_request_challenge(libspdm_context_t *spdm_context,
+                                                     uint8_t req_slot_id,
+                                                     const void *requester_context,
                                                      size_t *encap_request_size,
                                                      void *encap_request)
 {
@@ -43,7 +45,7 @@ libspdm_return_t libspdm_get_encap_request_challenge(libspdm_context_t *spdm_con
 
     spdm_request->header.spdm_version = libspdm_get_connection_version (spdm_context);
     spdm_request->header.request_response_code = SPDM_CHALLENGE;
-    spdm_request->header.param1 = spdm_context->encap_context.req_slot_id;
+    spdm_request->header.param1 = req_slot_id;
     spdm_request->header.param2 = SPDM_CHALLENGE_REQUEST_NO_MEASUREMENT_SUMMARY_HASH;
     if (!libspdm_get_random_number(SPDM_NONCE_SIZE, spdm_request->nonce)) {
         return LIBSPDM_STATUS_LOW_ENTROPY;
@@ -52,8 +54,12 @@ libspdm_return_t libspdm_get_encap_request_challenge(libspdm_context_t *spdm_con
     LIBSPDM_INTERNAL_DUMP_DATA(spdm_request->nonce, SPDM_NONCE_SIZE);
     LIBSPDM_DEBUG((LIBSPDM_DEBUG_INFO, "\n"));
     if (spdm_request->header.spdm_version >= SPDM_MESSAGE_VERSION_13) {
-        libspdm_copy_mem(spdm_request + 1, SPDM_REQ_CONTEXT_SIZE,
-                         spdm_context->encap_context.req_context, SPDM_REQ_CONTEXT_SIZE);
+        if (requester_context == NULL) {
+            libspdm_zero_mem(spdm_request + 1, SPDM_REQ_CONTEXT_SIZE);
+        } else {
+            libspdm_copy_mem(spdm_request + 1, SPDM_REQ_CONTEXT_SIZE,
+                             requester_context, SPDM_REQ_CONTEXT_SIZE);
+        }
         LIBSPDM_DEBUG((LIBSPDM_DEBUG_INFO, "Encap RequesterContext - "));
         LIBSPDM_INTERNAL_DUMP_DATA((uint8_t *)(spdm_request + 1), SPDM_REQ_CONTEXT_SIZE);
         LIBSPDM_DEBUG((LIBSPDM_DEBUG_INFO, "\n"));

library/spdm_responder_lib/libspdm_rsp_encap_get_certificate.c

@@ -1,6 +1,6 @@
 /**
  *  Copyright Notice:
- *  Copyright 2021-2025 DMTF. All rights reserved.
+ *  Copyright 2021-2026 DMTF. All rights reserved.
  *  License: BSD 3-Clause License. For full text see link: https://github.com/DMTF/libspdm/blob/main/LICENSE.md
  **/
 
@@ -9,6 +9,7 @@
 #if (LIBSPDM_ENABLE_CAPABILITY_ENCAP_CAP) && (LIBSPDM_SEND_GET_CERTIFICATE_SUPPORT)
 
 libspdm_return_t libspdm_get_encap_request_get_certificate(libspdm_context_t *spdm_context,
+                                                           uint8_t req_slot_id,
                                                            size_t *encap_request_size,
                                                            void *encap_request)
 {
@@ -58,7 +59,7 @@ libspdm_return_t libspdm_get_encap_request_get_certificate(libspdm_context_t *sp
 
     spdm_request->header.spdm_version = libspdm_get_connection_version (spdm_context);
     spdm_request->header.request_response_code = SPDM_GET_CERTIFICATE;
-    spdm_request->header.param1 = spdm_context->encap_context.req_slot_id;
+    spdm_request->header.param1 = req_slot_id;
     spdm_request->header.param2 = 0;
     req_msg_offset = (uint32_t)spdm_context->mut_auth_cert_chain_buffer_size;
 
@@ -90,6 +91,7 @@ libspdm_return_t libspdm_get_encap_request_get_certificate(libspdm_context_t *sp
         return LIBSPDM_STATUS_BUFFER_FULL;
     }
 
+    spdm_context->encap_context.req_slot_id = req_slot_id;
     libspdm_copy_mem(&spdm_context->encap_context.last_encap_request_header,
                      sizeof(spdm_context->encap_context.last_encap_request_header),
                      &spdm_request->header, sizeof(spdm_message_header_t));

library/spdm_responder_lib/libspdm_rsp_encap_get_digests.c

@@ -1,16 +1,16 @@
 /**
  *  Copyright Notice:
- *  Copyright 2021-2025 DMTF. All rights reserved.
+ *  Copyright 2021-2026 DMTF. All rights reserved.
  *  License: BSD 3-Clause License. For full text see link: https://github.com/DMTF/libspdm/blob/main/LICENSE.md
  **/
 
 #include "internal/libspdm_responder_lib.h"
 
 #if (LIBSPDM_ENABLE_CAPABILITY_ENCAP_CAP) && (LIBSPDM_SEND_GET_CERTIFICATE_SUPPORT)
 
-libspdm_return_t libspdm_get_encap_request_get_digest(libspdm_context_t *spdm_context,
-                                                      size_t *encap_request_size,
-                                                      void *encap_request)
+libspdm_return_t libspdm_get_encap_request_get_digests(libspdm_context_t *spdm_context,
+                                                       size_t *encap_request_size,
+                                                       void *encap_request)
 {
     spdm_get_digest_request_t *spdm_request;
     libspdm_return_t status;