transport: storage: add support for SPDM over the storage binding (DSP0286)

CMakeLists.txt

@@ -894,6 +894,7 @@ if(ENABLE_CODEQL STREQUAL "ON")
     add_subdirectory(library/spdm_secured_message_lib)
     add_subdirectory(library/spdm_transport_mctp_lib)
     add_subdirectory(library/spdm_transport_pcidoe_lib)
+    ADD_SUBDIRECTORY(library/spdm_transport_storage_lib)
     add_subdirectory(os_stub/memlib)
     add_subdirectory(os_stub/debuglib)
     add_subdirectory(os_stub/debuglib_null)
@@ -931,6 +932,7 @@ else()
         add_subdirectory(library/spdm_secured_message_lib)
         add_subdirectory(library/spdm_transport_mctp_lib)
         add_subdirectory(library/spdm_transport_pcidoe_lib)
+        ADD_SUBDIRECTORY(library/spdm_transport_storage_lib)
         add_subdirectory(os_stub/memlib)
         add_subdirectory(os_stub/debuglib)
         add_subdirectory(os_stub/debuglib_null)
@@ -1004,6 +1006,8 @@ else()
             add_subdirectory(unit_test/fuzzing/test_transport/test_spdm_transport_mctp_decode_message)
             add_subdirectory(unit_test/fuzzing/test_transport/test_spdm_transport_pci_doe_encode_message)
             add_subdirectory(unit_test/fuzzing/test_transport/test_spdm_transport_pci_doe_decode_message)
+            add_subdirectory(unit_test/fuzzing/test_transport/test_spdm_transport_storage_encode_message)
+            add_subdirectory(unit_test/fuzzing/test_transport/test_spdm_transport_storage_decode_message)
             add_subdirectory(unit_test/fuzzing/test_secured_message/test_spdm_decode_secured_message)
             add_subdirectory(unit_test/fuzzing/test_secured_message/test_spdm_encode_secured_message)
             add_subdirectory(unit_test/fuzzing/test_spdm_crypt/test_x509_certificate_check)
@@ -1070,6 +1074,7 @@ else()
             $<TARGET_OBJECTS:spdm_secured_message_lib>
             $<TARGET_OBJECTS:spdm_transport_mctp_lib>
             $<TARGET_OBJECTS:spdm_transport_pcidoe_lib>
+            $<TARGET_OBJECTS:spdm_transport_storage_lib>
         )
 
         add_library(${LIB_NAME}_platform SHARED

include/industry_standard/spdm_storage_binding.h

@@ -0,0 +1,45 @@
+/**
+ *  Copyright Notice:
+ *  Copyright 2024 DMTF. All rights reserved.
+ *  License: BSD 3-Clause License. For full text see link: https://github.com/DMTF/libspdm/blob/main/LICENSE.md
+ **/
+
+/** @file
+ * Definitions of SPDM over the Storage as defined in DSP0286
+ **/
+
+#ifndef SPDM_STORAGE_BINDING_H
+#define SPDM_STORAGE_BINDING_H
+
+#pragma pack(1)
+
+typedef struct {
+    uint16_t data_length;
+    uint16_t storage_binding_version;
+    uint8_t connection_parameters;
+    uint8_t reserved1[3];
+    uint8_t supported_operations;
+    uint8_t reserved2[7];
+    uint8_t reserved3[16];
+} spdm_storage_discovery_response_t;
+
+typedef struct {
+    uint16_t data_length;
+    uint16_t storage_binding_version;
+    uint32_t pending_info_flag;
+    uint32_t response_length;
+} spdm_storage_pending_info_response_t;
+
+#define SPDM_STORAGE_SECURITY_BINDING_VERSION 0x1000
+#define SPDM_STORAGE_SECURITY_PROTOCOL_DMTF 0xE8
+
+#define SPDM_STORAGE_OPERATION_CODE_DISCOVERY        0x01
+#define SPDM_STORAGE_OPERATION_CODE_PENDING_INFO     0x02
+#define SPDM_STORAGE_OPERATION_CODE_MESSAGE          0x05
+#define SPDM_STORAGE_OPERATION_CODE_SECURED_MESSAGE  0x06
+
+#define SPDM_STORAGE_MAX_CONNECTION_ID_MASK 0x3
+
+#pragma pack()
+
+#endif /* STORAGE_BINDING_H */

include/internal/libspdm_common_lib.h

@@ -1702,7 +1702,7 @@ static inline bool libspdm_onehot0(uint32_t mask)
     return !mask || !(mask & (mask - 1));
 }
 
-static inline uint64_t libspdm_le_to_be_64(uint64_t value)
+static inline uint64_t libspdm_byte_swap_64(uint64_t value)
 {
     return (((value & 0x00000000000000ff) << 56) |
             ((value & 0x000000000000ff00) << 40) |
@@ -1714,6 +1714,20 @@ static inline uint64_t libspdm_le_to_be_64(uint64_t value)
             ((value & 0xff00000000000000) >> 56));
 }
 
+static inline uint32_t libspdm_byte_swap_32(uint32_t value)
+{
+    return ((value & 0x000000FF) << 24) |
+           ((value & 0x0000FF00) << 8)  |
+           ((value & 0x00FF0000) >> 8)  |
+           ((value & 0xFF000000) >> 24);
+}
+
+static inline uint16_t libspdm_byte_swap_16(uint16_t value)
+{
+    return ((value & 0x00FF) << 8) |
+           ((value & 0xFF00) >> 8);
+}
+
 /**
  * Return capability flags that are masked by the negotiated SPDM version.
  *

include/library/spdm_transport_storage_lib.h

@@ -0,0 +1,244 @@
+/**
+ *  Copyright Notice:
+ *  Copyright 2024 DMTF. All rights reserved.
+ *  License: BSD 3-Clause License. For full text see link: https://github.com/DMTF/libspdm/blob/main/LICENSE.md
+ **/
+
+#ifndef STORAGE_TRANSPORT_LIB_H
+#define STORAGE_TRANSPORT_LIB_H
+
+#include "library/spdm_common_lib.h"
+#include "library/spdm_crypt_lib.h"
+
+#define LIBSPDM_STORAGE_SEQUENCE_NUMBER_COUNT 0
+#define LIBSPDM_STORAGE_MAX_RANDOM_NUMBER_COUNT 0
+
+/*
+ * SPDM Storage transport binding header for request encoding as defined by
+ * DSP0286. This header is not specific to any particular storage type, i.e
+ * SCSI, NVMe or ATA. Instead, it is used to encode requests (host to controller),
+ * to provide transport specific SPDM information. This information shall then
+ * be used to generate the storage protocol specific command. Refer to the
+ * storage specification for field sizes, offsets and application.
+ *
+ * As such, this header *shall not* be transmitted as a part of the libspdm
+ * message, instead be used only as required to generate the storage specific
+ * command(s).
+ *
+ * +-----------------+--------+-------------------+---------+--------+--+
+ * |      TYPE       |Security|      Security     | INC_512 | Length |  |
+ * |                 |Protocol| Protocol Specific |         |        |  |
+ * +-----------------+--------+-------------------+---------+--------+  +
+ * |Security Protocol|    1   |         2         |    1    |  4     |  |
+ * +-----------------+--------+-------------------+---------+--------+--+
+ *
+ * This structure is publicly defined to provide transport encoding information
+ * to the caller from transport_message buffer(s).
+ */
+#pragma pack(1)
+typedef struct {
+    uint8_t security_protocol;
+    uint16_t security_protocol_specific;
+    bool inc_512;
+    uint32_t length;
+} storage_spdm_transport_header;
+#pragma pack()
+
+#define LIBSPDM_STORAGE_TRANSPORT_HEADER_SIZE  (1 + 2 + 1 + 4)
+#define LIBSPDM_STORAGE_TRANSPORT_TAIL_SIZE    (0)
+
+#define LIBSPDM_STORAGE_CMD_DIRECTION_IF_SEND 0x01
+#define LIBSPDM_STORAGE_CMD_DIRECTION_IF_RECV 0x02
+
+/**
+ * Decode an Security Protocol Command message to a normal message or secured message.
+ *
+ * @param  session_id                  Indicates if it is a secured message protected via SPDM session.
+ *                                     If *session_id is NULL, it is a normal message.
+ *                                     If *session_id is NOT NULL, it is a secured message.
+ * @param  connection_id               Indicates the connection ID of the message.
+ * @param  transport_message_size      size in bytes of the transport message data buffer.
+ * @param  transport_message           A pointer to a source buffer to store the transport message.
+ * @param  message_size                size in bytes of the message data buffer.
+ * @param  message                     A pointer to a destination buffer to store the message.
+ *
+ * @retval RETURN_SUCCESS                      The message is encoded successfully.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_SIZE     The message is NULL or the transport_message_size is zero.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_FIELD    The message field is incorrect.
+ **/
+libspdm_return_t libspdm_storage_decode_message(uint32_t **session_id,
+                                                uint8_t *connection_id,
+                                                size_t transport_message_size,
+                                                void *transport_message,
+                                                size_t *message_size,
+                                                void **message);
+/**
+ * Decode an SPDM or APP message from a storage transport layer message.
+ *
+ * For normal SPDM message, it removes the transport layer wrapper,
+ * For secured SPDM message, it removes the transport layer wrapper, then decrypts and verifies a secured message.
+ * For secured APP message, it removes the transport layer wrapper, then decrypts and verifies a secured message.
+ *
+ * The APP message is decoded from a secured message directly in SPDM session.
+ * The APP message format is defined by the transport layer.
+ * Take MCTP as example: APP message == MCTP header (MCTP_MESSAGE_TYPE_SPDM) + SPDM message
+ *
+ * @param  spdm_context            A pointer to the SPDM context.
+ * @param  session_id              Indicates if it is a secured message protected via SPDM session.
+ *                                 If session_id is NULL, it is a normal message.
+ *                                 If session_id is not NULL, it is a secured message.
+ * @param  is_app_message          Indicates if it is an APP message or SPDM message.
+ * @param  is_request_message      Indicates if it is a request message.
+ * @param  transport_message_size  Size in bytes of the transport message data buffer.
+ * @param  transport_message       A pointer to a source buffer to store the transport message.
+ *                                 For normal message or secured message, it shall point to acquired receiver buffer.
+ * @param  message_size            Size in bytes of the message data buffer.
+ * @param  message                 A pointer to a destination buffer to store the message.
+ *                                 On input, it shall point to the scratch buffer in spdm_context.
+ *                                 On output, for normal message, it will point to the original receiver buffer.
+ *                                 On output, for secured message, it will point to the scratch buffer in spdm_context.
+ *
+ * @retval RETURN_SUCCESS                      The message is decoded successfully.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_SIZE     The message is NULL or the message_size is zero.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_FIELD    The message field is incorrect.
+ * @retval LIBSPDM_STATUS_UNSUPPORTED_CAP      The transport_message is unsupported.
+ **/
+libspdm_return_t libspdm_transport_storage_decode_message(
+    void *spdm_context, uint32_t **session_id,
+    bool *is_app_message, bool is_request_message,
+    size_t transport_message_size, void *transport_message,
+    size_t *message_size, void **message);
+
+
+/**
+ * Encode a normal message or secured message to a storage transport message.
+ *
+ * @param  session_id                  Indicates if it is a secured message protected via SPDM session.
+ *                                     If *session_id is NULL, it is a normal message.
+ *                                     If *session_id is NOT NULL, it is a secured message.
+ * @param  connection_id               Indicates the connection ID of the message.
+ * @param  message_size                size in bytes of the message data buffer.
+ * @param  message                     A pointer to a destination buffer to store the message.
+ * @param  transport_message_size      Size in bytes of the transport message data buffer.
+ *                                     On return, length of the transport message.
+ * @param  transport_message           A pointer to a source buffer to store the transport message.
+ *
+ * @retval RETURN_SUCCESS                      The message is encoded successfully.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_SIZE     The message is NULL or the message_size/transport_message_size is zero.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_FIELD    The message field is incorrect.
+ * @retval LIBSPDM_STATUS_BUFFER_TOO_SMALL     Insufficient transport buffer size.
+ **/
+libspdm_return_t libspdm_storage_encode_message(const uint32_t *session_id,
+                                                uint8_t connection_id,
+                                                size_t message_size, void *message,
+                                                size_t *transport_message_size,
+                                                void **transport_message);
+
+/**
+ * Encode an SPDM or APP message into a transport layer message.
+ *
+ * @param  spdm_context            A pointer to the SPDM context.
+ * @param  session_id              Indicates if it is a secured message protected via SPDM session.
+ *                                 If session_id is NULL, it is a normal message.
+ *                                 If session_id is not NULL, it is a secured message.
+ * @param  is_app_message          Indicates if it is an APP message or SPDM message.
+ * @param  is_request_message      Indicates if it is a request message.
+ * @param  message_size            Size in bytes of the message data buffer.
+ * @param  message                 A pointer to a destination buffer to store the message.
+ *                                 On input, it shall point to the scratch buffer in spdm_context.
+ *                                 On output, for normal message, it will point to the original receiver buffer.
+ *                                 On output, for secured message, it will point to the scratch buffer in spdm_context.
+ * @param  transport_message_size  Size in bytes of the transport message data buffer.
+ * @param  transport_message       A pointer to a source buffer to store the transport message.
+ *                                 For normal message or secured message, it shall point to acquired receiver buffer.
+ *
+ * @retval RETURN_SUCCESS                      The message is decoded successfully.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_SIZE     The message is NULL or the message_size is zero.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_FIELD    The message field is incorrect.
+ * @retval LIBSPDM_STATUS_UNSUPPORTED_CAP      The transport_message is unsupported.
+ **/
+libspdm_return_t libspdm_transport_storage_encode_message(
+    void *spdm_context, const uint32_t *session_id,
+    bool is_app_message,
+    bool is_request_message, size_t message_size, void *message,
+    size_t *transport_message_size, void **transport_message);
+
+/**
+ * Decode a storage transport management command
+ *
+ * @param  transport_message_size  Size in bytes of the transport message data buffer.
+ * @param  transport_message       A pointer to an encoded transport message buffer.
+ * @param  transport_command       Storage transport command contained in transport message
+ * @param  length                  On return, this specifies allocation length
+ *                                 or transfer length. Depending of if the
+ *                                 message was an IF_RECV or IF_SEND respectively.
+ *
+ * @retval RETURN_SUCCESS                      The message is decoded successfully.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_SIZE     The message is NULL or the message_size is zero.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_FIELD    The message field is incorrect.
+ * @retval LIBSPDM_STATUS_UNSUPPORTED_CAP      The transport_message is unsupported.
+ **/
+libspdm_return_t libspdm_transport_storage_decode_management_cmd(
+    size_t transport_message_size,
+    const void *transport_message,
+    uint8_t *transport_command,
+    uint32_t *length);
+
+/**
+ * Encode a storage transport management command, supports only Discovery and
+ * Pending Info.
+ *
+ * @param  cmd_direction           Specify the direction of the command IF_SEND/RECV
+ * @param  transport_operation     Transport operation type, Discovery/Pending Info
+ * @param  connection_id           SPDM Connection ID
+ * @param  transport_message_size  Size in bytes of the transport message data buffer.
+ *                                 On return, the length of the encoded message
+ * @param  allocation_length       Storage buffer allocation length
+ * @param  transport_message       A pointer to a transport message buffer.
+ *
+ * @retval RETURN_SUCCESS                      The message is encoded successfully.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_SIZE     The message is NULL or the message_size is zero.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_FIELD    The message field is incorrect.
+ * @retval LIBSPDM_STATUS_BUFFER_TOO_SMALL     Insufficient transport buffer size
+ **/
+libspdm_return_t libspdm_transport_storage_encode_management_cmd(
+    uint8_t cmd_direction, uint8_t transport_operation,
+    uint8_t connection_id, size_t *transport_message_size,
+    size_t *allocation_length, void *transport_message);
+
+/**
+ * Encode a storage transport discovery response. As defined by the DMTF DSP0286
+ *
+ * @param  transport_message_size  Size in bytes of the transport message data buffer.
+ *                                 On return, the size of the response
+ * @param  transport_message       A pointer to a source buffer to store the transport message.
+ *
+ * @retval RETURN_SUCCESS                      The message is decoded successfully.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_SIZE     The message is NULL or the message_size is zero.
+ * @retval LIBSPDM_STATUS_BUFFER_TOO_SMALL     @transport_message is too small
+ **/
+libspdm_return_t libspdm_transport_storage_encode_discovery_response(
+    size_t *transport_message_size,
+    void *transport_message);
+
+/**
+ * Encode a storage transport pending response. As defined by the DMTF DSP0286
+ *
+ * @param  transport_message_size  Size in bytes of the transport message data buffer.
+ *                                 On return, the size of the response
+ * @param  transport_message       A pointer to a source buffer to store the transport message.
+ * @param  response_pending        If true, the responder has a pending response
+ * @param  pending_response_length Valid only if @response_pending is true,
+ *                                 specifies the length of the pending message
+ *                                 in bytes.
+ *
+ * @retval RETURN_SUCCESS                      The message is decoded successfully.
+ * @retval LIBSPDM_STATUS_INVALID_MSG_SIZE     The message is NULL or the message_size is zero.
+ * @retval LIBSPDM_STATUS_BUFFER_TOO_SMALL     @transport_message is too small
+ **/
+libspdm_return_t libspdm_transport_storage_encode_pending_info_response(
+    size_t *transport_message_size,
+    void *transport_message, bool response_pending,
+    uint32_t pending_response_length);
+
+#endif /* STORAGE_TRANSPORT_LIB_H */

library/spdm_requester_lib/libspdm_req_send_receive.c

@@ -131,7 +131,7 @@ libspdm_return_t libspdm_receive_response(void *spdm_context, const uint32_t *se
     libspdm_return_t status;
     uint8_t *message;
     size_t message_size;
-    uint32_t *message_session_id;
+    uint32_t *message_session_id, message_id;
     bool is_message_app_message;
     uint64_t timeout;
     size_t transport_header_size;
@@ -163,7 +163,22 @@ libspdm_return_t libspdm_receive_response(void *spdm_context, const uint32_t *se
         return status;
     }
 
-    message_session_id = NULL;
+    /*
+     * The storage transport encoding, defined by DSP0286, does not indicate
+     * if we are/are not in a secure session in the transport data. This is
+     * different to most other transport encodings, which includes session
+     * information in the encoding.
+     *
+     * As such if we are in a secure session, session_id != NULL, we set
+     * message_session_id to be non-NULL to indicate to the lower layer
+     * that we are in a secure session.
+     */
+    if (session_id != NULL) {
+        message_session_id = &message_id;
+        message_id = *session_id;
+    } else {
+        message_session_id = NULL;
+    }
     is_message_app_message = false;
 
     /* always use scratch buffer to response.
@@ -211,7 +226,11 @@ libspdm_return_t libspdm_receive_response(void *spdm_context, const uint32_t *se
 
         /* Retry decoding message with backup Requester key.
          * Must reset some of the parameters in case they were modified */
-        message_session_id = NULL;
+        if (session_id != NULL) {
+            *message_session_id = *session_id;
+        } else {
+            message_session_id = NULL;
+        }
         is_message_app_message = false;
         *response = backup_response;
         *response_size = backup_response_size;