From 3b50fdce3938a8109d88a26b06c27a04c98962f4 Mon Sep 17 00:00:00 2001 From: Steven Bellock Date: Tue, 3 Oct 2023 15:10:07 -0700 Subject: [PATCH] Fix up documentation before 3.1 release Signed-off-by: Steven Bellock --- README.md | 10 +++++----- doc/aead_limit.md | 25 +++++++++++++++++-------- doc/crypto_endianness.md | 28 +++++++++++++++------------- doc/raw_public_key.md | 18 +++++++++++------- 4 files changed, 48 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 39237906019..0088ba06949 100644 --- a/README.md +++ b/README.md @@ -22,13 +22,13 @@ 2) Includes libraries that can be used to construct an SPDM Requester and an SPDM Responder. - Please refer to [libspdm API](https://github.com/DMTF/libspdm/tree/main/doc/api). + Refer to the [libspdm API](https://github.com/DMTF/libspdm/tree/main/doc/api) for more information. 3) Programming Context The core libraries in `libspdm/library` require only the C99 freestanding headers and so are suitable for embedded and systems programming. Any functionality beyond the freestanding headers is provided by `libspdm/os_stub` or by the library's Integrator. All statically allocated memory in the core libraries is read-only. The core libraries do not dynamically allocate memory. - Please refer to [programming environment](https://github.com/DMTF/libspdm/blob/main/doc/programming_environment.md). + Refer to [programming environment](https://github.com/DMTF/libspdm/blob/main/doc/programming_environment.md) for more information. 4) Implemented Requests and Responses @@ -53,9 +53,9 @@ An [OpenSSL](https://www.openssl.org/) wrapper is included in [cryptlib_openssl](https://github.com/DMTF/libspdm/tree/main/os_stub/openssllib). NOTE: SM2-KeyExchange and SM4_GCM are not supported. - Since 3.0.0, libspdm starts adding [FIPS 140-3](https://csrc.nist.gov/publications/detail/fips/140/3/final) support. Please refer to [libspdm FIPS](https://github.com/DMTF/libspdm/blob/main/doc/fips.md). + libspdm provides support for [FIPS 140-3](https://csrc.nist.gov/publications/detail/fips/140/3/final). Refer to [libspdm FIPS](https://github.com/DMTF/libspdm/blob/main/doc/fips.md) for more information. - Since 3.0.0, libspdm uses [RFC7250](https://www.rfc-editor.org/rfc/rfc7250) defined public key format. Please refer to [libspdm raw public key](https://github.com/DMTF/libspdm/blob/main/doc/raw_public_key.md). + libspdm implements a raw public key format as defined in [RFC7250](https://www.rfc-editor.org/rfc/rfc7250). Refer to [libspdm raw public key](https://github.com/DMTF/libspdm/blob/main/doc/raw_public_key.md) for more information. 6) Execution Context @@ -282,7 +282,7 @@ For other architectures, refer to [build](https://github.com/DMTF/libspdm/blob/m Refer to [test](https://github.com/DMTF/libspdm/blob/main/doc/test.md) for more details. -## Associated Repsositories +## Associated Repositories ### [spdm-emu](https://github.com/DMTF/spdm-emu) diff --git a/doc/aead_limit.md b/doc/aead_limit.md index 1b4d6b80976..c4e864f6c2f 100644 --- a/doc/aead_limit.md +++ b/doc/aead_limit.md @@ -1,17 +1,26 @@ # AEAD limit -## document +## Documents -[RFC 5116](https://www.rfc-editor.org/rfc/rfc5116) defines AEAD algorithm. [IETF AEAD Limits (Draft)](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-aead-limits) describes how to limit the use of keys in order to bound the advantage given to an attacker. +[RFC 5116](https://www.rfc-editor.org/rfc/rfc5116) defines AEAD algorithms. +[IETF AEAD Limits (Draft)](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-aead-limits) +describes how to limit the use of keys in order to bound the advantage given to an attacker. -NOTE: This is irrelevant to the plaintext bit length limitation (2^39 - 256), which is already defined in [AES-GCM](https://csrc.nist.gov/pubs/sp/800/38/d/final) 5.2.1.1. +NOTE: This is irrelevant to the plaintext bit length limitation (2^39 - 256), which is already +defined in [AES-GCM](https://csrc.nist.gov/pubs/sp/800/38/d/final) 5.2.1.1. -## sequence number based limitation +## Sequence number based limitation -[DSP0277](https://www.dmtf.org/dsp/DSP0277) defines 64bit sequence number. The default value is max number 0xFFFFFFFFFFFFFFFFull (64bit). +[DSP0277](https://www.dmtf.org/dsp/DSP0277) defines a 64-bit sequence number. The default value is +the maximum 64-bit value: 0xFFFFFFFFFFFFFFFF. -The Integrator can set `LIBSPDM_DATA_MAX_SPDM_SESSION_SEQUENCE_NUMBER` to override the default value, such as 0xFFFFFFFF (32bit) or 0xFFFFFF (24bit). +The Integrator can set `LIBSPDM_DATA_MAX_SPDM_SESSION_SEQUENCE_NUMBER` to override the default +value, such as 0xFFFFFFFF (32-bit) or 0xFFFFFF (24-bit). -The Integrator may get `LIBSPDM_DATA_SESSION_SEQUENCE_NUMBER_REQ_DIR` and `LIBSPDM_DATA_SESSION_SEQUENCE_NUMBER_RSP_DIR` to know the current number of messages that have been encrypted / decrypted in requester and responder direction, and trigger `KEY_UPDATE` flow. +The Integrator may query `LIBSPDM_DATA_SESSION_SEQUENCE_NUMBER_REQ_DIR` and +`LIBSPDM_DATA_SESSION_SEQUENCE_NUMBER_RSP_DIR` to get the current number of messages that have been +encrypted / decrypted in the request and response directions, and trigger may trigger a `KEY_UPDATE` +accordingly. -If `KEY_UPDATE` is not sent before the max sequence number is reached, the SPDM session will be terminated. +If `KEY_UPDATE` is not sent before the maximum sequence number is reached, the SPDM session will be +terminated. diff --git a/doc/crypto_endianness.md b/doc/crypto_endianness.md index f1e692d256f..a1b55e7ff61 100644 --- a/doc/crypto_endianness.md +++ b/doc/crypto_endianness.md @@ -1,28 +1,30 @@ -# Crypto Endianness +# Cryptography Endianness -## endianness of digital signature +## Endianness of digital signatures -SPDM 1.2+ defines the endianness of digital signature for RSA, ECDSA, SM2_DSA, and EdDSA. +SPDM 1.2 and later define the endianness of digital signatures for RSA, ECDSA, SM2_DSA, and EdDSA. * RSA: big endian for s. * ECDSA and SMD2_DSA: big endian for r and s. * EdDSA: big endian for R and little endian for S. -libspdm follows that for SPDM 1.2+. Because the definition aligns with existing crypto library such as OpenSSL and MbedTLS, no swap is required. +When the negotiated SPDM version is 1.2 or later libspdm follows these definitions. -SPDM 1.0 and 1.1 do not specify the endianness of the RSA and ECDSA digital signatures. +SPDM 1.0 and 1.1 did not specify the endianness of the RSA and ECDSA digital signatures. libspdm +allows an Integrator to specify the endianness when verifying RSA and ECDSA signatures through +`LIBSPDM_DATA_SPDM_VERSION_10_11_VERIFY_SIGNATURE_ENDIAN` when the negotiated SPDM version is 1.0 or +1.1. -libspdm uses big endian for RSA and ECDSA for SPDM 1.0/1.1, which algins with SPDM 1.2 and existing crypto library. No swap is required. +## Endianness of key exchange data -## endianness of key exchange data - -SPDM 1.1+ defines the endianness of key exchange data for FFDHE, ECDHE, and SM2_KeyExchange. +SPDM 1.1 and later defines the endianness of key exchange data for FFDHE, ECDHE, and SM2_KeyExchange. * FFDHE: big endian for Y. * ECDHE and SM2_KeyExchange: big endian for X and Y. libspdm follows that for SPDM 1.1+. Because the definition aligns with existing crypto library such as openssl and mbedtls, no swap is required. -## endianness of AEAD IV - -Secured SPDM 1.0/1.1 are not very clear on how to extend 64bit sequence number and XOR with the IV derived from SPDM key schedule. +## Endianness of AEAD IV -libspdm uses little endian for the sequence number for Secured SPDM 1.0/1.1, which algins with default endianness defined in SPDM 1.0+. No swap is required. +Versions 1.0 and 1.1 of the Secured Messages using SPDM specification do not explicitly specify how +the AEAD IV is formed. In particular the endianness of the sequence number is either missing (1.0) +or ill-defined (1.1). As such libspdm supports both little-endian and big-endian encoding of the +sequence number, as well as automatically swapping endianness if decryption fails. diff --git a/doc/raw_public_key.md b/doc/raw_public_key.md index 9ebfab9fc29..2c37c4f06c5 100644 --- a/doc/raw_public_key.md +++ b/doc/raw_public_key.md @@ -2,21 +2,25 @@ ## Specification -libspdm raw public key follows [RFC 7250](https://www.rfc-editor.org/rfc/rfc7250) defined public key format. +A libspdm raw public key follows the format as defined by +[RFC 7250](https://www.rfc-editor.org/rfc/rfc7250). -## Crypto Library +## Cryptography Library -libspdm calls crypto library directly to parse the raw public key. -- For OpenSSL, libspdm calls `d2i_RSA_PUBKEY_bio` for RSA, `d2i_EC_PUBKEY_bio` for ECDSA, and `d2i_PUBKEY_bio` for EdDSA and SM2DSA. -- For MbedTLS, libspdm calls `mbedtls_pk_parse_public_key` for RSA and ECDSA. EdDSA and SM2DSA are not supported. +libspdm calls the cryptography library directly to parse the raw public key. +- For OpenSSL, libspdm calls `d2i_RSA_PUBKEY_bio` for RSA, `d2i_EC_PUBKEY_bio` for ECDSA, and + `d2i_PUBKEY_bio` for EdDSA and SM2DSA. +- For MbedTLS, libspdm calls `mbedtls_pk_parse_public_key` for RSA and ECDSA. EdDSA and SM2DSA are + not supported. ## Generation -OpenSSL can be used to generate the DER based raw public key. +OpenSSL can be used to generate the DER-based raw public key. ``` openssl pkey -in end_point.key.priv.pem -inform PEM -pubout -outform DER -out end_point.key.pub.der ``` ## Registration -The Integrator can use `LIBSPDM_DATA_PEER_PUBLIC_KEY` and `LIBSPDM_DATA_LOCAL_PUBLIC_KEY` to register the raw public key based authentication. +The Integrator can use `LIBSPDM_DATA_PEER_PUBLIC_KEY` and `LIBSPDM_DATA_LOCAL_PUBLIC_KEY` to +register the raw public key.