diff --git a/include/Hacl_RSAPSS.h b/include/Hacl_RSAPSS.h index 8f4de949..31ff003d 100644 --- 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 index 8f4de949..31ff003d 100644 --- 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 index 19d4e5b4..2f35c6cf 100644 --- 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. diff --git a/src/msvc/Hacl_RSAPSS.c b/src/msvc/Hacl_RSAPSS.c index ce2fb517..bb74682b 100644 --- a/src/msvc/Hacl_RSAPSS.c +++ b/src/msvc/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. @@ -875,11 +885,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/tests/rsapss.cc b/tests/rsapss.cc index 029065a2..440e63e3 100644 --- a/tests/rsapss.cc +++ b/tests/rsapss.cc @@ -35,8 +35,17 @@ TEST(ApiSuite, ApiTest) generate_rsapss_key(&e, &eBits, &d, &dBits, &mod, &modBits); uint64_t* skey = Hacl_RSAPSS_new_rsapss_load_skey(modBits, eBits, dBits, mod, e, d); + + if (skey == NULL) { + //Error + } + uint64_t* pkey = Hacl_RSAPSS_new_rsapss_load_pkey(modBits, eBits, mod, e); + if (pkey == NULL) { + //Error + } + // Message const char* msg = "Hello, World!"; size_t msgLen = strlen(msg);