wolfSSL/wolfssl
1
0
Fork 1
mirror of https://github.com/wolfSSL/wolfssl.git synced 2025-08-03 20:54:41 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3555 from kojo1/doc-PSS_Sign-Verify

Browse Source 
Doc wc_RsaPSS_Sign/Verify/CheckPadding
This commit is contained in:
Chris Conlon
2020-12-16 15:18:24 -07:00
committed by GitHub
parent 5f30727b32 010c8db54e
commit 7e1a066963
1 changed files with 555 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

555
doc/dox_comments/header_files/rsa.h
View File

@@ -337,6 +337,561 @@ WOLFSSL_API int wc_RsaSSL_Verify(const byte* in, word32 inLen, byte* out,
/*!
\ingroup RSA
\brief Signs the provided array with the private key.
\return RSA_BUFFER_E: -131, RSA buffer error, output too small or
input too large
\param in The byte array to be encrypted.
\param inLen The length of in.
\param out The byte array for the encrypted data to be stored.
\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.
_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;
ret = wc_RsaPSS_Sign((byte*)szMessage, (word32)XSTRLEN(szMessage)+1,
pSignature, sizeof(pSignature),
WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
if (ret > 0 ){
sz = ret;
} else return -1;
ret = wc_RsaPSS_Verify(pSignature, sz, pt, outLen,
WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
if (ret <= 0)return -1;
wc_FreeRsaKey(&key);
wc_FreeRng(&rng);
\endcode
\sa wc_RsaPSS_Verify
*/
WOLFSSL_API int wc_RsaPSS_Sign(const byte* in, word32 inLen, byte* out,
word32 outLen, enum wc_HashType hash, int mgf,
RsaKey* key, WC_RNG* rng);
/*!
\ingroup RSA
\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.
\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 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.
_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;
ret = wc_RsaPSS_Sign((byte*)szMessage, (word32)XSTRLEN(szMessage)+1,
pSignature, sizeof(pSignature),
WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
if (ret > 0 ){
sz = ret;
} else return -1;
ret = wc_RsaPSS_Verify(pSignature, sz, pt, outLen,
WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
if (ret <= 0)return -1;
wc_FreeRsaKey(&key);
wc_FreeRng(&rng);
\endcode
\sa wc_RsaPSS_Sign
\sa wc_RsaPSS_VerifyInline
\sa wc_RsaPSS_CheckPadding
*/
WOLFSSL_API int wc_RsaPSS_Verify(byte* in, word32 inLen, byte* out,
word32 outLen, enum wc_HashType hash, int mgf,
RsaKey* key);
/*!
\ingroup RSA
\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.
\return <0 An error occurred.
\param in Byte array to be decrypted.
\param inLen Length of the buffer input.
\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.
_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;
ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
if (ret > 0 ){
sz = ret;
} else return -1;
ret = wc_RsaPSS_VerifyInline(pSignature, sz, pt,
WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
if (ret <= 0)return -1;
wc_FreeRsaKey(&key);
wc_FreeRng(&rng);
\endcode
\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 Verify the message signed with RSA-PSS.
Salt length is equal to hash length.
\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 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 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(pSignature, sz, pt, outLen,
digest, digestSz, WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &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_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,
enum wc_HashType hash, int mgf,
RsaKey* key);
/*!
\ingroup RSA
\brief Verify the message signed with RSA-PSS.
\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 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.
_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(pSignature, sz, pt,
digest, digestSz, WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &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_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 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.
_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(digest, digestSz, out, verify, hash);
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_ex
*/
WOLFSSL_API int wc_RsaPSS_CheckPadding(const byte* in, word32 inLen, byte* sig,
word32 sigSz,
enum wc_HashType hashType);
/*!
\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.