Added full support for Vendor Defined Requests and Responses.

New public API methods:

Responder:
libspdm_vendor_response_callback_func response_callback;
libspdm_register_vendor_callback_func( ... response_callback);

Requester:
libspdm_vendor_request(... request ... response ...);

Signed-off-by: Ionut Ursachi <[email protected]>

Author: uvinrg

CMakeLists.txt

@@ -900,6 +900,7 @@ else()
             ADD_SUBDIRECTORY(unit_test/test_spdm_crypt)
             ADD_SUBDIRECTORY(unit_test/test_spdm_fips)
             ADD_SUBDIRECTORY(unit_test/test_spdm_secured_message)
+            ADD_SUBDIRECTORY(unit_test/test_spdm_vendor_cmds)
             endif()
 
             if((NOT TOOLCHAIN STREQUAL "ARM_DS2022") AND (NOT TOOLCHAIN STREQUAL "RISCV_XPACK"))

doc/user_guide.md

@@ -249,10 +249,9 @@ Refer to spdm_client_init() in [spdm_requester.c](https://github.com/DMTF/spdm-e
 
 6. Send and receive message in an SPDM session
 
-   6.1, Use the SPDM vendor defined message.
-        (SPDM vendor defined message + transport layer header (SPDM) => application message)
+   6.1, Use the SPDM vendor defined request.
    ```
-   libspdm_send_receive_data (spdm_context, &session_id, FALSE, &request, request_size, &response, &response_size);
+   libspdm_vendor_request (spdm_context, standard_id, vendor_id_len, &vendor_id, &request, request_size, &response, &response_size);
    ```
 
    6.2, Use the transport layer application message.
@@ -435,27 +434,49 @@ Refer to spdm_server_init() in [spdm_responder.c](https://github.com/DMTF/spdm-e
 
 3. Register message process callback
 
-   This callback need handle both SPDM vendor defined message and transport layer application message.
-   ```
-   return_status libspdm_get_response_vendor_defined_request (
-     void           *spdm_context,
-     const uint32_t *session_id,
-     bool            is_app_message,
-     size_t          request_size,
-     const void     *request,
-     size_t         *response_size,
-     void           *response
-   )
-   {
-     if (is_app_message) {
-       // this is a transport layer application message
-     } else {
-       // this is a SPDM vendor defined message (without transport layer header)
-     }
-   }
-
-   libspdm_register_get_response_func (spdm_context, libspdm_get_response_vendor_defined_request);
-   ```
+   3.1 This callback handles transport layer application message.
+    ```
+    return_status libspdm_get_response (
+      void           *spdm_context,
+      const uint32_t *session_id,
+      bool            is_app_message,
+      size_t          request_size,
+      const void     *request,
+      size_t         *response_size,
+      void           *response
+    )
+    {
+      if (is_app_message) {
+        // this is a transport layer application message
+      } else {
+        // other SPDM message
+      }
+    }
+
+    libspdm_register_get_response_func (spdm_context, libspdm_get_response);
+    ```
+    3.2 This callback handles SPDM Vendor Defined Commands
+    ```
+    libspdm_return_t libspdm_vendor_response_func(
+      void *spdm_context,
+      uint16_t standard_id,
+      uint8_t vendor_id_len,
+      const void *vendor_id,
+      const void *request,
+      size_t request_len,
+      void *resp,
+      size_t *resp_len)
+    {
+      // process request and create response
+      ...
+      // populate response header and payload
+      ...
+
+      return LIBSPDM_STATUS_SUCCESS;
+    }
+
+    libspdm_register_vendor_callback_func(spdm_context, libspdm_vendor_response_func);
+    ```
 
 4. Free the memory of contexts within the SPDM context when all flow is over.
    This function doesn't free the SPDM context itself.

include/internal/libspdm_common_lib.h

@@ -606,6 +606,9 @@ typedef struct {
      * This field is ignored for other SPDM versions */
     uint8_t spdm_10_11_verify_signature_endian;
 
+#if LIBSPDM_ENABLE_VENDOR_DEFINED_MESSAGES
+    libspdm_vendor_response_callback_func vendor_response_callback;
+#endif /* LIBSPDM_ENABLE_VENDOR_DEFINED_MESSAGES */
 } libspdm_context_t;
 
 #define LIBSPDM_CONTEXT_SIZE_WITHOUT_SECURED_CONTEXT (sizeof(libspdm_context_t))

include/internal/libspdm_responder_lib.h

@@ -743,6 +743,31 @@ libspdm_return_t libspdm_get_response_chunk_send(libspdm_context_t *spdm_context
 
 #endif /* LIBSPDM_ENABLE_CAPABILITY_CHUNK_CAP */
 
+#if LIBSPDM_ENABLE_VENDOR_DEFINED_MESSAGES
+/**
+ * Process the SPDM VENDOR_DEFINED_REQUEST request and return the response.
+ *
+ * @param  spdm_context                  A pointer to the SPDM context.
+ * @param  request_size                  size in bytes of the request data.
+ * @param  request                      A pointer to the request data.
+ * @param  response_size                 size in bytes of the response data.
+ *                                     On input, it means the size in bytes of response data buffer.
+ *                                     On output, it means the size in bytes of copied response data
+ * @param  response                     A pointer to the response data.
+ *
+ * @retval RETURN_SUCCESS               The request is processed and the response is returned.
+ * @retval RETURN_BUFFER_TOO_SMALL      The buffer is too small to hold the data.
+ * @retval RETURN_DEVICE_ERROR          A device error occurs when communicates with the device.
+ * @retval RETURN_SECURITY_VIOLATION    Any verification fails.
+ **/
+
+libspdm_return_t libspdm_get_vendor_defined_response(libspdm_context_t *spdm_context,
+                                                     size_t request_size,
+                                                     const void *request,
+                                                     size_t *response_size,
+                                                     void *response);
+#endif /* LIBSPDM_ENABLE_VENDOR_DEFINED_MESSAGES */
+
 /**
  * This function allocates half of session ID for a responder.
  *

include/library/spdm_common_lib.h

@@ -946,4 +946,34 @@ uint32_t libspdm_module_version(void);
 /*true: FIPS enabled, false: FIPS disabled*/
 bool libspdm_get_fips_mode(void);
 
+#if LIBSPDM_ENABLE_VENDOR_DEFINED_MESSAGES
+
+/**
+ * Vendor Response Callback Prototype.
+ * First 2 bytes are the response length, followed by the actual response
+ *
+ * @param  spdm_context  A pointer to the SPDM context.
+ * @param  standard_id      Registry or Standards body used
+ * @param  vendor_id_len    Length in bytes of the vendor id field
+ * @param  vendor_id        Vendor ID assigned by the Registry or Standards Body. Little-endian format
+ * @param  request          The vendor defined request
+ * @param  request_len      Length of the request
+ * @param  response         The vendor defined response (including response length as first 2 bytes)
+ * @param  response_len     Length of the vendor response
+ *
+ * @retval LIBSPDM_STATUS_SUCCESS Success
+ * @retval LIBSPDM_STATUS_INVALID_PARAMETER Some parameters invalid or NULL
+ **/
+typedef libspdm_return_t (*libspdm_vendor_response_callback_func)(
+    void *spdm_context,
+    uint16_t standard_id,
+    uint8_t vendor_id_len,
+    const void *vendor_id,
+    const void *request,
+    size_t request_len,
+    void *response,
+    size_t *response_len);
+
+#endif /* LIBSPDM_ENABLE_VENDOR_DEFINED_MESSAGES */
+
 #endif /* SPDM_COMMON_LIB_H */

include/library/spdm_lib_config.h

@@ -76,6 +76,11 @@
 #define LIBSPDM_MAX_CERT_CHAIN_BLOCK_LEN 1024
 #endif
 
+/* Maximum size of a vendor defined response message */
+#ifndef LIBSPDM_MAX_VENDOR_DEFINED_RESPONSE_LEN
+#define LIBSPDM_MAX_VENDOR_DEFINED_RESPONSE_LEN 1024
+#endif
+
 /* To ensure integrity in communication between the Requester and the Responder libspdm calculates
  * cryptographic digests and signatures over multiple requests and responses. This value specifies
  * whether libspdm will use a running calculation over the transcript, where requests and responses
@@ -268,6 +273,10 @@
 #define LIBSPDM_ENABLE_CAPABILITY_CHUNK_CAP 1
 #endif
 
+#ifndef LIBSPDM_ENABLE_VENDOR_DEFINED_MESSAGES
+#define LIBSPDM_ENABLE_VENDOR_DEFINED_MESSAGES 1
+#endif
+
 /* If 1 then endpoint supports sending GET_CERTIFICATE and GET_DIGESTS requests.
  * If enabled and endpoint is a Responder then LIBSPDM_ENABLE_CAPABILITY_ENCAP_CAP
  * must also be enabled.

include/library/spdm_requester_lib.h

@@ -759,4 +759,44 @@ size_t libspdm_get_msg_log_size (void *spdm_context);
 void libspdm_reset_msg_log (void *spdm_context);
 #endif /* LIBSPDM_ENABLE_MSG_LOG */
 
+#if LIBSPDM_ENABLE_VENDOR_DEFINED_MESSAGES
+
+/**
+ * This function sends VENDOR_DEFINED_REQUEST to the device and gets back a VENDOR_DEFINED_RESPONSE.
+ *
+ * This is useful for creating unique requests/responses to devices.
+ *
+ * @param  spdm_context     A pointer to the SPDM context.
+ * @param  standard_id      Registry or Standards body used
+ * @param  vendor_id_len    Length in bytes of the vendor id field
+ * @param  vendor_id        Vendor ID assigned by the Registry or Standards Body. Little-endian format
+ * @param  request          The vendor defined request
+ * @param  request_len      Length of the request
+ * @param  response         The vendor defined response
+ * @param  response_len     Length of the vendor response
+ *
+ * @retval LIBSPDM_STATUS_SUCCESS
+ *         VENDOR_DEFINED_REQUEST was sent and VENDOR_DEFINED_RESPONSE was received.
+ * @retval LIBSPDM_STATUS_INVALID_STATE_LOCAL
+ *         Cannot send VENDOR_DEFINED_REQUEST due to Requester's state.
+ * @retval LIBSPDM_STATUS_ERROR_PEER
+ *         The Responder returned an unexpected error.
+ * @retval LIBSPDM_STATUS_BUSY_PEER
+ *         The Responder continually returned Busy error messages.
+ * @retval LIBSPDM_STATUS_RESYNCH_PEER
+ *         The Responder returned a RequestResynch error message.
+ * @retval LIBSPDM_STATUS_BUFFER_FULL
+ *         The buffer used to store transcripts is exhausted.
+ **/
+libspdm_return_t libspdm_vendor_request(void *spdm_context,
+                                        uint16_t standard_id,
+                                        uint8_t vendor_id_len,
+                                        void *vendor_id,
+                                        void *request,
+                                        size_t request_len,
+                                        void *response,
+                                        size_t *response_len);
+
+#endif /* LIBSPDM_ENABLE_VENDOR_DEFINED_MESSAGES */
+
 #endif /* SPDM_REQUESTER_LIB_H */

include/library/spdm_responder_lib.h

@@ -262,4 +262,22 @@ void libspdm_register_cert_chain_buffer(
     void *spdm_context, void *cert_chain_buffer, size_t cert_chain_buffer_max_size);
 #endif
 
+#if LIBSPDM_ENABLE_VENDOR_DEFINED_MESSAGES
+
+/**
+ * This function registers the callback function for doing a VENDOR_DEFINED_RESPONSE to the device.
+ *
+ * This is useful for creating unique requests to devices.
+ *
+ * @param  spdm_context     A pointer to the SPDM context.
+ * @param  resp_callback_func   Response callback function
+ *
+ * @retval LIBSPDM_STATUS_SUCCESS Success
+ * @retval LIBSPDM_STATUS_INVALID_PARAMETER Some parameters invalid or NULL
+ **/
+libspdm_return_t libspdm_register_vendor_callback_func(void *spdm_context,
+                                                       libspdm_vendor_response_callback_func resp_callback);
+
+#endif /* LIBSPDM_ENABLE_VENDOR_DEFINED_MESSAGES */
+
 #endif /* SPDM_RESPONDER_LIB_H */

library/spdm_requester_lib/CMakeLists.txt

@@ -29,6 +29,7 @@ SET(src_spdm_requester_lib
     libspdm_req_send_receive.c
     libspdm_req_set_certificate.c
     libspdm_req_get_csr.c
+    libspdm_req_vendor_request.c
 )
 
 ADD_LIBRARY(spdm_requester_lib STATIC ${src_spdm_requester_lib})