mirrors/wolfssl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

add XXX_ex APIs, corret spelling, descriptions

Browse Source
This commit is contained in:
Takashi Kojo 2020-12-12 07:05:09 +09:00
parent 47f7e46ffe
commit b2a66a10f4
1 changed files with 251 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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.