Fix more style and comments in src/crypto (project-chip#8215)

- Address comments from @bzbarsky-apple

Fixes project-chip#8208

src/crypto/CHIPCryptoPAL.h

@@ -293,7 +293,13 @@ class P256Keypair : public ECPKeypair<P256PublicKey, P256ECDHDerivedSecret, P256
      **/
     CHIP_ERROR ECDSA_sign_hash(const uint8_t * hash, size_t hash_length, P256ECDSASignature & out_signature) override;
 
-    /** @brief A function to derive a shared secret using ECDH
+    /**
+     * @brief A function to derive a shared secret using ECDH
+     *
+     * This implements the CHIP_Crypto_ECDH(PrivateKey myPrivateKey, PublicKey theirPublicKey) cryptographic primitive
+     * from the specification, using this class's private key from `mKeypair` as `myPrivateKey` and the remote
+     * public key from `remote_public_key` as `theirPublicKey`.
+     *
      * @param remote_public_key Public key of remote peer with which we are trying to establish secure channel. remote_public_key is
      * ASN.1 DER encoded as padded big-endian field elements as described in SEC 1: Elliptic Curve Cryptography
      * [https://www.secg.org/sec1-v2.pdf]
@@ -316,6 +322,10 @@ class P256Keypair : public ECPKeypair<P256PublicKey, P256ECDHDerivedSecret, P256
 
 /**
  * @brief A function that implements AES-CCM encryption
+ *
+ * This implements the CHIP_Crypto_AEAD_GenerateEncrypt() cryptographic primitive
+ * from the specification.
+ *
  * @param plaintext Plaintext to encrypt
  * @param plaintext_length Length of plain_text
  * @param aad Additional authentication data
@@ -335,6 +345,10 @@ CHIP_ERROR AES_CCM_encrypt(const uint8_t * plaintext, size_t plaintext_length, c
 
 /**
  * @brief A function that implements AES-CCM decryption
+ *
+ * This implements the CHIP_Crypto_AEAD_DecryptVerify() cryptographic primitive
+ * from the specification.
+ *
  * @param ciphertext Ciphertext to decrypt
  * @param ciphertext_length Length of ciphertext
  * @param aad Additional authentical data.
@@ -364,6 +378,10 @@ CHIP_ERROR VerifyCertificateSigningRequest(const uint8_t * csr, size_t csr_lengt
 
 /**
  * @brief A function that implements SHA-256 hash
+ *
+ * This implements the CHIP_Crypto_Hash() cryptographic primitive
+ * in the the specification.
+ *
  * @param data The data to hash
  * @param data_length Length of the data
  * @param out_buffer Pointer to buffer to write output into
@@ -416,14 +434,24 @@ class HKDF_sha
 
     /**
      * @brief A function that implements SHA-256 based HKDF
+     *
+     * This implements the CHIP_Crypto_KDF() cryptographic primitive
+     * in the the specification.
+     *
+     *  Error values are:
+     *   - CHIP_ERROR_INVALID_ARGUMENT: for any bad arguments or nullptr input on
+     *     any pointer.
+     *   - CHIP_ERROR_INTERNAL: for any unexpected error arising in the underlying
+     *     cryptographic layers.
+     *
      * @param secret The secret to use as the key to the HKDF
      * @param secret_length Length of the secret
      * @param salt Optional salt to use as input to the HKDF
      * @param salt_length Length of the salt
      * @param info Optional info to use as input to the HKDF
      * @param info_length Length of the info
      * @param out_buffer Pointer to buffer to write output into.
-     * @param out_length Resulting length of out_buffer
+     * @param out_length Size of the underlying out_buffer. That length of output key material will be generated in out_buffer.
      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
      **/
 
@@ -440,14 +468,24 @@ class HMAC_sha
     /**
      * @brief A function that implements SHA-256 based HMAC per FIPS1981.
      *
-     * The `out_length` must be at least CHIP_CRYPTO_HASH_LEN_BYTES
+     * This implements the CHIP_Crypto_HMAC() cryptographic primitive
+     * in the the specification.
+     *
+     * The `out_length` must be at least kSHA256_Hash_Length, and only
+     * kSHA256_Hash_Length bytes are written to out_buffer.
+     *
+     * Error values are:
+     *   - CHIP_ERROR_INVALID_ARGUMENT: for any bad arguments or nullptr input on
+     *     any pointer.
+     *   - CHIP_ERROR_INTERNAL: for any unexpected error arising in the underlying
+     *     cryptographic layers.
      *
      * @param key The key to use for the HMAC operation
      * @param key_length Length of the key
      * @param message Message over which to compute the HMAC
      * @param message_length Length of the message over which to compute the HMAC
-     * @param out_buffer Pointer to buffer to write output into.
-     * @param out_length Resulting length of out_buffer
+     * @param out_buffer Pointer to buffer into which to write the output.
+     * @param out_length Underlying size of the `out_buffer`.
      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
      **/
 

src/crypto/CHIPCryptoPALOpenSSL.cpp

@@ -414,7 +414,7 @@ CHIP_ERROR HMAC_sha::HMAC_SHA256(const uint8_t * key, size_t key_length, const u
     VerifyOrReturnError(key_length > 0, CHIP_ERROR_INVALID_ARGUMENT);
     VerifyOrReturnError(message != nullptr, CHIP_ERROR_INVALID_ARGUMENT);
     VerifyOrReturnError(message_length > 0, CHIP_ERROR_INVALID_ARGUMENT);
-    VerifyOrReturnError(out_length >= CHIP_CRYPTO_HASH_LEN_BYTES, CHIP_ERROR_INVALID_ARGUMENT);
+    VerifyOrReturnError(out_length >= kSHA256_Hash_Length, CHIP_ERROR_INVALID_ARGUMENT);
     VerifyOrReturnError(out_buffer != nullptr, CHIP_ERROR_INVALID_ARGUMENT);
 
     CHIP_ERROR error         = CHIP_ERROR_INTERNAL;

src/crypto/CHIPCryptoPALmbedTLS.cpp

@@ -281,7 +281,7 @@ CHIP_ERROR HMAC_sha::HMAC_SHA256(const uint8_t * key, size_t key_length, const u
     VerifyOrReturnError(key_length > 0, CHIP_ERROR_INVALID_ARGUMENT);
     VerifyOrReturnError(message != nullptr, CHIP_ERROR_INVALID_ARGUMENT);
     VerifyOrReturnError(message_length > 0, CHIP_ERROR_INVALID_ARGUMENT);
-    VerifyOrReturnError(out_length >= CHIP_CRYPTO_HASH_LEN_BYTES, CHIP_ERROR_INVALID_ARGUMENT);
+    VerifyOrReturnError(out_length >= kSHA256_Hash_Length, CHIP_ERROR_INVALID_ARGUMENT);
     VerifyOrReturnError(out_buffer != nullptr, CHIP_ERROR_INVALID_ARGUMENT);
 
     const mbedtls_md_info_t * const md = mbedtls_md_info_from_type(MBEDTLS_MD_SHA256);

src/crypto/hsm/CHIPCryptoPALHsm.h

@@ -176,10 +176,6 @@ class HKDF_shaHSM : public HKDF_sha
                                    const size_t salt_length, const uint8_t * info, const size_t info_length, uint8_t * out_buffer,
                                    size_t out_length) override;
 
-    void SetKeyId(uint32_t id) { keyid = id; }
-
-    uint32_t GetKeyId() { return keyid; }
-
 private:
     uint32_t keyid;
 };
@@ -195,11 +191,7 @@ class HMAC_shaHSM : public HMAC_sha
     ~HMAC_shaHSM();
 
     virtual CHIP_ERROR HMAC_SHA256(const uint8_t * key, size_t key_length, const uint8_t * message, size_t message_length,
-                                   uint8_t * out_buffer, size_t out_length);
-
-    void SetKeyId(uint32_t id) { keyid = id; }
-
-    uint32_t GetKeyId() { return keyid; }
+                                   uint8_t * out_buffer, size_t out_length) override;
 
 private:
     uint32_t keyid;