Fix up documentation before 3.1 release

Signed-off-by: Steven Bellock <[email protected]>

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)
 

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.

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.

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.