mirror of
https://github.com/wolfSSL/wolfssl.git
synced 2026-01-27 08:02:21 +01:00
77d9410aa0
This PR adds Doxygen documentation for native wolfSSL API functions that were previously undocumented. It includes documentation notes for APIs gated on specific preprocessor macros: - WOLF_PRIVATE_KEY_ID: _Id and _Label init helpers (wc_AesInit_Id, wc_AesInit_Label, wc_ecc_init_id, wc_ecc_init_label, wc_InitRsaKey_Id, wc_InitRsaKey_Label) require this for PKCS11 support - WC_NO_CONSTRUCTORS: New/Delete constructor functions (wc_AesNew/Delete, wc_curve25519_new/delete, wc_ed25519_new/delete, wc_NewRsaKey/DeleteRsaKey) are only available when this is not defined. WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is defined. - WOLFSSL_PUBLIC_ASN: ASN functions marked with WOLFSSL_ASN_API include notes indicating they are not public by default - WOLFSSL_DUAL_ALG_CERTS: wc_GeneratePreTBS and wc_MakeSigWithBitStr for Post-Quantum dual algorithm certificate signing The New/Delete functions are documented as being exposed to support allocation of structures using dynamic memory to provide better ABI compatibility.
2206 lines
67 KiB
C
2206 lines
67 KiB
C
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function initializes a provided RsaKey struct. It also takes
|
|
in a heap identifier, for use with user defined memory overrides
|
|
(see XMALLOC, XFREE, XREALLOC).
|
|
|
|
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING
|
|
is enabled.
|
|
|
|
\return 0 Returned upon successfully initializing the RSA structure for
|
|
use with encryption and decryption
|
|
\return BAD_FUNC_ARGS Returned if the RSA key pointer evaluates to NULL
|
|
|
|
\param key pointer to the RsaKey structure to initialize
|
|
\param heap pointer to a heap identifier, for use with memory overrides,
|
|
allowing custom handling of memory allocation. This heap will be the
|
|
default used when allocating memory for use with this RSA object
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey enc;
|
|
int ret;
|
|
ret = wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
|
|
if ( ret != 0 ) {
|
|
// error initializing RSA key
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_FreeRsaKey
|
|
\sa wc_RsaSetRNG
|
|
*/
|
|
int wc_InitRsaKey(RsaKey* key, void* heap);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function initializes a provided RsaKey struct. The id and
|
|
len are used to identify the key on the device while the devId identifies
|
|
the device. It also takes in a heap identifier, for use with user defined
|
|
memory overrides (see XMALLOC, XFREE, XREALLOC).
|
|
|
|
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING
|
|
is enabled.
|
|
|
|
\note This API is only available when WOLF_PRIVATE_KEY_ID is defined,
|
|
which is set for PKCS11 support.
|
|
|
|
\return 0 Returned upon successfully initializing the RSA structure for
|
|
use with encryption and decryption
|
|
\return BAD_FUNC_ARGS Returned if the RSA key pointer evaluates to NULL
|
|
\return BUFFER_E Returned if len is less than 0 or greater than
|
|
RSA_MAX_ID_LEN.
|
|
|
|
\param key pointer to the RsaKey structure to initialize
|
|
\param id identifier of key on device
|
|
\param len length of identifier in bytes
|
|
\param heap pointer to a heap identifier, for use with memory overrides,
|
|
allowing custom handling of memory allocation. This heap will be the
|
|
default used when allocating memory for use with this RSA object
|
|
\param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey enc;
|
|
unsigned char* id = (unsigned char*)"RSA2048";
|
|
int len = 7;
|
|
int devId = 1;
|
|
int ret;
|
|
ret = wc_CryptoDev_RegisterDevice(devId, wc_Pkcs11_CryptoDevCb,
|
|
&token);
|
|
if ( ret != 0) {
|
|
// error associating callback and token with device id
|
|
}
|
|
ret = wc_InitRsaKey_Id(&enc, id, len, NULL, devId); // not using heap hint
|
|
if ( ret != 0 ) {
|
|
// error initializing RSA key
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_InitRsaKey
|
|
\sa wc_FreeRsaKey
|
|
\sa wc_RsaSetRNG
|
|
*/
|
|
int wc_InitRsaKey_Id(RsaKey* key, unsigned char* id, int len,
|
|
void* heap, int devId);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function associates RNG with Key. It is needed when WC_RSA_BLINDING
|
|
is enabled.
|
|
|
|
\return 0 Returned upon success
|
|
\return BAD_FUNC_ARGS Returned if the RSA key, rng pointer evaluates to NULL
|
|
|
|
\param key pointer to the RsaKey structure to be associated
|
|
\param rng pointer to the WC_RNG structure to associate with
|
|
|
|
_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);
|
|
\endcode
|
|
|
|
\sa wc_InitRsaKey
|
|
\sa wc_RsaSetRNG
|
|
*/
|
|
int wc_RsaSetRNG(RsaKey* key, WC_RNG* rng);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function frees a provided RsaKey struct using mp_clear.
|
|
|
|
\return 0 Returned upon successfully freeing the key
|
|
|
|
\param key pointer to the RsaKey structure to free
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey enc;
|
|
wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
|
|
... set key, do encryption
|
|
|
|
wc_FreeRsaKey(&enc);
|
|
\endcode
|
|
|
|
\sa wc_InitRsaKey
|
|
*/
|
|
int wc_FreeRsaKey(RsaKey* key);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief Function that does the RSA operation directly with no padding. The input
|
|
size must match key size. Typically this is
|
|
used when padding is already done on the RSA input.
|
|
|
|
\return size On successfully encryption the size of the encrypted buffer
|
|
is returned
|
|
\return RSA_BUFFER_E RSA buffer error, output too small or input too large
|
|
|
|
\param in buffer to do operation on
|
|
\param inLen length of input buffer
|
|
\param out buffer to hold results
|
|
\param outSz gets set to size of result buffer. Should be passed in as length
|
|
of out buffer. If the pointer "out" is null then outSz gets set to the
|
|
expected buffer size needed and LENGTH_ONLY_E gets returned.
|
|
\param key initialized RSA key to use for encrypt/decrypt
|
|
\param type if using private or public key (RSA_PUBLIC_ENCRYPT,
|
|
RSA_PUBLIC_DECRYPT, RSA_PRIVATE_ENCRYPT, RSA_PRIVATE_DECRYPT)
|
|
\param rng initialized WC_RNG struct
|
|
|
|
_Example_
|
|
\code
|
|
int ret;
|
|
WC_RNG rng;
|
|
RsaKey key;
|
|
byte in[256];
|
|
byte out[256];
|
|
word32 outSz = (word32)sizeof(out);
|
|
…
|
|
|
|
ret = wc_RsaDirect(in, (word32)sizeof(in), out, &outSz, &key,
|
|
RSA_PRIVATE_ENCRYPT, &rng);
|
|
if (ret < 0) {
|
|
//handle error
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_RsaPublicEncrypt
|
|
\sa wc_RsaPrivateDecrypt
|
|
*/
|
|
int wc_RsaDirect(const byte* in, word32 inLen, byte* out, word32* outSz,
|
|
RsaKey* key, int type, WC_RNG* rng);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function encrypts a message from in and stores the result
|
|
in out. It requires an initialized public key and a random number
|
|
generator. As a side effect, this function will return the bytes written
|
|
to out in outLen.
|
|
|
|
\return Success Upon successfully encrypting the input message, returns
|
|
the number of bytes written on success and less than zero for failure.
|
|
\return BAD_FUNC_ARG Returned if any of the input parameters are invalid
|
|
\return RSA_BUFFER_E Returned if the output buffer is too small to store
|
|
the ciphertext
|
|
\return RNG_FAILURE_E Returned if there is an error generating a random
|
|
block using the provided RNG structure
|
|
\return MP_INIT_E May be returned if there is an error in the math
|
|
library used while encrypting the message
|
|
\return MP_READ_E May be returned if there is an error in the math
|
|
library used while encrypting the message
|
|
\return MP_CMP_E May be returned if there is an error in the math
|
|
library used while encrypting the message
|
|
\return MP_INVMOD_E May be returned if there is an error in the math
|
|
library used while encrypting the message
|
|
\return MP_EXPTMOD_E May be returned if there is an error in the math
|
|
library used while encrypting the message
|
|
\return MP_MOD_E May be returned if there is an error in the math
|
|
library used while encrypting the message
|
|
\return MP_MUL_E May be returned if there is an error in the math
|
|
library used while encrypting the message
|
|
\return MP_ADD_E May be returned if there is an error in the math
|
|
library used while encrypting the message
|
|
\return MP_MULMOD_E May be returned if there is an error in the math
|
|
library used while encrypting the message
|
|
\return MP_TO_E May be returned if there is an error in the math
|
|
library used while encrypting the message
|
|
\return MP_MEM May be returned if there is an error in the math
|
|
library used while encrypting the message
|
|
\return MP_ZERO_E May be returned if there is an error in the math
|
|
library used while encrypting the message
|
|
|
|
\param in pointer to a buffer containing the input message to encrypt
|
|
\param inLen the length of the message to encrypt
|
|
\param out pointer to the buffer in which to store the output ciphertext
|
|
\param outLen the length of the output buffer
|
|
\param key pointer to the RsaKey structure containing the public
|
|
key to use for encryption
|
|
\param rng The RNG structure with which to generate random block padding
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey pub;
|
|
int ret = 0;
|
|
byte n[] = { // initialize with received n component of public key };
|
|
byte e[] = { // initialize with received e component of public key };
|
|
byte msg[] = { // initialize with plaintext of message to encrypt };
|
|
byte cipher[256]; // 256 bytes is large enough to store 2048 bit RSA
|
|
ciphertext
|
|
|
|
wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
|
|
wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub);
|
|
// initialize with received public key parameters
|
|
ret = wc_RsaPublicEncrypt(msg, sizeof(msg), out, sizeof(out), &pub, &rng);
|
|
if ( ret != 0 ) {
|
|
// error encrypting message
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_RsaPrivateDecrypt
|
|
*/
|
|
int wc_RsaPublicEncrypt(const byte* in, word32 inLen, byte* out,
|
|
word32 outLen, RsaKey* key, WC_RNG* rng);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This functions is utilized by the wc_RsaPrivateDecrypt function
|
|
for decrypting.
|
|
|
|
\return Success Length of decrypted data.
|
|
\return RSA_PAD_E RsaUnPad error, bad formatting
|
|
|
|
\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 key The key to use for decryption.
|
|
|
|
_Example_
|
|
\code
|
|
none
|
|
\endcode
|
|
|
|
\sa wc_RsaPrivateDecrypt
|
|
*/
|
|
int wc_RsaPrivateDecryptInline(byte* in, word32 inLen, byte** out,
|
|
RsaKey* key);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This functions provides private RSA decryption.
|
|
|
|
\return Success length of decrypted data.
|
|
\return MEMORY_E -125, out of memory error
|
|
\return BAD_FUNC_ARG -173, Bad function argument provided
|
|
|
|
\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 key The key to use for decryption.
|
|
|
|
_Example_
|
|
\code
|
|
ret = wc_RsaPublicEncrypt(in, inLen, out, sizeof(out), &key, &rng);
|
|
if (ret < 0) {
|
|
return -1;
|
|
}
|
|
ret = wc_RsaPrivateDecrypt(out, ret, plain, sizeof(plain), &key);
|
|
if (ret < 0) {
|
|
return -1;
|
|
}
|
|
\endcode
|
|
|
|
\sa RsaUnPad
|
|
\sa wc_RsaFunction
|
|
\sa wc_RsaPrivateDecryptInline
|
|
*/
|
|
int wc_RsaPrivateDecrypt(const byte* in, word32 inLen, byte* out,
|
|
word32 outLen, RsaKey* key);
|
|
|
|
/*!
|
|
\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 key The key to use for encryption.
|
|
\param RNG The RNG struct to use for random number purposes.
|
|
|
|
_Example_
|
|
\code
|
|
ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng);
|
|
if (ret < 0) {
|
|
return -1;
|
|
}
|
|
memset(plain, 0, sizeof(plain));
|
|
ret = wc_RsaSSL_Verify(out, ret, plain, sizeof(plain), &key);
|
|
if (ret < 0) {
|
|
return -1;
|
|
}
|
|
if (ret != inLen) {
|
|
return -1;
|
|
}
|
|
if (XMEMCMP(in, plain, ret) != 0) {
|
|
return -1;
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_RsaPad
|
|
*/
|
|
int wc_RsaSSL_Sign(const byte* in, word32 inLen, byte* out,
|
|
word32 outLen, RsaKey* key, WC_RNG* rng);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief Used to verify that the message was signed by RSA key. The output
|
|
uses the same byte array as the input.
|
|
|
|
\return >0 Length of the digest.
|
|
\return <0 An error occurred.
|
|
|
|
\param in Byte array to be decrypted.
|
|
\param inLen Length of the buffer input.
|
|
\param out Pointer to a pointer for decrypted information.
|
|
\param key RsaKey to use.
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
WC_RNG rng;
|
|
int ret = 0;
|
|
long e = 65537; // standard value to use for exponent
|
|
wc_InitRsaKey(&key, NULL); // not using heap hint. No custom memory
|
|
wc_InitRng(&rng);
|
|
wc_MakeRsaKey(&key, 2048, e, &rng);
|
|
|
|
byte in[] = { // Initialize with some RSA encrypted information }
|
|
byte* out;
|
|
if(wc_RsaSSL_VerifyInline(in, sizeof(in), &out, &key) < 0)
|
|
{
|
|
// handle error
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_RsaSSL_Verify
|
|
\sa wc_RsaSSL_Sign
|
|
*/
|
|
int wc_RsaSSL_VerifyInline(byte* in, word32 inLen, byte** out,
|
|
RsaKey* key);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief Used to verify that the message was signed by key.
|
|
|
|
\return Success Length of digest 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 key The key to use for verification.
|
|
|
|
_Example_
|
|
\code
|
|
ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng);
|
|
if (ret < 0) {
|
|
return -1;
|
|
}
|
|
memset(plain, 0, sizeof(plain));
|
|
ret = wc_RsaSSL_Verify(out, ret, plain, sizeof(plain), &key);
|
|
if (ret < 0) {
|
|
return -1;
|
|
}
|
|
if (ret != inLen) {
|
|
return -1;
|
|
}
|
|
if (XMEMCMP(in, plain, ret) != 0) {
|
|
return -1;
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_RsaSSL_Sign
|
|
*/
|
|
int wc_RsaSSL_Verify(const byte* in, word32 inLen, byte* out,
|
|
word32 outLen, RsaKey* key);
|
|
|
|
/*!
|
|
\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
|
|
\sa wc_RsaSetRNG
|
|
*/
|
|
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.
|
|
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
|
|
|
|
\return Success Length of text on no error.
|
|
\return MEMORY_E memory exception.
|
|
\return MP_EXPTMOD_E - When using fastmath and FP_MAX_BITS not set to at least 2 times the keySize (Example when using 4096-bit key set FP_MAX_BITS to 8192 or greater value)
|
|
|
|
\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
|
|
\sa wc_RsaSetRNG
|
|
*/
|
|
int wc_RsaPSS_Verify(const 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.
|
|
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING
|
|
is enabled.
|
|
|
|
\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
|
|
\sa wc_RsaSetRNG
|
|
*/
|
|
|
|
|
|
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.
|
|
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
|
|
|
|
\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
|
|
\sa wc_RsaSetRNG
|
|
*/
|
|
|
|
int wc_RsaPSS_VerifyCheck(const 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.
|
|
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
|
|
|
|
\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
|
|
\sa wc_RsaSetRNG
|
|
*/
|
|
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.
|
|
|
|
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
|
|
|
|
\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
|
|
\sa wc_RsaSetRNG
|
|
*/
|
|
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.
|
|
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
|
|
|
|
\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
|
|
\sa wc_RsaSetRNG
|
|
*/
|
|
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.
|
|
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
|
|
|
|
\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
|
|
\sa wc_RsaSetRNG
|
|
*/
|
|
int wc_RsaPSS_CheckPadding(const byte* in, word32 inLen, const 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 Can be used to calculate salt size in FIPS case
|
|
|
|
_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
|
|
*/
|
|
int wc_RsaPSS_CheckPadding_ex(const byte* in, word32 inLen, const 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.
|
|
|
|
\param key The key to use for verification.
|
|
|
|
_Example_
|
|
\code
|
|
int sz = wc_RsaEncryptSize(&key);
|
|
\endcode
|
|
|
|
\sa wc_InitRsaKey
|
|
\sa wc_InitRsaKey_ex
|
|
\sa wc_MakeRsaKey
|
|
*/
|
|
int wc_RsaEncryptSize(const RsaKey* key);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function parses a DER-formatted RSA private key, extracts the
|
|
private key and stores it in the given RsaKey structure. It also sets the
|
|
distance parsed in idx.
|
|
|
|
\return 0 Returned upon successfully parsing the private key from the DER
|
|
encoded input
|
|
\return ASN_PARSE_E Returned if there is an error parsing the private key
|
|
from the input buffer. This may happen if the input private key is not
|
|
properly formatted according to ASN.1 standards
|
|
\return ASN_RSA_KEY_E Returned if there is an error reading the private
|
|
key elements of the RSA key input
|
|
|
|
\param input pointer to the buffer containing the DER formatted private
|
|
key to decode
|
|
\param inOutIdx pointer to the index in the buffer at which the key begins
|
|
(usually 0). As a side effect of this function, inOutIdx will store the
|
|
distance parsed through the input buffer
|
|
\param key pointer to the RsaKey structure in which to store the decoded
|
|
private key
|
|
\param inSz size of the input buffer
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey enc;
|
|
word32 idx = 0;
|
|
int ret = 0;
|
|
byte der[] = { // initialize with DER-encoded RSA private key };
|
|
|
|
wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
|
|
ret = wc_RsaPrivateKeyDecode(der, &idx, &enc, sizeof(der));
|
|
if( ret != 0 ) {
|
|
// error parsing private key
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_RsaPublicKeyDecode
|
|
\sa wc_MakeRsaKey
|
|
*/
|
|
int wc_RsaPrivateKeyDecode(const byte* input, word32* inOutIdx,
|
|
RsaKey* key, word32 inSz);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function parses a DER-formatted RSA public key, extracts the
|
|
public key and stores it in the given RsaKey structure. It also sets the
|
|
distance parsed in idx.
|
|
|
|
\return 0 Returned upon successfully parsing the public key from the DER
|
|
encoded input
|
|
\return ASN_PARSE_E Returned if there is an error parsing the public key
|
|
from the input buffer. This may happen if the input public key is not
|
|
properly formatted according to ASN.1 standards
|
|
\return ASN_OBJECT_ID_E Returned if the ASN.1 Object ID does not match
|
|
that of a RSA public key
|
|
\return ASN_EXPECT_0_E Returned if the input key is not correctly
|
|
formatted according to ASN.1 standards
|
|
\return ASN_BITSTR_E Returned if the input key is not correctly formatted
|
|
according to ASN.1 standards
|
|
\return ASN_RSA_KEY_E Returned if there is an error reading the public key
|
|
elements of the RSA key input
|
|
|
|
\param input pointer to the buffer containing the input DER-encoded RSA
|
|
public key to decode
|
|
\param inOutIdx pointer to the index in the buffer at which the key
|
|
begins (usually 0). As a side effect of this function, inOutIdx will
|
|
store the distance parsed through the input buffer
|
|
\param key pointer to the RsaKey structure in which to store the decoded
|
|
public key
|
|
\param inSz size of the input buffer
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey pub;
|
|
word32 idx = 0;
|
|
int ret = 0;
|
|
byte der[] = { // initialize with DER-encoded RSA public key };
|
|
|
|
wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
|
|
ret = wc_RsaPublicKeyDecode(der, &idx, &pub, sizeof(der));
|
|
if( ret != 0 ) {
|
|
// error parsing public key
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_RsaPublicKeyDecodeRaw
|
|
*/
|
|
int wc_RsaPublicKeyDecode(const byte* input, word32* inOutIdx,
|
|
RsaKey* key, word32 inSz);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function decodes the raw elements of an RSA public key, taking
|
|
in the public modulus (n) and exponent (e). It stores these raw elements
|
|
in the provided RsaKey structure, allowing one to use them in the
|
|
encryption/decryption process.
|
|
|
|
\return 0 Returned upon successfully decoding the raw elements of the
|
|
public key into the RsaKey structure
|
|
\return BAD_FUNC_ARG Returned if any of the input arguments evaluates to
|
|
NULL
|
|
\return MP_INIT_E Returned if there is an error initializing an integer
|
|
for use with the multiple precision integer (mp_int) library
|
|
\return ASN_GETINT_E Returned if there is an error reading one of the
|
|
provided RSA key elements, n or e
|
|
|
|
\param n pointer to a buffer containing the raw modulus parameter of the
|
|
public RSA key
|
|
\param nSz size of the buffer containing n
|
|
\param e pointer to a buffer containing the raw exponent parameter of
|
|
the public RSA key
|
|
\param eSz size of the buffer containing e
|
|
\param key pointer to the RsaKey struct to initialize with the provided
|
|
public key elements
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey pub;
|
|
int ret = 0;
|
|
byte n[] = { // initialize with received n component of public key };
|
|
byte e[] = { // initialize with received e component of public key };
|
|
|
|
wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
|
|
ret = wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub);
|
|
if( ret != 0 ) {
|
|
// error parsing public key elements
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_RsaPublicKeyDecode
|
|
*/
|
|
int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz,
|
|
const byte* e, word32 eSz, RsaKey* key);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function converts an RsaKey key to DER format. The result is
|
|
written to output and it returns the number of bytes written.
|
|
|
|
\return >0 Success, number of bytes written.
|
|
\return BAD_FUNC_ARG Returned if key or output is null, or if key->type
|
|
is not RSA_PRIVATE, or if inLen isn't large enough for output buffer.
|
|
\return MEMORY_E Returned if there is an error allocating memory.
|
|
|
|
\param key Initialized RsaKey structure.
|
|
\param output Pointer to output buffer.
|
|
\param inLen Size of output buffer.
|
|
|
|
_Example_
|
|
\code
|
|
byte* der;
|
|
// Allocate memory for der
|
|
int derSz = // Amount of memory allocated for der;
|
|
RsaKey key;
|
|
WC_RNG rng;
|
|
long e = 65537; // standard value to use for exponent
|
|
ret = wc_MakeRsaKey(&key, 2048, e, &rng); // generate 2048 bit long
|
|
private key
|
|
wc_InitRsaKey(&key, NULL);
|
|
wc_InitRng(&rng);
|
|
if(wc_RsaKeyToDer(&key, der, derSz) != 0)
|
|
{
|
|
// Handle the error thrown
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_RsaKeyToPublicDer
|
|
\sa wc_InitRsaKey
|
|
\sa wc_MakeRsaKey
|
|
\sa wc_InitRng
|
|
*/
|
|
int wc_RsaKeyToDer(RsaKey* key, byte* output, word32 inLen);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function performs RSA encrypt while allowing the choice of
|
|
which padding to use.
|
|
|
|
\return size On successfully encryption the size of the encrypted buffer
|
|
is returned
|
|
\return RSA_BUFFER_E RSA buffer error, output too small or input too large
|
|
|
|
\param in pointer to the buffer for encryption
|
|
\param inLen length of the buffer to encrypt
|
|
\param out encrypted msg created
|
|
\param outLen length of buffer available to hold encrypted msg
|
|
\param key initialized RSA key struct
|
|
\param rng initialized WC_RNG struct
|
|
\param type type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
|
|
\param hash type of hash to use (choices can be found in hash.h)
|
|
\param mgf type of mask generation function to use
|
|
\param label an optional label to associate with encrypted message
|
|
\param labelSz size of the optional label used
|
|
|
|
_Example_
|
|
\code
|
|
WC_RNG rng;
|
|
RsaKey key;
|
|
byte in[] = “I use Turing Machines to ask questions”
|
|
byte out[256];
|
|
int ret;
|
|
…
|
|
|
|
ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, &rng,
|
|
WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
|
|
if (ret < 0) {
|
|
//handle error
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_RsaPublicEncrypt
|
|
\sa wc_RsaPrivateDecrypt_ex
|
|
*/
|
|
int wc_RsaPublicEncrypt_ex(const byte* in, word32 inLen, byte* out,
|
|
word32 outLen, RsaKey* key, WC_RNG* rng, int type,
|
|
enum wc_HashType hash, int mgf, byte* label, word32 labelSz);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function uses RSA to decrypt a message and gives the
|
|
option of what padding type.
|
|
|
|
\return size On successful decryption, the size of the decrypted message
|
|
is returned.
|
|
\return MEMORY_E Returned if not enough memory on system to malloc a
|
|
needed array.
|
|
\return BAD_FUNC_ARG Returned if a bad argument was passed into the
|
|
function.
|
|
|
|
\param in pointer to the buffer for decryption
|
|
\param inLen length of the buffer to decrypt
|
|
\param out decrypted msg created
|
|
\param outLen length of buffer available to hold decrypted msg
|
|
\param key initialized RSA key struct
|
|
\param type type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
|
|
\param hash type of hash to use (choices can be found in hash.h)
|
|
\param mgf type of mask generation function to use
|
|
\param label an optional label to associate with encrypted message
|
|
\param labelSz size of the optional label used
|
|
|
|
_Example_
|
|
\code
|
|
WC_RNG rng;
|
|
RsaKey key;
|
|
byte in[] = “I use Turing Machines to ask questions”
|
|
byte out[256];
|
|
byte plain[256];
|
|
int ret;
|
|
…
|
|
ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key,
|
|
&rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
|
|
if (ret < 0) {
|
|
//handle error
|
|
}
|
|
…
|
|
ret = wc_RsaPrivateDecrypt_ex(out, ret, plain, sizeof(plain), &key,
|
|
WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
|
|
|
|
if (ret < 0) {
|
|
//handle error
|
|
}
|
|
\endcode
|
|
|
|
\sa none
|
|
*/
|
|
int wc_RsaPrivateDecrypt_ex(const byte* in, word32 inLen,
|
|
byte* out, word32 outLen, RsaKey* key, int type,
|
|
enum wc_HashType hash, int mgf, byte* label, word32 labelSz);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function uses RSA to decrypt a message inline and gives the
|
|
option of what padding type. The in buffer will contain the decrypted
|
|
message after being called and the out byte pointer will point to the
|
|
location in the “in” buffer where the plain text is.
|
|
|
|
\return size On successful decryption, the size of the decrypted message
|
|
is returned.
|
|
\return MEMORY_E: Returned if not enough memory on system to malloc a
|
|
needed array.
|
|
\return RSA_PAD_E: Returned if an error in the padding was encountered.
|
|
\return BAD_PADDING_E: Returned if an error happened during parsing past
|
|
padding.
|
|
\return BAD_FUNC_ARG: Returned if a bad argument was passed into the
|
|
function.
|
|
|
|
\param in pointer to the buffer for decryption
|
|
\param inLen length of the buffer to decrypt
|
|
\param out pointer to location of decrypted message in “in” buffer
|
|
\param key initialized RSA key struct
|
|
\param type type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
|
|
\param hash type of hash to use (choices can be found in hash.h)
|
|
\param mgf type of mask generation function to use
|
|
\param label an optional label to associate with encrypted message
|
|
\param labelSz size of the optional label used
|
|
|
|
_Example_
|
|
\code
|
|
WC_RNG rng;
|
|
RsaKey key;
|
|
byte in[] = “I use Turing Machines to ask questions”
|
|
byte out[256];
|
|
byte* plain;
|
|
int ret;
|
|
…
|
|
ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key,
|
|
&rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
|
|
|
|
if (ret < 0) {
|
|
//handle error
|
|
}
|
|
…
|
|
ret = wc_RsaPrivateDecryptInline_ex(out, ret, &plain, &key,
|
|
WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
|
|
|
|
if (ret < 0) {
|
|
//handle error
|
|
}
|
|
\endcode
|
|
|
|
\sa none
|
|
*/
|
|
int wc_RsaPrivateDecryptInline_ex(byte* in, word32 inLen,
|
|
byte** out, RsaKey* key, int type, enum wc_HashType hash,
|
|
int mgf, byte* label, word32 labelSz);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief Flattens the RsaKey structure into individual elements (e, n)
|
|
used for the RSA algorithm.
|
|
|
|
\return 0 Returned if the function executed normally, without error.
|
|
\return BAD_FUNC_ARG: Returned if any of the parameters are passed in
|
|
with a null value.
|
|
\return RSA_BUFFER_E: Returned if the e or n buffers passed in are not
|
|
the correct size.
|
|
\return MP_MEM: Returned if an internal function has memory errors.
|
|
\return MP_VAL: Returned if an internal function argument is not valid.
|
|
|
|
\param key The key to use for verification.
|
|
\param e a buffer for the value of e. e is a large positive integer in
|
|
the RSA modular arithmetic operation.
|
|
\param eSz the size of the e buffer.
|
|
\param n a buffer for the value of n. n is a large positive integer in
|
|
the RSA modular arithmetic operation.
|
|
\param nSz the size of the n buffer.
|
|
|
|
_Example_
|
|
\code
|
|
Rsa key; // A valid RSA key.
|
|
byte e[ buffer sz E.g. 256 ];
|
|
byte n[256];
|
|
int ret;
|
|
word32 eSz = sizeof(e);
|
|
word32 nSz = sizeof(n);
|
|
...
|
|
ret = wc_RsaFlattenPublicKey(&key, e, &eSz, n, &nSz);
|
|
if (ret != 0) {
|
|
// Failure case.
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_InitRsaKey
|
|
\sa wc_InitRsaKey_ex
|
|
\sa wc_MakeRsaKey
|
|
*/
|
|
int wc_RsaFlattenPublicKey(const RsaKey* key, byte* e, word32* eSz, byte* n,
|
|
word32* nSz);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief Convert Rsa Public key to DER format. Writes to output, and
|
|
returns count of bytes written.
|
|
|
|
\return >0 Success, number of bytes written.
|
|
\return BAD_FUNC_ARG Returned if key or output is null.
|
|
\return MEMORY_E Returned when an error allocating memory occurs.
|
|
\return <0 Error
|
|
|
|
\param key The RSA key structure to convert.
|
|
\param output Output buffer to hold DER. (if NULL will return length only)
|
|
\param inLen Length of buffer.
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
|
|
wc_InitRsaKey(&key, NULL);
|
|
// Use key
|
|
|
|
const int BUFFER_SIZE = 1024; // Some adequate size for the buffer
|
|
byte output[BUFFER_SIZE];
|
|
if (wc_RsaKeyToPublicDer(&key, output, sizeof(output)) != 0) {
|
|
// Handle Error
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_RsaPublicKeyDerSize
|
|
\sa wc_RsaKeyToPublicDer_ex
|
|
\sa wc_InitRsaKey
|
|
*/
|
|
int wc_RsaKeyToPublicDer(RsaKey* key, byte* output, word32 inLen);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief Convert RSA Public key to DER format. Writes to output, and
|
|
returns count of bytes written. If with_header is 0 then only the
|
|
( seq + n + e) is returned in ASN.1 DER format and will exclude the header.
|
|
|
|
\return >0 Success, number of bytes written.
|
|
\return BAD_FUNC_ARG Returned if key or output is null.
|
|
\return MEMORY_E Returned when an error allocating memory occurs.
|
|
\return <0 Error
|
|
|
|
\param key The RSA key structure to convert.
|
|
\param output Output buffer to hold DER. (if NULL will return length only)
|
|
\param inLen Length of buffer.
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
|
|
wc_InitRsaKey(&key, NULL);
|
|
// Use key
|
|
|
|
const int BUFFER_SIZE = 1024; // Some adequate size for the buffer
|
|
byte output[BUFFER_SIZE];
|
|
if (wc_RsaKeyToPublicDer_ex(&key, output, sizeof(output), 0) != 0) {
|
|
// Handle Error
|
|
}
|
|
\endcode
|
|
|
|
\sa wc_RsaPublicKeyDerSize
|
|
\sa wc_RsaKeyToPublicDer
|
|
\sa wc_InitRsaKey
|
|
*/
|
|
int wc_RsaKeyToPublicDer_ex(RsaKey* key, byte* output, word32 inLen,
|
|
int with_header);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function generates a RSA private key of length size (in bits)
|
|
and given exponent (e). It then stores this key in the provided RsaKey
|
|
structure, so that it may be used for encryption/decryption. A secure
|
|
number to use for e is 65537. size is required to be greater than or equal
|
|
to RSA_MIN_SIZE and less than or equal to RSA_MAX_SIZE. For this function
|
|
to be available, the option WOLFSSL_KEY_GEN must be enabled at compile
|
|
time. This can be accomplished with --enable-keygen if using ./configure.
|
|
|
|
\return 0 Returned upon successfully generating a RSA private key
|
|
\return BAD_FUNC_ARG Returned if any of the input arguments are NULL,
|
|
the size parameter falls outside of the necessary bounds, or e is
|
|
incorrectly chosen
|
|
\return RNG_FAILURE_E Returned if there is an error generating a random
|
|
block using the provided RNG structure
|
|
\return MP_INIT_E
|
|
\return MP_READ_E May be May be returned if there is an error in the math
|
|
library used while generating the RSA key returned if there is an error
|
|
in the math library used while generating the RSA key
|
|
\return MP_CMP_E May be returned if there is an error in the math library
|
|
used while generating the RSA key
|
|
\return MP_INVMOD_E May be returned if there is an error in the math
|
|
library used while generating the RSA key
|
|
\return MP_EXPTMOD_E May be returned if there is an error in the math
|
|
library used while generating the RSA key
|
|
\return MP_MOD_E May be returned if there is an error in the math
|
|
library used while generating the RSA key
|
|
\return MP_MUL_E May be returned if there is an error in the math
|
|
library used while generating the RSA key
|
|
\return MP_ADD_E May be returned if there is an error in the math
|
|
library used while generating the RSA key
|
|
\return MP_MULMOD_E May be returned if there is an error in the math
|
|
library used while generating the RSA key
|
|
\return MP_TO_E May be returned if there is an error in the math
|
|
library used while generating the RSA key
|
|
\return MP_MEM May be returned if there is an error in the math
|
|
library used while generating the RSA key
|
|
\return MP_ZERO_E May be returned if there is an error in the math
|
|
library used while generating the RSA key
|
|
|
|
\param key pointer to the RsaKey structure in which to store the
|
|
generated private key
|
|
\param size desired key length, in bits. Required to be greater than
|
|
RSA_MIN_SIZE and less than RSA_MAX_SIZE
|
|
\param e exponent parameter to use for generating the key. A secure
|
|
choice is 65537
|
|
\param rng pointer to an RNG structure to use for random number generation
|
|
while making the key
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey priv;
|
|
WC_RNG rng;
|
|
int ret = 0;
|
|
long e = 65537; // standard value to use for exponent
|
|
|
|
wc_InitRsaKey(&priv, NULL); // not using heap hint. No custom memory
|
|
wc_InitRng(&rng);
|
|
// generate 2048 bit long private key
|
|
ret = wc_MakeRsaKey(&priv, 2048, e, &rng);
|
|
if( ret != 0 ) {
|
|
// error generating private key
|
|
}
|
|
\endcode
|
|
|
|
\sa none
|
|
*/
|
|
int wc_MakeRsaKey(RsaKey* key, int size, long e, WC_RNG* rng);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function sets the non-blocking RSA context. When a RsaNb context
|
|
is set it enables fast math based non-blocking exptmod, which splits the RSA
|
|
function into many smaller operations.
|
|
Enabled when WC_RSA_NONBLOCK is defined.
|
|
|
|
\return 0 Success
|
|
\return BAD_FUNC_ARG Returned if key or nb is null.
|
|
|
|
\param key The RSA key structure
|
|
\param nb The RSA non-blocking structure for this RSA key to use.
|
|
|
|
_Example_
|
|
\code
|
|
int ret, count = 0;
|
|
RsaKey key;
|
|
RsaNb nb;
|
|
|
|
wc_InitRsaKey(&key, NULL);
|
|
|
|
// Enable non-blocking RSA mode - provide context
|
|
ret = wc_RsaSetNonBlock(key, &nb);
|
|
if (ret != 0)
|
|
return ret;
|
|
|
|
do {
|
|
ret = wc_RsaSSL_Sign(in, inLen, out, outSz, key, rng);
|
|
count++; // track number of would blocks
|
|
if (ret == FP_WOULDBLOCK) {
|
|
// do "other" work here
|
|
}
|
|
} while (ret == FP_WOULDBLOCK);
|
|
if (ret < 0) {
|
|
return ret;
|
|
}
|
|
|
|
printf("RSA non-block sign: size %d, %d times\n", ret, count);
|
|
\endcode
|
|
|
|
\sa wc_RsaSetNonBlockTime
|
|
*/
|
|
int wc_RsaSetNonBlock(RsaKey* key, RsaNb* nb);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
|
|
\brief This function configures the maximum amount of blocking time in
|
|
microseconds. It uses a pre-computed table (see tfm.c exptModNbInst) along
|
|
with the CPU speed in megahertz to determine if the next operation can be
|
|
completed within the maximum blocking time provided.
|
|
Enabled when WC_RSA_NONBLOCK_TIME is defined.
|
|
|
|
\return 0 Success
|
|
\return BAD_FUNC_ARG Returned if key is null or wc_RsaSetNonBlock was not
|
|
previously called and key->nb is null.
|
|
|
|
\param key The RSA key structure.
|
|
\param maxBlockUs Maximum time to block microseconds.
|
|
\param cpuMHz CPU speed in megahertz.
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
RsaNb nb;
|
|
|
|
wc_InitRsaKey(&key, NULL);
|
|
wc_RsaSetNonBlock(key, &nb);
|
|
wc_RsaSetNonBlockTime(&key, 4000, 160); // Block Max = 4 ms, CPU = 160MHz
|
|
|
|
\endcode
|
|
|
|
\sa wc_RsaSetNonBlock
|
|
*/
|
|
int wc_RsaSetNonBlockTime(RsaKey* key, word32 maxBlockUs,
|
|
word32 cpuMHz);
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Initializes RSA key with heap and device ID.
|
|
|
|
\return 0 on success
|
|
\return negative on error
|
|
|
|
\param key RSA key structure
|
|
\param heap Heap hint
|
|
\param devId Device ID
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
int ret = wc_InitRsaKey_ex(&key, NULL, INVALID_DEVID);
|
|
\endcode
|
|
|
|
\sa wc_InitRsaKey
|
|
*/
|
|
int wc_InitRsaKey_ex(RsaKey* key, void* heap, int devId);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Allocates and initializes new RSA key. These New/Delete functions
|
|
are exposed to support allocation of the structure using dynamic memory
|
|
to provide better ABI compatibility.
|
|
|
|
\note This API is only available when WC_NO_CONSTRUCTORS is not defined.
|
|
WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is
|
|
defined.
|
|
|
|
\return RsaKey pointer on success
|
|
\return NULL on failure
|
|
|
|
\param heap Heap hint
|
|
\param devId Device ID
|
|
\param result_code Result code pointer
|
|
|
|
_Example_
|
|
\code
|
|
int result;
|
|
RsaKey* key = wc_NewRsaKey(NULL, INVALID_DEVID, &result);
|
|
\endcode
|
|
|
|
\sa wc_DeleteRsaKey
|
|
*/
|
|
RsaKey* wc_NewRsaKey(void* heap, int devId, int *result_code);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Deletes and frees RSA key. These New/Delete functions are exposed
|
|
to support allocation of the structure using dynamic memory to provide
|
|
better ABI compatibility.
|
|
|
|
\note This API is only available when WC_NO_CONSTRUCTORS is not defined.
|
|
WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is
|
|
defined.
|
|
|
|
\return 0 on success
|
|
\return negative on error
|
|
|
|
\param key RSA key to delete
|
|
\param key_p Pointer to key pointer
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey* key;
|
|
int ret = wc_DeleteRsaKey(key, &key);
|
|
\endcode
|
|
|
|
\sa wc_NewRsaKey
|
|
*/
|
|
int wc_DeleteRsaKey(RsaKey* key, RsaKey** key_p);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Initializes RSA key with label.
|
|
|
|
\note This API is only available when WOLF_PRIVATE_KEY_ID is defined,
|
|
which is set for PKCS11 support.
|
|
|
|
\return 0 on success
|
|
\return negative on error
|
|
|
|
\param key RSA key structure
|
|
\param label Label string
|
|
\param heap Heap hint
|
|
\param devId Device ID
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
int ret = wc_InitRsaKey_Label(&key, "mykey", NULL,
|
|
INVALID_DEVID);
|
|
\endcode
|
|
|
|
\sa wc_InitRsaKey_ex
|
|
*/
|
|
int wc_InitRsaKey_Label(RsaKey* key, const char* label, void* heap,
|
|
int devId);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Checks RSA key validity.
|
|
|
|
\return 0 on success
|
|
\return negative on error
|
|
|
|
\param key RSA key to check
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
int ret = wc_CheckRsaKey(&key);
|
|
\endcode
|
|
|
|
\sa wc_MakeRsaKey
|
|
*/
|
|
int wc_CheckRsaKey(RsaKey* key);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Uses key ID for hardware RSA.
|
|
|
|
\return 0 on success
|
|
\return negative on error
|
|
|
|
\param key RSA key
|
|
\param keyId Key identifier
|
|
\param flags Flags
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
int ret = wc_RsaUseKeyId(&key, 1, 0);
|
|
\endcode
|
|
|
|
\sa wc_RsaGetKeyId
|
|
*/
|
|
int wc_RsaUseKeyId(RsaKey* key, word32 keyId, word32 flags);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Gets key ID from hardware RSA key.
|
|
|
|
\return 0 on success
|
|
\return negative on error
|
|
|
|
\param key RSA key
|
|
\param keyId Key identifier pointer
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
word32 keyId;
|
|
int ret = wc_RsaGetKeyId(&key, &keyId);
|
|
\endcode
|
|
|
|
\sa wc_RsaUseKeyId
|
|
*/
|
|
int wc_RsaGetKeyId(RsaKey* key, word32* keyId);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Performs RSA operation.
|
|
|
|
\return 0 on success
|
|
\return negative on error
|
|
|
|
\param in Input buffer
|
|
\param inLen Input length
|
|
\param out Output buffer
|
|
\param outLen Output length pointer
|
|
\param type Operation type
|
|
\param key RSA key
|
|
\param rng Random number generator
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
WC_RNG rng;
|
|
byte in[256], out[256];
|
|
word32 outLen = sizeof(out);
|
|
int ret = wc_RsaFunction(in, 256, out, &outLen,
|
|
RSA_PUBLIC_ENCRYPT, &key, &rng);
|
|
\endcode
|
|
|
|
\sa wc_RsaPublicEncrypt
|
|
*/
|
|
int wc_RsaFunction(const byte* in, word32 inLen, byte* out,
|
|
word32* outLen, int type, RsaKey* key, WC_RNG* rng);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Signs with RSA-PSS extended options.
|
|
|
|
\return Size of signature on success
|
|
\return negative on error
|
|
|
|
\param in Input buffer
|
|
\param inLen Input length
|
|
\param out Output buffer
|
|
\param outLen Output buffer size
|
|
\param hash Hash type
|
|
\param mgf MGF type
|
|
\param saltLen Salt length
|
|
\param key RSA key
|
|
\param rng Random number generator
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
WC_RNG rng;
|
|
byte in[32], sig[256];
|
|
int ret = wc_RsaPSS_Sign_ex(in, 32, sig, sizeof(sig),
|
|
WC_HASH_TYPE_SHA256,
|
|
WC_MGF1SHA256, 32, &key, &rng);
|
|
\endcode
|
|
|
|
\sa wc_RsaPSS_Sign
|
|
*/
|
|
int wc_RsaPSS_Sign_ex(const byte* in, word32 inLen, byte* out,
|
|
word32 outLen, enum wc_HashType hash, int mgf, int saltLen,
|
|
RsaKey* key, WC_RNG* rng);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Verifies RSA signature with padding type.
|
|
|
|
\return Size of decrypted data on success
|
|
\return negative on error
|
|
|
|
\param in Input signature
|
|
\param inLen Signature length
|
|
\param out Output buffer
|
|
\param outLen Output buffer size
|
|
\param key RSA key
|
|
\param pad_type Padding type
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
byte sig[256], out[256];
|
|
int ret = wc_RsaSSL_Verify_ex(sig, 256, out, sizeof(out),
|
|
&key, RSA_PKCS1_PADDING);
|
|
\endcode
|
|
|
|
\sa wc_RsaSSL_Verify
|
|
*/
|
|
int wc_RsaSSL_Verify_ex(const byte* in, word32 inLen, byte* out,
|
|
word32 outLen, RsaKey* key, int pad_type);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Verifies RSA signature with hash type.
|
|
|
|
\return Size of decrypted data on success
|
|
\return negative on error
|
|
|
|
\param in Input signature
|
|
\param inLen Signature length
|
|
\param out Output buffer
|
|
\param outLen Output buffer size
|
|
\param key RSA key
|
|
\param pad_type Padding type
|
|
\param hash Hash type
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
byte sig[256], out[256];
|
|
int ret = wc_RsaSSL_Verify_ex2(sig, 256, out, sizeof(out),
|
|
&key, RSA_PKCS1_PADDING,
|
|
WC_HASH_TYPE_SHA256);
|
|
\endcode
|
|
|
|
\sa wc_RsaSSL_Verify_ex
|
|
*/
|
|
int wc_RsaSSL_Verify_ex2(const byte* in, word32 inLen, byte* out,
|
|
word32 outLen, RsaKey* key, int pad_type,
|
|
enum wc_HashType hash);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Verifies RSA-PSS inline with extended options.
|
|
|
|
\return Size of verified data on success
|
|
\return negative on error
|
|
|
|
\param in Input/output buffer
|
|
\param inLen Input length
|
|
\param out Output pointer
|
|
\param hash Hash type
|
|
\param mgf MGF type
|
|
\param saltLen Salt length
|
|
\param key RSA key
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
byte sig[256];
|
|
byte* out;
|
|
int ret = wc_RsaPSS_VerifyInline_ex(sig, 256, &out,
|
|
WC_HASH_TYPE_SHA256,
|
|
WC_MGF1SHA256, 32, &key);
|
|
\endcode
|
|
|
|
\sa wc_RsaPSS_VerifyInline
|
|
*/
|
|
int wc_RsaPSS_VerifyInline_ex(byte* in, word32 inLen, byte** out,
|
|
enum wc_HashType hash, int mgf, int saltLen, RsaKey* key);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Verifies RSA-PSS with extended options.
|
|
|
|
\return Size of verified data on success
|
|
\return negative on error
|
|
|
|
\param in Input signature
|
|
\param inLen Signature length
|
|
\param out Output buffer
|
|
\param outLen Output buffer size
|
|
\param hash Hash type
|
|
\param mgf MGF type
|
|
\param saltLen Salt length
|
|
\param key RSA key
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
byte sig[256], out[256];
|
|
int ret = wc_RsaPSS_Verify_ex(sig, 256, out, sizeof(out),
|
|
WC_HASH_TYPE_SHA256,
|
|
WC_MGF1SHA256, 32, &key);
|
|
\endcode
|
|
|
|
\sa wc_RsaPSS_Verify
|
|
*/
|
|
int wc_RsaPSS_Verify_ex(const byte* in, word32 inLen, byte* out,
|
|
word32 outLen, enum wc_HashType hash, int mgf, int saltLen,
|
|
RsaKey* key);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Checks RSA-PSS padding with extended options.
|
|
|
|
\return 0 on success
|
|
\return negative on error
|
|
|
|
\param in Padded data
|
|
\param inLen Padded data length
|
|
\param sig Signature
|
|
\param sigSz Signature size
|
|
\param hashType Hash type
|
|
\param saltLen Salt length
|
|
\param bits Key size in bits
|
|
\param heap Heap hint
|
|
|
|
_Example_
|
|
\code
|
|
byte padded[256], sig[256];
|
|
int ret = wc_RsaPSS_CheckPadding_ex2(padded, 256, sig, 256,
|
|
WC_HASH_TYPE_SHA256, 32,
|
|
2048, NULL);
|
|
\endcode
|
|
|
|
\sa wc_RsaPSS_CheckPadding_ex
|
|
*/
|
|
int wc_RsaPSS_CheckPadding_ex2(const byte* in, word32 inLen,
|
|
const byte* sig, word32 sigSz, enum wc_HashType hashType,
|
|
int saltLen, int bits, void* heap);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Exports RSA key components.
|
|
|
|
\return 0 on success
|
|
\return negative on error
|
|
|
|
\param key RSA key
|
|
\param e Public exponent buffer
|
|
\param eSz Public exponent size pointer
|
|
\param n Modulus buffer
|
|
\param nSz Modulus size pointer
|
|
\param d Private exponent buffer
|
|
\param dSz Private exponent size pointer
|
|
\param p Prime p buffer
|
|
\param pSz Prime p size pointer
|
|
\param q Prime q buffer
|
|
\param qSz Prime q size pointer
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
byte e[3], n[256], d[256], p[128], q[128];
|
|
word32 eSz = 3, nSz = 256, dSz = 256, pSz = 128, qSz = 128;
|
|
int ret = wc_RsaExportKey(&key, e, &eSz, n, &nSz, d, &dSz,
|
|
p, &pSz, q, &qSz);
|
|
\endcode
|
|
|
|
\sa wc_RsaFlattenPublicKey
|
|
*/
|
|
int wc_RsaExportKey(const RsaKey* key, byte* e, word32* eSz,
|
|
byte* n, word32* nSz, byte* d, word32* dSz, byte* p,
|
|
word32* pSz, byte* q, word32* qSz);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Checks probable prime with extended options.
|
|
|
|
\return 0 on success
|
|
\return negative on error
|
|
|
|
\param p Prime p buffer
|
|
\param pSz Prime p size
|
|
\param q Prime q buffer
|
|
\param qSz Prime q size
|
|
\param e Public exponent buffer
|
|
\param eSz Public exponent size
|
|
\param nlen Modulus length
|
|
\param isPrime Prime result pointer
|
|
\param rng Random number generator
|
|
|
|
_Example_
|
|
\code
|
|
byte p[128], q[128], e[3];
|
|
int isPrime;
|
|
WC_RNG rng;
|
|
int ret = wc_CheckProbablePrime_ex(p, 128, q, 128, e, 3,
|
|
2048, &isPrime, &rng);
|
|
\endcode
|
|
|
|
\sa wc_CheckProbablePrime
|
|
*/
|
|
int wc_CheckProbablePrime_ex(const byte* p, word32 pSz,
|
|
const byte* q, word32 qSz, const byte* e, word32 eSz,
|
|
int nlen, int* isPrime, WC_RNG* rng);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Checks probable prime.
|
|
|
|
\return 0 on success
|
|
\return negative on error
|
|
|
|
\param p Prime p buffer
|
|
\param pSz Prime p size
|
|
\param q Prime q buffer
|
|
\param qSz Prime q size
|
|
\param e Public exponent buffer
|
|
\param eSz Public exponent size
|
|
\param nlen Modulus length
|
|
\param isPrime Prime result pointer
|
|
|
|
_Example_
|
|
\code
|
|
byte p[128], q[128], e[3];
|
|
int isPrime;
|
|
int ret = wc_CheckProbablePrime(p, 128, q, 128, e, 3, 2048,
|
|
&isPrime);
|
|
\endcode
|
|
|
|
\sa wc_CheckProbablePrime_ex
|
|
*/
|
|
int wc_CheckProbablePrime(const byte* p, word32 pSz,
|
|
const byte* q, word32 qSz, const byte* e, word32 eSz,
|
|
int nlen, int* isPrime);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Pads data with extended options.
|
|
|
|
\return 0 on success
|
|
\return negative on error
|
|
|
|
\param input Input data
|
|
\param inputLen Input length
|
|
\param pkcsBlock Output padded block
|
|
\param pkcsBlockLen Padded block size
|
|
\param padValue Pad value
|
|
\param rng Random number generator
|
|
\param padType Padding type
|
|
\param hType Hash type
|
|
\param mgf MGF type
|
|
\param optLabel Optional label
|
|
\param labelLen Label length
|
|
\param saltLen Salt length
|
|
\param bits Key size in bits
|
|
\param heap Heap hint
|
|
|
|
_Example_
|
|
\code
|
|
byte in[32], padded[256];
|
|
WC_RNG rng;
|
|
int ret = wc_RsaPad_ex(in, 32, padded, 256, 0x00, &rng,
|
|
RSA_BLOCK_TYPE_1,
|
|
WC_HASH_TYPE_SHA256, WC_MGF1SHA256,
|
|
NULL, 0, 32, 2048, NULL);
|
|
\endcode
|
|
|
|
\sa wc_RsaUnPad_ex
|
|
*/
|
|
int wc_RsaPad_ex(const byte* input, word32 inputLen,
|
|
byte* pkcsBlock, word32 pkcsBlockLen, byte padValue,
|
|
WC_RNG* rng, int padType, enum wc_HashType hType, int mgf,
|
|
byte* optLabel, word32 labelLen, int saltLen, int bits,
|
|
void* heap);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Unpads data with extended options.
|
|
|
|
\return Size of unpadded data on success
|
|
\return negative on error
|
|
|
|
\param pkcsBlock Padded block
|
|
\param pkcsBlockLen Padded block length
|
|
\param out Output pointer
|
|
\param padValue Pad value
|
|
\param padType Padding type
|
|
\param hType Hash type
|
|
\param mgf MGF type
|
|
\param optLabel Optional label
|
|
\param labelLen Label length
|
|
\param saltLen Salt length
|
|
\param bits Key size in bits
|
|
\param heap Heap hint
|
|
|
|
_Example_
|
|
\code
|
|
byte padded[256];
|
|
byte* out;
|
|
int ret = wc_RsaUnPad_ex(padded, 256, &out, 0x00,
|
|
RSA_BLOCK_TYPE_1,
|
|
WC_HASH_TYPE_SHA256, WC_MGF1SHA256,
|
|
NULL, 0, 32, 2048, NULL);
|
|
\endcode
|
|
|
|
\sa wc_RsaPad_ex
|
|
*/
|
|
int wc_RsaUnPad_ex(byte* pkcsBlock, word32 pkcsBlockLen,
|
|
byte** out, byte padValue, int padType,
|
|
enum wc_HashType hType, int mgf, byte* optLabel,
|
|
word32 labelLen, int saltLen, int bits, void* heap);
|
|
|
|
/*!
|
|
\ingroup RSA
|
|
\brief Decodes raw RSA private key.
|
|
|
|
\return 0 on success
|
|
\return negative on error
|
|
|
|
\param n Modulus buffer
|
|
\param nSz Modulus size
|
|
\param e Public exponent buffer
|
|
\param eSz Public exponent size
|
|
\param d Private exponent buffer
|
|
\param dSz Private exponent size
|
|
\param u Coefficient buffer
|
|
\param uSz Coefficient size
|
|
\param p Prime p buffer
|
|
\param pSz Prime p size
|
|
\param q Prime q buffer
|
|
\param qSz Prime q size
|
|
\param dP dP buffer
|
|
\param dPSz dP size
|
|
\param dQ dQ buffer
|
|
\param dQSz dQ size
|
|
\param key RSA key
|
|
|
|
_Example_
|
|
\code
|
|
RsaKey key;
|
|
byte n[256], e[3], d[256], u[256], p[128], q[128];
|
|
byte dP[128], dQ[128];
|
|
int ret = wc_RsaPrivateKeyDecodeRaw(n, 256, e, 3, d, 256,
|
|
u, 256, p, 128, q, 128,
|
|
dP, 128, dQ, 128, &key);
|
|
\endcode
|
|
|
|
\sa wc_RsaPrivateKeyDecode
|
|
*/
|
|
int wc_RsaPrivateKeyDecodeRaw(const byte* n, word32 nSz,
|
|
const byte* e, word32 eSz, const byte* d, word32 dSz,
|
|
const byte* u, word32 uSz, const byte* p, word32 pSz,
|
|
const byte* q, word32 qSz, const byte* dP, word32 dPSz,
|
|
const byte* dQ, word32 dQSz, RsaKey* key);
|