jyao1 / openspdm

This openspdm is a sample implementation for the DMTF SPDM specification.

This openspdm is a sample implementation for the DMTF SPDM specification

NOTE

The openspdm is moved to https://github.com/DMTF/libspdm. The temp_master branch is synced. The openspdm issue is also synced. This repo will be achieved as read-only.

Feature

1. Specification

   The SPDM and secured message follow :

   DSP0274 Security Protocol and Data Model (SPDM) Specification (version 1.0.0 and version 1.1.0)

   DSP0277 Secured Messages using SPDM Specification (version 1.0.0b)

   The MCTP and secured MCTP follow :

   DSP0275 Security Protocol and Data Model (SPDM) over MCTP Binding Specification (version 1.0.0)

   DSP0276 Secured MCTP Messages over MCTP Binding Specification (version 1.0.0a)

   The PCI DOE / IDE follow :

   PCI Data Object Exchange (DOE) ECN

   PCI Component Measurement and Authentication (CMA) ECN

   PCI Integrity and Data Encryption (IDE) ECN

2. Both SPDM requester and SPDM responder.

3. Programming Context:

   No heap is required in the SPDM lib. No writable global variable is required in the SPDM lib.

4. Implemented command and response:

   SPDM 1.0: GET_VERSION, GET_CAPABILITY, NEGOTIATE_ALGORITHM, GET_DIGEST, GET_CERTIFICATE, CHALLENGE, GET_MEASUREMENT.

   SPDM 1.1: KEY_EXCHANGE, FINISH, PSK_EXCHANGE, PSK_FINISH, END_SESSION, HEARTBEAT, KEY_UPDATE, ENCAPSULATED message

5. Cryptographic algorithm support:

   The SPDM lib requires cryptolib API, including random number, symmetric crypto, asymmetric crypto, hash and message authentication code etc.

   Current support algorithm: SHA-2, RSA-SSA/ECDSA, FFDHE/ECDHE, AES_GCM/ChaCha20Poly1305, HMAC.

   An MbedTls wrapper is included in BaseCryptLibMbedTls.

   An Openssl wrapper is included in BaseCryptLibOpenssl.

6. Execution context:

   Support to build an OS application for SpdmRequester and SpdmResponder to trace the communication.

   Support to be included in UEFI host environment EDKII, such as SpdmRequester

   Support to be included in OpenBMC. It is in planning, see SPDM Integration.

Document

1. Presentation

   Open Source Firmware Conference 2020 - openspdm

2. openspdm library design:

   The detailed design can be found at Design

3. openspdm user guide:

   The user guide can be found at UserGuide

Prerequisit

Build Tool

1. Visual Studio (VS2015 or VS2019)

2. GCC (above GCC5)

3. LLVM (LLVM9)

   Download and install LLVM9. Ensure LLVM9 executable directory is in PATH environment variable.

4. cmake. It will be used to replace makefile.

Crypto library

1. MbedTls as Crypto library

   Please download mbedtls-2.16.6 and unzip it. Rename mbedtls-2.16.6 to mbedtls and put mbedtls under MbedTlsLib

2. Openssl as crypto library

   Please download openssl-1.1.1g and unzip it. Rename openssl-1.1.1g to openssl and put openssl under OpensslLib

Unit Test framework

1. cmocka

   Please download cmocka-1.1.5 and unzip it. Rename cmocka-1.1.5 to cmocka and put cmocka under CmockaLib

Build

Windows Build:

1. Use Visual Studio

   Tool : Visual Studio 2015 (TOOLCHAIN=VS2015)

   Open visual studio 2015 command prompt at openspdm dir and type nmake ARCH=<X64|Ia32> TARGET=<DEBUG|RELEASE> CRYPTO=<MbedTls|Openssl> -e WORKSPACE=<openspdm_root_dir>. (Use x86 command prompt for ARCH=Ia32 and x64 command prompt for ARCH=X64)

   Tool : Visual Studio 2019 (TOOLCHAIN=VS2019)

   Open visual studio 2019 command prompt at openspdm dir and type nmake ARCH=<X64|Ia32> TOOLCHAIN=VS2019 TARGET=<DEBUG|RELEASE> CRYPTO=<MbedTls|Openssl> -e WORKSPACE=<openspdm_root_dir>. (Use x86 command prompt for ARCH=Ia32 and x64 command prompt for ARCH=X64)

2. Use LLVM

   Tool : LLVM x86_64-pc-windows-msvc (TOOLCHAIN=CLANG)

   Open visual studio 2019 command prompt at openspdm dir and type make ARCH=<X64|Ia32> TOOLCHAIN=CLANG TARGET=<DEBUG|RELEASE> CRYPTO=<MbedTls|Openssl> -e WORKSPACE=<openspdm_root_dir>. (Use x86 command prompt for ARCH=Ia32 and x64 command prompt for ARCH=X64)

Linux Build:

1. Use GCC

   Tool : GCC (TOOLCHAIN=GCC)

   Open command prompt at openspdm dir and type make -f GNUmakefile ARCH=<X64|Ia32> TARGET=<DEBUG|RELEASE> CRYPTO=<MbedTls|Openssl> -e WORKSPACE=<openspdm_root_dir>.

2. Use LLVM

   Tool : LLVM (TOOLCHAIN=CLANG)

   Open command prompt at openspdm dir and type make -f GNUmakefile ARCH=<X64|Ia32> TOOLCHAIN=CLANG TARGET=<DEBUG|RELEASE> CRYPTO=<MbedTls|Openssl> -e WORKSPACE=<openspdm_root_dir>.

Build with CMake

We will use CMake to replace makefile in the future, after all features are enabled. Currently, only SpdmEmu and UnitTest are enabled with VS2019 and GCC.

1. Use CMake in Linux (Toolchain=GCC|CLANG)

   cd openspdm
   mkdir build
   cd build
   cmake -DARCH=<X64|Ia32> -DTOOLCHAIN=<Toolchain> -DTARGET=<Debug|Release> -DCRYPTO=<MbedTls|Openssl> -DTESTTYPE=<SpdmEmu|UnitTest> ..
   make CopyTestKey
   make
   

2. Use CMake in Windows (Toolchain=VS2019|VS2015|CLANG)

   Use x86 command prompt for ARCH=Ia32 and x64 command prompt for ARCH=X64.

   cd openspdm
   mkdir build
   cd build
   cmake -G"NMake Makefiles" -DARCH=<X64|Ia32> -DTOOLCHAIN=<Toolchain> -DTARGET=<Debug|Release> -DCRYPTO=<MbedTls|Openssl> -DTESTTYPE=<SpdmEmu|UnitTest> ..
   nmake CopyTestKey
   nmake
   

Run Test

Run SpdmEmu

The SpdmEmu output is at openspdm/Build/<TARGET>_<TOOLCHAIN>/<ARCH>. Open one command prompt at output dir to run SpdmResponderEmu and another command prompt to run SpdmRequesterEmu.

Please refer to SpdmEmu for detail.

Run UnitTest

The UnitTest output is at openspdm/Build/<TARGET>_<TOOLCHAIN>/<ARCH>. Open one command prompt at output dir to run TestSpdmRequester > NUL and TestSpdmResponder > NUL.

You may see something like:

      [==========] Running 2 test(s).
      [ RUN      ] TestSpdmResponderVersionCase1
      [       OK ] TestSpdmResponderVersionCase1
      [ RUN      ] TestSpdmResponderVersionCase2
      [       OK ] TestSpdmResponderVersionCase2
      [==========] 2 test(s) run.
      [  PASSED  ] 2 test(s).
   

SpdmDump tool

The tool output is at openspdm/Build/<TARGET>_<TOOLCHAIN>/<ARCH>. It can be used to parse the pcap file for offline analysis.

Please refer to SpdmDump for detail.

Other Test

openspdm also supports other test such as code coverage, fuzzing, symbolic execution, model checker.

Please refer to Test for detail.

Feature not implemented yet

1. Please refer to issues for detail

Contribution

1. Please refer to contribution for detail

Known limitation

This package is only the sample code to show the concept. It does not have a full validation such as robustness functional test and fuzzing test. It does not meet the production quality yet. Any codes including the API definition, the libary and the drivers are subject to change.

openspdm's Issues

Add RSA-PSS support

All requests should use SPDM_MESSAGE_VERSION_11

With exception of GET_VERSION, all requests and responses should use SPDM_MESSAGE_VERSION_11 in header, even though those commands were first defined in 1.0.

Need handle different SPDM_KEY_EXCHANGE_RESPONSE_MUT_AUTH_REQUESTED

SPDM_KEY_EXCHANGE_RESPONSE_MUT_AUTH_REQUESTED_WITH_ENCAP_REQUEST
SPDM_KEY_EXCHANGE_RESPONSE_MUT_AUTH_REQUESTED_WITH_GET_DIGESTS

Need a better way to bind secure SPDM message transport

Current implementation uses a drafted version MTCP in SPDM lib.
We may need isolate this to support PCI DOE secure message as well.

Need add SPDM_EXTENDED_ALGORITHM support

Current code does not support SPDM_EXTENDED_ALGORITHM.

Need use DMTF OID in sample cert

4.9.2.4.3 Definition of othername using the DMTF OID

DMTFOtherName :== SEQUENCE {
type-id [0] id-DMTF-device-info
value [1] ub-DMTF-device-info
}
-- OID for DMTF device info --
id-DMTF-device-info OBJECT IDENTIFIER ::== { 1 3 6 1 4 1 412 274 1 }
-- All printable characters except ":" --
DMTF-device-string PrintableString ::== (ALL EXCEPT ":")
-- Device Manufacturer --
DMTF-manufacturer ::== DMTF-device-string
-- Device Product --
DMTF-product ::== DMTF-device-string
-- Device Serial Number --
DMTF-serialNumber ::== DMTF-device-string
-- Device information string --
ub-DMTF-device-info UTF8String ::== (DMTF-manufacturer":"DMTF-product":"DMTF-serialNumber)

Need check ENC_CAP and MAC_CAP to decide auth-only session or enc+auth session.

SPDM_DEVICE_CONTEXT for Requester and Responder

SPDM_DEVICE_CONTEXT is overloaded with both Requester and Responder context.

Suggest define SPDM_REQUESTER_CONTEXT and SPDM_RESPONDER_CONTEXT instead.

Function of SpdmGetVersion()

I think instead of returning list of Responder's supported versions to caller, function SpdmGetVersion() itself should do the comparison of its own version (currently 1.1) and Responder's supported versions and decides on the highest common version to use going forward.

Update to SPDM 1.1.0C

Current openspdm supports 1.1.0B. We need sync to latest SPDM 1.1.0C.

Need support multiple SlotNumber

The verification should be based upon the key in different slot number.

MANAGED_BUFFER, LARGE_MANAGED_BUFFER, SMALL_MANAGED_BUFFER

The code requires that MANAGED_BUFFER be the same as the first two components of LARGE/SMALL_MANAGED_BUFFER.
To facilitate such, suggest below:

typedef struct {
UINTN MaxBufferSize;
UINTN BufferSize;
//UINT8 Buffer[MaxBufferSize];
} MANAGED_BUFFER;

typedef struct {
MANAGED_BUFFER ManagedBufferSizes;
UINT8 Buffer[MAX_SPDM_MESSAGE_BUFFER_SIZE];
} LARGE_MANAGED_BUFFER;

typedef struct {
MANAGED_BUFFER ManagedBufferSizes;
UINT8 Buffer[MAX_SPDM_MESSAGE_SMALL_BUFFER_SIZE];
} SMALL_MANAGED_BUFFER;

Need support single algorithm to reduce the size

Current openspdm link all algorithm. The size of the binary is big.
A given device may only need support single algorithm (Hash/AEAD/Signing).

We need support single algorithm configuration to reduce the final binary size.

need support SPDM_END_SESSION_REQUEST_ATTRIBUTES_PRESERVE_NEGOTIATED_STATE

need remove USE_PSK macro

the test should support both KeyExchange and PskExchange without rebuild.

Need add ReqBaseAsymAlg support

Current negotiate algo only supports DHE/AEAD/KeySchedule, but misses ReqBaseAsymAlg.

Need align DHE and ECDHE crypto API.

Current DHE:
Result = DhGenerateKey (*Context, SelfPubKey, &OutKeySize);

Current ECDHE:
Result = EcGenerateKey (*Context);
ASSERT (Result);

OutKeySize = SelfKeySize;
Result = EcGetPublicKey (*Context, SelfPubKey, &OutKeySize);

need handle error when append both message to TH

need handle response not ready to resend the message and append both message to TH
other than response_not_ready, any other error message should be dropped and append neither to TH.

Need add FLAGS_CACHE_CAP support.

Currently, there is no code handling FLAGS_CACHE_CAP

Need enable CMAKE to support multiple toolchain

Need support SPDM_ENCAPSULATED_RESPONSE_ACK_RESPONSE_PAYLOAD_TYPE_SLOT_NUMBER

Support BasicMutualAuth in ChallengeAuth

Response handling code should check response header version

Response version should be 0x11.

Need check GET_DIGESTS command receive flags in SpdmGetResponseCertificate()

From SpdmResponderLibCertificate.c:

SpdmGetResponseCertificate (
IN VOID *Context,
IN UINTN RequestSize,
IN VOID *Request,
IN OUT UINTN *ResponseSize,
OUT VOID *Response
)
{
….
if ((SpdmContext->SpdmCmdReceiveState & SPDM_GET_CAPABILITIES_RECEIVE_FLAG) == 0) {
SpdmGenerateErrorResponse (SpdmContext, SPDM_ERROR_CODE_UNEXPECTED_REQUEST, 0, ResponseSize, Response);
return RETURN_SUCCESS;
}

Should we need check GET_DIGESTS command run previously?

need merge model checker branch to master

need support pre-provision public cert, with SlotId 0xFF in Challenge/Auth message.

The encryption padding data should be random size.

MCTP_MESSAGE_CIPHERTEXT_HEADER should be refined.

Add SHA3 support

Support HANDSHAKE_IN_THE_CLEAR_CAP

Need send the ERROR message (ErrorCode=DecryptError) for the decryption error

Function of GET_CAPABILITIES()

I think the GET_CAPABILITIES() should check the Flags returned from Responder and remember the set of capabilities (bits of Flags) that are set both by Requester and Responder. For this session, if caller calls a command that's not in the set of capabilities, then that command function should return error. For example, if Responder did not set CHAL_CAP, then SpdmChallenge() should return error immediately, without sending CHALLEGE to Responder.

ResetManagedBuffer type casting from caller pointer

ResetManagedBuffer (&SpdmContext->Transcript.MessageA);
ResetManagedBuffer (&SpdmContext->Transcript.MessageB);
ResetManagedBuffer (&SpdmContext->Transcript.MessageC);
ResetManagedBuffer (&SpdmContext->Transcript.M1M2);

ResetManagedBuffer() is type casting SMALL/LARGE_MANAGED_BUFFER to MANAGED_BUFFER. But they have different structures.

Need add SPDM CertChain verification

It should Include

1. the root cert hash verification
2. root cert verify intermediate cert
3. intermediate cert verify leaf cert.

Need support DEFAULT_OPAQUE_LENGTH be 0

Below code will get error if DEFAULT_OPAQUE_LENGTH is 0.

#pragma pack(1)

typedef struct {
UINT8 Nonce[SPDM_NONCE_SIZE];
UINT16 OpaqueLength;
UINT8 OpaqueData[DEFAULT_OPAQUE_LENGTH];
//UINT8 Signature[SignatureSize];
} SPDM_MEASUREMENT_SIG;

#pragma pack()

Need handle RESPOND_IF_READY

Current code does not support RESPOND_IF_READY handling.

Need add LLVM build support in windows.

Need add VS2019 build

Full error handling for SPDM1.0

According to SPDM 1.0 Spec: For an SPDM operation that results in an error, the Responder shall send an ERROR response message (with error code and error data) to the Requester.
When Requester receive the ERROR response message, Requester should do the relevant error handling.

enable LLVM libfuzzer

need append request after get the response

Current request is appended before the response is got. It violates the spec.

need remove SpdmCommonLibInternal.h from other module.

Also, the SpdmCommonLib path should be removed from -I include path.

align key schedule string to the spdm 1.1 spec

Need support PSKHint setting

Need add ExtendedErrorData generation

Current SpdmGenerateErrorResponse() only support ErrorCode and ErrorData.

need add a way to convert the SPDM plain text data to DSP0277 application data.

For example, add E-IC:0, E-MessageType=5 for MCTP.

need a way to send APP message in secure session

support multiple PSK and PSKHint

Need "Secured Messages opaque data format"

This is for secure message version control

Need handle SlotNum in SpdmGenerateSessionHandshakeKey and SpdmGenerateSessionDataKey

currently it is hardcoded as SlotNum = 0;

Need check GET_DIGEST instead of GET_CERTIFICATE in SpdmGetResponseChallenge()

In SpdmGetResponseChallenge (), it checks SPDM_GET_CERTIFICATE_RECEIVE_FLAG

if (((SpdmContext->SpdmCmdReceiveState & SPDM_NEGOTIATE_ALGORITHMS_RECEIVE_FLAG) == 0) ||
((SpdmContext->SpdmCmdReceiveState & SPDM_GET_CAPABILITIES_RECEIVE_FLAG) == 0) ||
((SpdmContext->SpdmCmdReceiveState & SPDM_GET_CERTIFICATE_RECEIVE_FLAG) == 0)) {
SpdmGenerateErrorResponse (SpdmContext, SPDM_ERROR_CODE_UNEXPECTED_REQUEST, 0, ResponseSize, Response);
return RETURN_SUCCESS;
}

According to spec, page 21, SPDM messaging protocol flow.

GET_CERTIFICATE is optional, GET_DIGESTS is required.