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

CMakeLists.txt

@@ -891,6 +891,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)
@@ -928,6 +929,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)
@@ -1063,6 +1065,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/storage.h

@@ -0,0 +1,50 @@
+/**
+ *  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
+ **/
+
+/**
+ *  Author: Wilfred Mallawa <[email protected]>
+ *          Alistair Francis <[email protected]>
+ **/
+
+/** @file
+ * Definitions of SPDM over the Storage as defined in DSP0286
+ **/
+
+#ifndef STORAGE_BINDING_H
+#define STORAGE_BINDING_H
+
+#pragma pack(1)
+
+typedef struct {
+    uint16_t data_length;
+    uint16_t storage_binding_version;
+    uint8_t max_connection_id : 2;
+    uint8_t reserved1[3];
+    uint8_t supported_operations[8];
+    uint8_t reserved2[16];
+} storage_discovery_response_t;
+
+typedef struct {
+    uint16_t data_length;
+    uint16_t storage_binding_version;
+    uint32_t pending_info_flag;
+    uint32_t response_length;
+} storage_pending_info_response_t;
+
+#define STORAGE_SECURITY_BINDING_VERSION 0x1000
+#define STORAGE_SECURITY_PROTOCOL_DMTF 0xE8
+
+#define STORAGE_OPERATION_CODE_DISCOVERY        0x01
+#define STORAGE_OPERATION_CODE_PENDING_INFO     0x02
+#define STORAGE_OPERATION_CODE_MESSAGE          0x05
+#define STORAGE_OPERATION_CODE_SECURED_MESSAGE  0x06
+
+#define STORAGE_MAX_SIZE_IN_BYTE 0x00100000
+#define STORAGE_MAX_SIZE_IN_DW 0x00040000
+
+#pragma pack()
+
+#endif /* STORAGE_BINDING_H */

include/library/spdm_transport_storage_lib.h

@@ -0,0 +1,248 @@
+/**
+ *  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
+ **/
+
+/**
+ *  Author: Wilfred Mallawa <[email protected]>
+ *          Alistair Francis <[email protected]>
+ **/
+
+#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.
+ **/
+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  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_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  transport_message_size  Size in bytes of the transport message data buffer.
+ *                                 On return, the length of the encoded message
+ * @param  transport_message       A pointer to an encoded transport message buffer.
+ * @param  transport_command       Storage transport command contained in 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_INVALID_MSG_FIELD    The message field is incorrect.
+ **/
+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 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_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;

library/spdm_transport_storage_lib/CMakeLists.txt

@@ -0,0 +1,9 @@
+cmake_minimum_required(VERSION 3.5)
+
+INCLUDE_DIRECTORIES(${LIBSPDM_DIR}/include)
+
+SET(src_spdm_transport_storage_lib
+    libspdm_storage.c
+)
+
+ADD_LIBRARY(spdm_transport_storage_lib STATIC ${src_spdm_transport_storage_lib})