Improve RSAPSS documentation

Extended usage example and function info updated for general clarity, return values, endianness.
cryspen · Sep 9, 2023 · b9aed9e · b9aed9e
1 parent c6d3969
commit b9aed9e
Show file tree

Hide file tree

Showing 5 changed files with 133 additions and 72 deletions.
diff --git a/include/Hacl_RSAPSS.h b/include/Hacl_RSAPSS.h
@@ -42,10 +42,12 @@ extern "C" {
 /**
 Sign a message `msg` and write the signature to `sgnt`.
 
+@note Memory location of `sgnt` must not overlap memory locations of: `skey`, `salt`, and `msg`.
+
 @param a Hash algorithm to use. Allowed values for `a` are ...
-  * Spec_Hash_Definitions_SHA2_256,
-  * Spec_Hash_Definitions_SHA2_384, and
-  * Spec_Hash_Definitions_SHA2_512.
+  - Spec_Hash_Definitions_SHA2_256,
+  - Spec_Hash_Definitions_SHA2_384, and
+  - Spec_Hash_Definitions_SHA2_512.
 @param modBits Count of bits in the modulus (`n`).
 @param eBits Count of bits in `e` value.
 @param dBits Count of bits in `d` value.
@@ -75,7 +77,10 @@ Hacl_RSAPSS_rsapss_sign(
 /**
 Verify the signature `sgnt` of a message `msg`.
 
-@param a Hash algorithm to use.
+@param a Hash algorithm to use. Allowed values for `a` are ...
+  - Spec_Hash_Definitions_SHA2_256,
+  - Spec_Hash_Definitions_SHA2_384, and
+  - Spec_Hash_Definitions_SHA2_512.
 @param modBits Count of bits in the modulus (`n`).
 @param eBits Count of bits in `e` value.
 @param pkey Pointer to public key created by `Hacl_RSAPSS_new_rsapss_load_pkey`.
@@ -105,10 +110,10 @@ Load a public key from key parts.
 
 @param modBits Count of bits in modulus (`n`).
 @param eBits Count of bits in `e` value.
-@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`) is read from.
-@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value is read from.
+@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`), in big-endian byte order, is read from.
+@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value, in big-endian byte order, is read from.
 
-@return Returns an allocated public key. Note: caller must take care to `free()` the created key.
+@return Returns an allocated public key upon success, otherwise, `NULL` if key part arguments are invalid or memory allocation fails. Note: caller must take care to `free()` the created key.
 */
 uint64_t
 *Hacl_RSAPSS_new_rsapss_load_pkey(uint32_t modBits, uint32_t eBits, uint8_t *nb, uint8_t *eb);
@@ -119,11 +124,11 @@ Load a secret key from key parts.
 @param modBits Count of bits in modulus (`n`).
 @param eBits Count of bits in `e` value.
 @param dBits Count of bits in `d` value.
-@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`) is read from.
-@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value is read from.
-@param db Pointer to `ceil(modBits / 8)` bytes where the `d` value is read from.
+@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`), in big-endian byte order, is read from.
+@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value, in big-endian byte order, is read from.
+@param db Pointer to `ceil(modBits / 8)` bytes where the `d` value, in big-endian byte order, is read from.
 
-@return Returns an allocated secret key. Note: caller must take care to `free()` the created key.
+@return Returns an allocated secret key upon success, otherwise, `NULL` if key part arguments are invalid or memory allocation fails. Note: caller must take care to `free()` the created key.
 */
 uint64_t
 *Hacl_RSAPSS_new_rsapss_load_skey(
@@ -138,13 +143,18 @@ uint64_t
 /**
 Sign a message `msg` and write the signature to `sgnt`.
 
-@param a Hash algorithm to use.
+@note Memory location of `sgnt` must not overlap memory locations of: `nb`, `eb`, `db`, `salt`, and `msg`.
+
+@param a Hash algorithm to use. Allowed values for `a` are ...
+  - Spec_Hash_Definitions_SHA2_256,
+  - Spec_Hash_Definitions_SHA2_384, and
+  - Spec_Hash_Definitions_SHA2_512.
 @param modBits Count of bits in the modulus (`n`).
 @param eBits Count of bits in `e` value.
 @param dBits Count of bits in `d` value.
-@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`) is read from.
-@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value is read from.
-@param db Pointer to `ceil(modBits / 8)` bytes where the `d` value is read from.
+@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`), in big-endian byte order, is read from.
+@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value, in big-endian byte order, is read from.
+@param db Pointer to `ceil(modBits / 8)` bytes where the `d` value, in big-endian byte order, is read from.
 @param saltLen Length of salt.
 @param salt Pointer to `saltLen` bytes where the salt is read from.
 @param msgLen Length of message.
@@ -172,11 +182,14 @@ Hacl_RSAPSS_rsapss_skey_sign(
 /**
 Verify the signature `sgnt` of a message `msg`.
 
-@param a Hash algorithm to use.
+@param a Hash algorithm to use. Allowed values for `a` are ...
+  - Spec_Hash_Definitions_SHA2_256,
+  - Spec_Hash_Definitions_SHA2_384, and
+  - Spec_Hash_Definitions_SHA2_512.
 @param modBits Count of bits in the modulus (`n`).
 @param eBits Count of bits in `e` value.
-@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`) is read from.
-@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value is read from.
+@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`), in big-endian byte order, is read from.
+@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value, in big-endian byte order, is read from.
 @param saltLen Length of salt.
 @param sgntLen Length of signature.
 @param sgnt Pointer to `sgntLen` bytes where the signature is read from.

diff --git a/include/msvc/Hacl_RSAPSS.h b/include/msvc/Hacl_RSAPSS.h
@@ -42,10 +42,12 @@ extern "C" {
 /**
 Sign a message `msg` and write the signature to `sgnt`.
 
+@note Memory location of `sgnt` must not overlap memory locations of: `skey`, `salt`, and `msg`.
+
 @param a Hash algorithm to use. Allowed values for `a` are ...
-  * Spec_Hash_Definitions_SHA2_256,
-  * Spec_Hash_Definitions_SHA2_384, and
-  * Spec_Hash_Definitions_SHA2_512.
+  - Spec_Hash_Definitions_SHA2_256,
+  - Spec_Hash_Definitions_SHA2_384, and
+  - Spec_Hash_Definitions_SHA2_512.
 @param modBits Count of bits in the modulus (`n`).
 @param eBits Count of bits in `e` value.
 @param dBits Count of bits in `d` value.
@@ -75,7 +77,10 @@ Hacl_RSAPSS_rsapss_sign(
 /**
 Verify the signature `sgnt` of a message `msg`.
 
-@param a Hash algorithm to use.
+@param a Hash algorithm to use. Allowed values for `a` are ...
+  - Spec_Hash_Definitions_SHA2_256,
+  - Spec_Hash_Definitions_SHA2_384, and
+  - Spec_Hash_Definitions_SHA2_512.
 @param modBits Count of bits in the modulus (`n`).
 @param eBits Count of bits in `e` value.
 @param pkey Pointer to public key created by `Hacl_RSAPSS_new_rsapss_load_pkey`.
@@ -105,10 +110,10 @@ Load a public key from key parts.
 
 @param modBits Count of bits in modulus (`n`).
 @param eBits Count of bits in `e` value.
-@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`) is read from.
-@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value is read from.
+@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`), in big-endian byte order, is read from.
+@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value, in big-endian byte order, is read from.
 
-@return Returns an allocated public key. Note: caller must take care to `free()` the created key.
+@return Returns an allocated public key upon success, otherwise, `NULL` if key part arguments are invalid or memory allocation fails. Note: caller must take care to `free()` the created key.
 */
 uint64_t
 *Hacl_RSAPSS_new_rsapss_load_pkey(uint32_t modBits, uint32_t eBits, uint8_t *nb, uint8_t *eb);
@@ -119,11 +124,11 @@ Load a secret key from key parts.
 @param modBits Count of bits in modulus (`n`).
 @param eBits Count of bits in `e` value.
 @param dBits Count of bits in `d` value.
-@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`) is read from.
-@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value is read from.
-@param db Pointer to `ceil(modBits / 8)` bytes where the `d` value is read from.
+@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`), in big-endian byte order, is read from.
+@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value, in big-endian byte order, is read from.
+@param db Pointer to `ceil(modBits / 8)` bytes where the `d` value, in big-endian byte order, is read from.
 
-@return Returns an allocated secret key. Note: caller must take care to `free()` the created key.
+@return Returns an allocated secret key upon success, otherwise, `NULL` if key part arguments are invalid or memory allocation fails. Note: caller must take care to `free()` the created key.
 */
 uint64_t
 *Hacl_RSAPSS_new_rsapss_load_skey(
@@ -138,13 +143,18 @@ uint64_t
 /**
 Sign a message `msg` and write the signature to `sgnt`.
 
-@param a Hash algorithm to use.
+@note Memory location of `sgnt` must not overlap memory locations of: `nb`, `eb`, `db`, `salt`, and `msg`.
+
+@param a Hash algorithm to use. Allowed values for `a` are ...
+  - Spec_Hash_Definitions_SHA2_256,
+  - Spec_Hash_Definitions_SHA2_384, and
+  - Spec_Hash_Definitions_SHA2_512.
 @param modBits Count of bits in the modulus (`n`).
 @param eBits Count of bits in `e` value.
 @param dBits Count of bits in `d` value.
-@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`) is read from.
-@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value is read from.
-@param db Pointer to `ceil(modBits / 8)` bytes where the `d` value is read from.
+@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`), in big-endian byte order, is read from.
+@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value, in big-endian byte order, is read from.
+@param db Pointer to `ceil(modBits / 8)` bytes where the `d` value, in big-endian byte order, is read from.
 @param saltLen Length of salt.
 @param salt Pointer to `saltLen` bytes where the salt is read from.
 @param msgLen Length of message.
@@ -172,11 +182,14 @@ Hacl_RSAPSS_rsapss_skey_sign(
 /**
 Verify the signature `sgnt` of a message `msg`.
 
-@param a Hash algorithm to use.
+@param a Hash algorithm to use. Allowed values for `a` are ...
+  - Spec_Hash_Definitions_SHA2_256,
+  - Spec_Hash_Definitions_SHA2_384, and
+  - Spec_Hash_Definitions_SHA2_512.
 @param modBits Count of bits in the modulus (`n`).
 @param eBits Count of bits in `e` value.
-@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`) is read from.
-@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value is read from.
+@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`), in big-endian byte order, is read from.
+@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value, in big-endian byte order, is read from.
 @param saltLen Length of salt.
 @param sgntLen Length of signature.
 @param sgnt Pointer to `sgntLen` bytes where the signature is read from.

diff --git a/src/Hacl_RSAPSS.c b/src/Hacl_RSAPSS.c
@@ -403,10 +403,12 @@ load_skey(
 /**
 Sign a message `msg` and write the signature to `sgnt`.
 
+@note Memory location of `sgnt` must not overlap memory locations of: `skey`, `salt`, and `msg`.
+
 @param a Hash algorithm to use. Allowed values for `a` are ...
-  * Spec_Hash_Definitions_SHA2_256,
-  * Spec_Hash_Definitions_SHA2_384, and
-  * Spec_Hash_Definitions_SHA2_512.
+  - Spec_Hash_Definitions_SHA2_256,
+  - Spec_Hash_Definitions_SHA2_384, and
+  - Spec_Hash_Definitions_SHA2_512.
 @param modBits Count of bits in the modulus (`n`).
 @param eBits Count of bits in `e` value.
 @param dBits Count of bits in `d` value.
@@ -518,7 +520,10 @@ Hacl_RSAPSS_rsapss_sign(
 /**
 Verify the signature `sgnt` of a message `msg`.
 
-@param a Hash algorithm to use.
+@param a Hash algorithm to use. Allowed values for `a` are ...
+  - Spec_Hash_Definitions_SHA2_256,
+  - Spec_Hash_Definitions_SHA2_384, and
+  - Spec_Hash_Definitions_SHA2_512.
 @param modBits Count of bits in the modulus (`n`).
 @param eBits Count of bits in `e` value.
 @param pkey Pointer to public key created by `Hacl_RSAPSS_new_rsapss_load_pkey`.
@@ -637,10 +642,10 @@ Load a public key from key parts.
 
 @param modBits Count of bits in modulus (`n`).
 @param eBits Count of bits in `e` value.
-@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`) is read from.
-@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value is read from.
+@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`), in big-endian byte order, is read from.
+@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value, in big-endian byte order, is read from.
 
-@return Returns an allocated public key. Note: caller must take care to `free()` the created key.
+@return Returns an allocated public key upon success, otherwise, `NULL` if key part arguments are invalid or memory allocation fails. Note: caller must take care to `free()` the created key.
 */
 uint64_t
 *Hacl_RSAPSS_new_rsapss_load_pkey(uint32_t modBits, uint32_t eBits, uint8_t *nb, uint8_t *eb)
@@ -707,11 +712,11 @@ Load a secret key from key parts.
 @param modBits Count of bits in modulus (`n`).
 @param eBits Count of bits in `e` value.
 @param dBits Count of bits in `d` value.
-@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`) is read from.
-@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value is read from.
-@param db Pointer to `ceil(modBits / 8)` bytes where the `d` value is read from.
+@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`), in big-endian byte order, is read from.
+@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value, in big-endian byte order, is read from.
+@param db Pointer to `ceil(modBits / 8)` bytes where the `d` value, in big-endian byte order, is read from.
 
-@return Returns an allocated secret key. Note: caller must take care to `free()` the created key.
+@return Returns an allocated secret key upon success, otherwise, `NULL` if key part arguments are invalid or memory allocation fails. Note: caller must take care to `free()` the created key.
 */
 uint64_t
 *Hacl_RSAPSS_new_rsapss_load_skey(
@@ -804,13 +809,18 @@ uint64_t
 /**
 Sign a message `msg` and write the signature to `sgnt`.
 
-@param a Hash algorithm to use.
+@note Memory location of `sgnt` must not overlap memory locations of: `nb`, `eb`, `db`, `salt`, and `msg`.
+
+@param a Hash algorithm to use. Allowed values for `a` are ...
+  - Spec_Hash_Definitions_SHA2_256,
+  - Spec_Hash_Definitions_SHA2_384, and
+  - Spec_Hash_Definitions_SHA2_512.
 @param modBits Count of bits in the modulus (`n`).
 @param eBits Count of bits in `e` value.
 @param dBits Count of bits in `d` value.
-@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`) is read from.
-@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value is read from.
-@param db Pointer to `ceil(modBits / 8)` bytes where the `d` value is read from.
+@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`), in big-endian byte order, is read from.
+@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value, in big-endian byte order, is read from.
+@param db Pointer to `ceil(modBits / 8)` bytes where the `d` value, in big-endian byte order, is read from.
 @param saltLen Length of salt.
 @param salt Pointer to `saltLen` bytes where the salt is read from.
 @param msgLen Length of message.
@@ -873,11 +883,14 @@ Hacl_RSAPSS_rsapss_skey_sign(
 /**
 Verify the signature `sgnt` of a message `msg`.
 
-@param a Hash algorithm to use.
+@param a Hash algorithm to use. Allowed values for `a` are ...
+  - Spec_Hash_Definitions_SHA2_256,
+  - Spec_Hash_Definitions_SHA2_384, and
+  - Spec_Hash_Definitions_SHA2_512.
 @param modBits Count of bits in the modulus (`n`).
 @param eBits Count of bits in `e` value.
-@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`) is read from.
-@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value is read from.
+@param nb Pointer to `ceil(modBits / 8)` bytes where the modulus (`n`), in big-endian byte order, is read from.
+@param eb Pointer to `ceil(modBits / 8)` bytes where the `e` value, in big-endian byte order, is read from.
 @param saltLen Length of salt.
 @param sgntLen Length of signature.
 @param sgnt Pointer to `sgntLen` bytes where the signature is read from.