diff --git a/doc/dox_comments/header_files/rsa.h b/doc/dox_comments/header_files/rsa.h index 494ced2ad..55cd3cfb1 100644 --- a/doc/dox_comments/header_files/rsa.h +++ b/doc/dox_comments/header_files/rsa.h @@ -387,7 +387,7 @@ WOLFSSL_API int wc_RsaPSS_Sign(const byte* in, word32 inLen, byte* out, /*! \ingroup RSA - \brief Decrypt input singature to verify that the message was signed by key. + \brief Decrypt input signature to verify that the message was signed by key. \return Success Length of text on no error. \return MEMORY_E memory exception. @@ -441,7 +441,7 @@ WOLFSSL_API int wc_RsaPSS_Verify(byte* in, word32 inLen, byte* out, /*! \ingroup RSA - \brief Decript input singature to verify that the message was signed by RSA key. + \brief Decrypt input signature to verify that the message was signed by RSA key. The output uses the same byte array as the input. \return >0 Length of text. @@ -449,7 +449,7 @@ WOLFSSL_API int wc_RsaPSS_Verify(byte* in, word32 inLen, byte* out, \param in Byte array to be decrypted. \param inLen Length of the buffer input. - \param out Pointer to a pointer for decrypted information. + \param out Pointer to address containing the PSS data. \param hash The hash type to be in message \param mgf Mask Generation Function Identifiers \param key RsaKey to use. @@ -482,28 +482,36 @@ WOLFSSL_API int wc_RsaPSS_Verify(byte* in, word32 inLen, byte* out, \sa wc_RsaPSS_Verify \sa wc_RsaPSS_Sign + \sa wc_RsaPSS_VerifyCheck + \sa wc_RsaPSS_VerifyCheck_ex + \sa wc_RsaPSS_VerifyCheckInline + \sa wc_RsaPSS_VerifyCheckInline_ex \sa wc_RsaPSS_CheckPadding + \sa wc_RsaPSS_CheckPadding_ex */ + WOLFSSL_API int wc_RsaPSS_VerifyInline(byte* in, word32 inLen, byte** out, enum wc_HashType hash, int mgf, RsaKey* key); /*! \ingroup RSA - \brief Decript singature to verify that the message was signed by key with checking - the padding. + \brief Verify the message signed with RSA-PSS. + Salt length is equal to hash length. - \return Success Length of text on no error. + \return the length of the PSS data on success and negative indicates failure. \return MEMORY_E memory exception. \param in The byte array to be decrypted. \param inLen The length of in. - \param out The byte array for the decrypted data to be stored. + \param out Pointer to address containing the PSS data. \param outLen The length of out. - \param hash The hash type to be in message - \param mgf Mask Generation Function Identifiers - \param key The key to use for verification. + \param digest Hash of the data that is being verified. + \param digestLen Length of hash. + \param hash Hash algorithm. + \param mgf Mask generation function. + \param key Public RSA key. _Example_ \code @@ -542,7 +550,13 @@ WOLFSSL_API int wc_RsaPSS_VerifyInline(byte* in, word32 inLen, byte** out, \sa wc_RsaPSS_Sign \sa wc_RsaPSS_Verify + \sa wc_RsaPSS_VerifyCheck_ex + \sa wc_RsaPSS_VerifyCheckInline + \sa wc_RsaPSS_VerifyCheckInline_ex + \sa wc_RsaPSS_CheckPadding + \sa wc_RsaPSS_CheckPadding_ex */ + WOLFSSL_API int wc_RsaPSS_VerifyCheck(byte* in, word32 inLen, byte* out, word32 outLen, const byte* digest, word32 digestLen, @@ -551,16 +565,88 @@ WOLFSSL_API int wc_RsaPSS_VerifyCheck(byte* in, word32 inLen, /*! \ingroup RSA - \brief Decript singature to verify that the message was signed by key with checking - the padding. The output uses the same byte array as the input. + \brief Verify the message signed with RSA-PSS. - \return Success Length of text on no error. + \return the length of the PSS data on success and negative indicates failure. \return MEMORY_E memory exception. \param in The byte array to be decrypted. \param inLen The length of in. - \param out The byte array for the decrypted data to be stored. + \param out Pointer to address containing the PSS data. \param outLen The length of out. + \param digest Hash of the data that is being verified. + \param digestLen Length of hash. + \param hash Hash algorithm. + \param mgf Mask generation function. + \param saltLen Length of salt used. RSA_PSS_SALT_LEN_DEFAULT (-1) indicates salt + length is the same as the hash length. RSA_PSS_SALT_LEN_DISCOVER + indicates salt length is determined from the data. + + \param key Public RSA key. + + _Example_ + \code + ret = wc_InitRsaKey(&key, NULL); + if (ret == 0) { + ret = wc_InitRng(&rng); + } else return -1; + if (ret == 0) { + ret = wc_RsaSetRNG(&key, &rng); + } else return -1; + if (ret == 0) { + ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng); + } else return -1; + + if (ret == 0) { + digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256); + ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz); + } else return -1; + + if (ret == 0) { + ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz, + WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng); + if (ret > 0 ){ + sz = ret; + } else return -1; + } else return -1; + if (ret == 0) { + ret = wc_RsaPSS_VerifyCheck_ex(pSignature, sz, pt, outLen, + digest, digestSz, WC_HASH_TYPE_SHA256, WC_MGF1SHA256, saltLen, &key); + if (ret <= 0) return -1; + } else return -1; + + wc_FreeRsaKey(&key); + wc_FreeRng(&rng); + \endcode + + \sa wc_RsaPSS_Sign + \sa wc_RsaPSS_Verify + \sa wc_RsaPSS_VerifyCheck + \sa wc_RsaPSS_VerifyCheckInline + \sa wc_RsaPSS_VerifyCheckInline_ex + \sa wc_RsaPSS_CheckPadding + \sa wc_RsaPSS_CheckPadding_ex +*/ +WOLFSSL_API int wc_RsaPSS_VerifyCheck_ex(byte* in, word32 inLen, + byte* out, word32 outLen, + const byte* digest, word32 digestLen, + enum wc_HashType hash, int mgf, int saltLen, + RsaKey* key); + +/*! + \ingroup RSA + + \brief Verify the message signed with RSA-PSS. + The input buffer is reused for the output buffer. + Salt length is equal to hash length. + + \return the length of the PSS data on success and negative indicates failure. + + \param in The byte array to be decrypted. + \param inLen The length of in. + \param out The byte array for the decrypted data to be stored. + \param digest Hash of the data that is being verified. + \param digestLen Length of hash. \param hash The hash type to be in message \param mgf Mask Generation Function Identifiers \param key The key to use for verification. @@ -602,25 +688,100 @@ WOLFSSL_API int wc_RsaPSS_VerifyCheck(byte* in, word32 inLen, \sa wc_RsaPSS_Sign \sa wc_RsaPSS_Verify + \sa wc_RsaPSS_VerifyCheck + \sa wc_RsaPSS_VerifyCheck_ex + \sa wc_RsaPSS_VerifyCheckInline_ex + \sa wc_RsaPSS_CheckPadding + \sa wc_RsaPSS_CheckPadding_ex */ WOLFSSL_API int wc_RsaPSS_VerifyCheckInline(byte* in, word32 inLen, byte** out, const byte* digest, word32 digentLen, enum wc_HashType hash, int mgf, RsaKey* key); +/*! + \ingroup RSA + + \brief Verify the message signed with RSA-PSS. + The input buffer is reused for the output buffer. + + \return the length of the PSS data on success and negative indicates failure. + + \param in The byte array to be decrypted. + \param inLen The length of in. + \param out The byte array for the decrypted data to be stored. + \param digest Hash of the data that is being verified. + \param digestLen Length of hash. + \param hash The hash type to be in message + \param mgf Mask Generation Function Identifiers + \param saltLen Length of salt used. RSA_PSS_SALT_LEN_DEFAULT (-1) indicates salt + length is the same as the hash length. RSA_PSS_SALT_LEN_DISCOVER + indicates salt length is determined from the data. + \param key The key to use for verification. + + _Example_ + \code + ret = wc_InitRsaKey(&key, NULL); + if (ret == 0) { + ret = wc_InitRng(&rng); + } else return -1; + if (ret == 0) { + ret = wc_RsaSetRNG(&key, &rng); + } else return -1; + if (ret == 0) { + ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng); + } else return -1; + + if (ret == 0) { + digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256); + ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz); + } else return -1; + + if (ret == 0) { + ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz, + WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng); + if (ret > 0 ){ + sz = ret; + } else return -1; + } else return -1; + if (ret == 0) { + ret = wc_RsaPSS_VerifyCheckInline_ex(pSignature, sz, pt, + digest, digestSz, WC_HASH_TYPE_SHA256, WC_MGF1SHA256, saltLen, &key); + if (ret <= 0) return -1; + } else return -1; + + wc_FreeRsaKey(&key); + wc_FreeRng(&rng); + \endcode + + \sa wc_RsaPSS_Sign + \sa wc_RsaPSS_Verify + \sa wc_RsaPSS_VerifyCheck + \sa wc_RsaPSS_VerifyCheck_ex + \sa wc_RsaPSS_VerifyCheckInline + \sa wc_RsaPSS_CheckPadding + \sa wc_RsaPSS_CheckPadding_ex +*/ +WOLFSSL_API int wc_RsaPSS_VerifyCheckInline_ex(byte* in, word32 inLen, byte** out, + const byte* digest, word32 digentLen, + enum wc_HashType hash, int mgf, int saltLen, + RsaKey* key); /*! \ingroup RSA - \brief Decript singature to verify that the message was signed by key and check the padding. - The output uses the same byte array as the input. + \brief Checks the PSS data to ensure that the signature matches. + Salt length is equal to hash length. - \return Success Length of text on no error. + \return BAD_PADDING_E when the PSS data is invalid, BAD_FUNC_ARG when + NULL is passed in to in or sig or inSz is not the same as the hash + algorithm length and 0 on success. \return MEMORY_E memory exception. - \param digest The byte array to be decrypted. - \param digestSz The length of in. - \param verify The byte array for the decrypted data to be stored. - \param hash The hash type to be in message + \param in Hash of the data that is being verified. + \param inSz Length of hash. + \param sig Buffer holding PSS data. + \param sigSz Size of PSS data. + \param hashType Hash algorithm. _Example_ \code @@ -657,6 +818,11 @@ WOLFSSL_API int wc_RsaPSS_VerifyCheckInline(byte* in, word32 inLen, byte** out, \sa wc_RsaPSS_Sign \sa wc_RsaPSS_Verify \sa wc_RsaPSS_VerifyInline + \sa wc_RsaPSS_VerifyCheck + \sa wc_RsaPSS_VerifyCheck_ex + \sa wc_RsaPSS_VerifyCheckInline + \sa wc_RsaPSS_VerifyCheckInline_ex + \sa wc_RsaPSS_CheckPadding_ex */ WOLFSSL_API int wc_RsaPSS_CheckPadding(const byte* in, word32 inLen, byte* sig, word32 sigSz, @@ -664,6 +830,70 @@ WOLFSSL_API int wc_RsaPSS_CheckPadding(const byte* in, word32 inLen, byte* sig, /*! \ingroup RSA + \brief Checks the PSS data to ensure that the signature matches. + Salt length is equal to hash length. + + \return BAD_PADDING_E when the PSS data is invalid, BAD_FUNC_ARG when + NULL is passed in to in or sig or inSz is not the same as the hash + algorithm length and 0 on success. + \return MEMORY_E memory exception. + + \param in Hash of the data that is being verified. + \param inSz Length of hash. + \param sig Buffer holding PSS data. + \param sigSz Size of PSS data. + \param hashType Hash algorithm. + \param saltLen Length of salt used. RSA_PSS_SALT_LEN_DEFAULT (-1) indicates salt + length is the same as the hash length. RSA_PSS_SALT_LEN_DISCOVER + indicates salt length is determined from the data. + \param bits igonred + + _Example_ + \code + ret = wc_InitRsaKey(&key, NULL); + if (ret == 0) { + ret = wc_InitRng(&rng); + } else return -1; + if (ret == 0) { + ret = wc_RsaSetRNG(&key, &rng); + } else return -1; + if (ret == 0) { + ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng); + } else return -1; + if (ret == 0) { + digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256); + ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz); + } else return -1; + ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, sizeof(pSignature), + WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng); + if (ret > 0 ){ + sz = ret; + } else return -1; + + verify = wc_RsaPSS_Verify(pSignature, sz, out, outLen, + WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key); + if (verify <= 0)return -1; + + ret = wc_RsaPSS_CheckPadding_ex(digest, digestSz, out, verify, hash, saltLen, 0); + + wc_FreeRsaKey(&key); + wc_FreeRng(&rng); + \endcode + + \sa wc_RsaPSS_Sign + \sa wc_RsaPSS_Verify + \sa wc_RsaPSS_VerifyInline + \sa wc_RsaPSS_VerifyCheck + \sa wc_RsaPSS_VerifyCheck_ex + \sa wc_RsaPSS_VerifyCheckInline + \sa wc_RsaPSS_VerifyCheckInline_ex + \sa wc_RsaPSS_CheckPadding +*/ +WOLFSSL_API int wc_RsaPSS_CheckPadding_ex(const byte* in, word32 inLen, byte* sig, + word32 sigSz, + enum wc_HashType hashType, int saltLen, int bits); + \ingroup RSA + \brief Returns the encryption size for the provided key structure. \return Success Encryption size for the provided key structure.