Functions
Algorithms - RSA

Functions

WOLFSSL_API int wc_SetKeyUsage (Cert *cert, const char *value)
 This function allows you to set the key usage using a comma delimited string of tokens. Accepted tokens are: digitalSignature, nonRepudiation, contentCommitment, keyCertSign, cRLSign, dataEncipherment, keyAgreement, keyEncipherment, encipherOnly, decipherOnly. Example: "digitalSignature,nonRepudiation" nonRepudiation and contentCommitment are for the same usage. More...
 
WOLFSSL_API int wc_InitRsaKey (RsaKey *key, void *heap)
 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). More...
 
WOLFSSL_API int wc_InitRsaKey_Id (RsaKey *key, unsigned char *id, int len, void *heap, int devId)
 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). More...
 
WOLFSSL_API int wc_RsaSetRNG (RsaKey *key, WC_RNG *rng)
 This function associates RNG with Key. It is needed when WC_RSA_BLINDING is enabled. More...
 
WOLFSSL_API int wc_FreeRsaKey (RsaKey *key)
 This function frees a provided RsaKey struct using mp_clear. More...
 
WOLFSSL_API int wc_RsaPublicEncrypt (const byte *in, word32 inLen, byte *out, word32 outLen, RsaKey *key, WC_RNG *rng)
 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. More...
 
WOLFSSL_API int wc_RsaPrivateDecryptInline (byte *in, word32 inLen, byte **out, RsaKey *key)
 This functions is utilized by the wc_RsaPrivateDecrypt function for decrypting. More...
 
WOLFSSL_API int wc_RsaPrivateDecrypt (const byte *in, word32 inLen, byte *out, word32 outLen, RsaKey *key)
 This functions provides private RSA decryption. More...
 
WOLFSSL_API int wc_RsaSSL_Sign (const byte *in, word32 inLen, byte *out, word32 outLen, RsaKey *key, WC_RNG *rng)
 Signs the provided array with the private key. More...
 
WOLFSSL_API int wc_RsaSSL_VerifyInline (byte *in, word32 inLen, byte **out, RsaKey *key)
 Used to verify that the message was signed by RSA key. The output uses the same byte array as the input. More...
 
WOLFSSL_API int wc_RsaSSL_Verify (const byte *in, word32 inLen, byte *out, word32 outLen, RsaKey *key)
 Used to verify that the message was signed by key. More...
 
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)
 Signs the provided array with the private key. More...
 
WOLFSSL_API int wc_RsaPSS_Verify (byte *in, word32 inLen, byte *out, word32 outLen, enum wc_HashType hash, int mgf, RsaKey *key)
 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. More...
 
WOLFSSL_API int wc_RsaPSS_VerifyInline (byte *in, word32 inLen, byte **out, enum wc_HashType hash, int mgf, RsaKey *key)
 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. More...
 
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)
 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. More...
 
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)
 Verify the message signed with RSA-PSS. The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled. More...
 
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)
 Verify the message signed with RSA-PSS. The input buffer is reused for the output buffer. Salt length is equal to hash length. More...
 
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)
 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. More...
 
WOLFSSL_API int wc_RsaPSS_CheckPadding (const byte *in, word32 inLen, byte *sig, word32 sigSz, enum wc_HashType hashType)
 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. More...
 
WOLFSSL_API int wc_RsaPSS_CheckPadding_ex (const byte *in, word32 inLen, byte *sig, word32 sigSz, enum wc_HashType hashType, int saltLen, int bits)
 Checks the PSS data to ensure that the signature matches. Salt length is equal to hash length. More...
 
WOLFSSL_API int wc_RsaEncryptSize (RsaKey *key)
 Returns the encryption size for the provided key structure. More...
 
WOLFSSL_API int wc_RsaPrivateKeyDecode (const byte *input, word32 *inOutIdx, RsaKey *, word32)
 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. More...
 
WOLFSSL_API int wc_RsaPublicKeyDecode (const byte *input, word32 *inOutIdx, RsaKey *, word32)
 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. More...
 
WOLFSSL_API int wc_RsaPublicKeyDecodeRaw (const byte *n, word32 nSz, const byte *e, word32 eSz, RsaKey *key)
 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. More...
 
WOLFSSL_API int wc_RsaKeyToDer (RsaKey *, byte *output, word32 inLen)
 This function converts an RsaKey key to DER format. The result is written to output and it returns the number of bytes written. More...
 
WOLFSSL_API 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)
 This function performs RSA encrypt while allowing the choice of which padding to use. More...
 
WOLFSSL_API 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)
 This function uses RSA to decrypt a message and gives the option of what padding type. More...
 
WOLFSSL_API int wc_RsaPrivateDecryptInline_ex (byte *in, word32 inLen, byte **out, RsaKey *key, int type, enum wc_HashType hash, int mgf, byte *label, word32 labelSz)
 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. More...
 
WOLFSSL_API int wc_RsaFlattenPublicKey (RsaKey *, byte *, word32 *, byte *, word32 *)
 Flattens the RsaKey structure into individual elements (e, n) used for the RSA algorithm. More...
 
WOLFSSL_API int wc_RsaKeyToPublicDer (RsaKey *key, byte *output, word32 inLen)
 Convert Rsa Public key to DER format. Writes to output, and returns count of bytes written. More...
 
WOLFSSL_API int wc_RsaKeyToPublicDer_ex (RsaKey *key, byte *output, word32 inLen, int with_header)
 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. More...
 
WOLFSSL_API int wc_MakeRsaKey (RsaKey *key, int size, long e, WC_RNG *rng)
 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 RSA_MIN_SIZE and less than 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. More...
 
WOLFSSL_API int wc_RsaSetNonBlock (RsaKey *key, RsaNb *nb)
 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. More...
 
WOLFSSL_API int wc_RsaSetNonBlockTime (RsaKey *key, word32 maxBlockUs, word32 cpuMHz)
 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. More...
 

Detailed Description

Function Documentation

WOLFSSL_API int wc_FreeRsaKey ( RsaKey *  key)

This function frees a provided RsaKey struct using mp_clear.

Returns
0 Returned upon successfully freeing the key
Parameters
keypointer to the RsaKey structure to free

Example

1 RsaKey enc;
2 wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
3 ... set key, do encryption
4 
5 wc_FreeRsaKey(&enc);
See also
wc_InitRsaKey
WOLFSSL_API int wc_InitRsaKey ( RsaKey *  key,
void *  heap 
)

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.

Returns
0 Returned upon successfully initializing the RSA structure for use with encryption and decryption
BAD_FUNC_ARGS Returned if the RSA key pointer evaluates to NULL
Parameters
keypointer to the RsaKey structure to initialize
heappointer 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

1 RsaKey enc;
2 int ret;
3 ret = wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
4 if ( ret != 0 ) {
5  // error initializing RSA key
6 }
See also
wc_RsaInitCavium
wc_FreeRsaKey
wc_RsaSetRNG
WOLFSSL_API int wc_InitRsaKey_Id ( RsaKey *  key,
unsigned char *  id,
int  len,
void *  heap,
int  devId 
)

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.

Returns
0 Returned upon successfully initializing the RSA structure for use with encryption and decryption
BAD_FUNC_ARGS Returned if the RSA key pointer evaluates to NULL
BUFFER_E Returned if len is less than 0 or greater than RSA_MAX_ID_LEN.
Parameters
keypointer to the RsaKey structure to initialize
ididentifier of key on device
lenlength of identifier in bytes
heappointer 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
devIdID to use with hardware device

Example

1 RsaKey enc;
2 unsigned char* id = (unsigned char*)"RSA2048";
3 int len = 6;
4 int devId = 1;
5 int ret;
6 ret = wc_CryptoDev_RegisterDevice(devId, wc_Pkcs11_CryptoDevCb,
7  &token);
8 if ( ret != 0) {
9  // error associating callback and token with device id
10 }
11 ret = wc_InitRsaKey_Id(&enc, id, len, NULL, devId); // not using heap hint
12 if ( ret != 0 ) {
13  // error initializing RSA key
14 }
See also
wc_InitRsaKey
wc_RsaInitCavium
wc_FreeRsaKey
wc_RsaSetRNG
WOLFSSL_API int wc_MakeRsaKey ( RsaKey *  key,
int  size,
long  e,
WC_RNG *  rng 
)

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 RSA_MIN_SIZE and less than 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.

Returns
0 Returned upon successfully generating a RSA private key
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
RNG_FAILURE_E Returned if there is an error generating a random block using the provided RNG structure
MP_INIT_E
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
MP_CMP_E May be returned if there is an error in the math library used while generating the RSA key
MP_INVMOD_E May be returned if there is an error in the math library used while generating the RSA key
MP_EXPTMOD_E May be returned if there is an error in the math library used while generating the RSA key
MP_MOD_E May be returned if there is an error in the math library used while generating the RSA key
MP_MUL_E May be returned if there is an error in the math library used while generating the RSA key
MP_ADD_E May be returned if there is an error in the math library used while generating the RSA key
MP_MULMOD_E May be returned if there is an error in the math library used while generating the RSA key
MP_TO_E May be returned if there is an error in the math library used while generating the RSA key
MP_MEM May be returned if there is an error in the math library used while generating the RSA key
MP_ZERO_E May be returned if there is an error in the math library used while generating the RSA key
Parameters
keypointer to the RsaKey structure in which to store the generated private key
sizedesired key length, in bits. Required to be greater than RSA_MIN_SIZE and less than RSA_MAX_SIZE
eexponent parameter to use for generating the key. A secure choice is 65537
rngpointer to an RNG structure to use for random number generation while making the ke

Example

1 RsaKey priv;
2 WC_WC_RNG rng;
3 int ret = 0;
4 long e = 65537; // standard value to use for exponent
5 
6 wc_InitRsaKey(&priv, NULL); // not using heap hint. No custom memory
7 wc_InitRng(&rng);
8 // generate 2048 bit long private key
9 ret = wc_MakeRsaKey(&priv, 2048, e, &rng);
10 if( ret != 0 ) {
11  // error generating private key
12 }
See also
none
WOLFSSL_API int wc_RsaEncryptSize ( RsaKey *  key)

Returns the encryption size for the provided key structure.

Returns
Success Encryption size for the provided key structure.
Parameters
keyThe key to use for verification.

Example

1 int sz = wc_RsaEncryptSize(&key);
See also
wc_InitRsaKey
wc_InitRsaKey_ex
wc_MakeRsaKey
WOLFSSL_API int wc_RsaFlattenPublicKey ( RsaKey *  ,
byte *  ,
word32 *  ,
byte *  ,
word32 *   
)

Flattens the RsaKey structure into individual elements (e, n) used for the RSA algorithm.

Returns
0 Returned if the function executed normally, without error.
BAD_FUNC_ARG: Returned if any of the parameters are passed in with a null value.
RSA_BUFFER_E: Returned if the e or n buffers passed in are not the correct size.
MP_MEM: Returned if an internal function has memory errors.
MP_VAL: Returned if an internal function argument is not valid.
Parameters
keyThe key to use for verification.
ea buffer for the value of e. e is a large positive integer in the RSA modular arithmetic operation.
eSzthe size of the e buffer.
na buffer for the value of n. n is a large positive integer in the RSA modular arithmetic operation.
nSzthe size of the n buffer.

Example

1 Rsa key; // A valid RSA key.
2 byte e[ buffer sz E.g. 256 ];
3 byte n[256];
4 int ret;
5 word32 eSz = sizeof(e);
6 word32 nSz = sizeof(n);
7 ...
8 ret = wc_RsaFlattenPublicKey(&key, e, &eSz, n, &nSz);
9 if (ret != 0) {
10  // Failure case.
11 }
See also
wc_InitRsaKey
wc_InitRsaKey_ex
wc_MakeRsaKey
WOLFSSL_API int wc_RsaKeyToDer ( RsaKey *  ,
byte *  output,
word32  inLen 
)

This function converts an RsaKey key to DER format. The result is written to output and it returns the number of bytes written.

Returns
0 Success
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.
MEMORY_E Returned if there is an error allocating memory.
Parameters
keyInitialized RsaKey structure.
outputPointer to output buffer.
inLenSize of output buffer.

Example

1 byte* der;
2 // Allocate memory for der
3 int derSz = // Amount of memory allocated for der;
4 RsaKey key;
5 WC_WC_RNG rng;
6 long e = 65537; // standard value to use for exponent
7 ret = wc_MakeRsaKey(&key, 2048, e, &rng); // generate 2048 bit long
8 private key
9 wc_InitRsaKey(&key, NULL);
10 wc_InitRng(&rng);
11 if(wc_RsaKeyToDer(&key, der, derSz) != 0)
12 {
13  // Handle the error thrown
14 }
See also
wc_RsaKeyToPublicDer
wc_InitRsaKey
wc_MakeRsaKey
wc_InitRng
WOLFSSL_API int wc_RsaKeyToPublicDer ( RsaKey *  key,
byte *  output,
word32  inLen 
)

Convert Rsa Public key to DER format. Writes to output, and returns count of bytes written.

Returns
>0 Success, number of bytes written.
BAD_FUNC_ARG Returned if key or output is null.
MEMORY_E Returned when an error allocating memory occurs.
<0 Error
Parameters
keyThe RSA key structure to convert.
outputOutput buffer to hold DER. (if NULL will return length only)
inLenLength of buffer.

Example

1 RsaKey key;
2 
3 wc_InitRsaKey(&key, NULL);
4 // Use key
5 
6 const int BUFFER_SIZE = 1024; // Some adequate size for the buffer
7 byte output[BUFFER_SIZE];
8 if (wc_RsaKeyToPublicDer(&key, output, sizeof(output)) != 0) {
9  // Handle Error
10 }
See also
wc_RsaPublicKeyDerSize
wc_RsaKeyToPublicDer_ex
wc_InitRsaKey
WOLFSSL_API int wc_RsaKeyToPublicDer_ex ( RsaKey *  key,
byte *  output,
word32  inLen,
int  with_header 
)

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.

Returns
>0 Success, number of bytes written.
BAD_FUNC_ARG Returned if key or output is null.
MEMORY_E Returned when an error allocating memory occurs.
<0 Error
Parameters
keyThe RSA key structure to convert.
outputOutput buffer to hold DER. (if NULL will return length only)
inLenLength of buffer.

Example

1 RsaKey key;
2 
3 wc_InitRsaKey(&key, NULL);
4 // Use key
5 
6 const int BUFFER_SIZE = 1024; // Some adequate size for the buffer
7 byte output[BUFFER_SIZE];
8 if (wc_RsaKeyToPublicDer_ex(&key, output, sizeof(output), 0) != 0) {
9  // Handle Error
10 }
See also
wc_RsaPublicKeyDerSize
wc_RsaKeyToPublicDer
wc_InitRsaKey
WOLFSSL_API int wc_RsaPrivateDecrypt ( const byte *  in,
word32  inLen,
byte *  out,
word32  outLen,
RsaKey *  key 
)

This functions provides private RSA decryption.

Returns
Success length of decrypted data.
MEMORY_E -125, out of memory error
BAD_FUNC_ARG -173, Bad function argument provided
Parameters
inThe byte array to be decrypted.
inLenThe length of in.
outThe byte array for the decrypted data to be stored.
outLenThe length of out.
keyThe key to use for decryption.

Example

1 ret = wc_RsaPublicEncrypt(in, inLen, out, sizeof(out), &key, &rng);
2 if (ret < 0) {
3  return -1;
4 }
5 ret = wc_RsaPrivateDecrypt(out, ret, plain, sizeof(plain), &key);
6 if (ret < 0) {
7  return -1;
8 }
See also
RsaUnPad
wc_RsaFunction
wc_RsaPrivateDecryptInline
WOLFSSL_API 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 
)

This function uses RSA to decrypt a message and gives the option of what padding type.

Returns
size On successful decryption, the size of the decrypted message is returned.
MEMORY_E Returned if not enough memory on system to malloc a needed array.
BAD_FUNC_ARG Returned if a bad argument was passed into the function.
Parameters
inpointer to the buffer for decryption
inLenlength of the buffer to decrypt
outdecrypted msg created
outLenlength of buffer available to hold decrypted msg
keyinitialized RSA key struct
typetype of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
hashtype of hash to use (choices can be found in hash.h)
mgftype of mask generation function to use
labelan optional label to associate with encrypted message
labelSzsize of the optional label used

Example

1 WC_WC_WC_RNG rng;
2 RsaKey key;
3 byte in[] = “I use Turing Machines to ask questions”
4 byte out[256];
5 byte plain[256];
6 int ret;
7 …
8 ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key,
9 &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
10 if (ret < 0) {
11  //handle error
12 }
13 …
14 ret = wc_RsaPrivateDecrypt_ex(out, ret, plain, sizeof(plain), &key,
15 WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
16 
17 if (ret < 0) {
18  //handle error
19 }
See also
none
WOLFSSL_API int wc_RsaPrivateDecryptInline ( byte *  in,
word32  inLen,
byte **  out,
RsaKey *  key 
)

This functions is utilized by the wc_RsaPrivateDecrypt function for decrypting.

Returns
Success Length of decrypted data.
RSA_PAD_E RsaUnPad error, bad formatting
Parameters
inThe byte array to be decrypted.
inLenThe length of in.
outThe byte array for the decrypted data to be stored.
keyThe key to use for decryption.

Example

1 none
See also
wc_RsaPrivateDecrypt
WOLFSSL_API int wc_RsaPrivateDecryptInline_ex ( byte *  in,
word32  inLen,
byte **  out,
RsaKey *  key,
int  type,
enum wc_HashType  hash,
int  mgf,
byte *  label,
word32  labelSz 
)

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.

Returns
size On successful decryption, the size of the decrypted message is returned.
MEMORY_E: Returned if not enough memory on system to malloc a needed array.
RSA_PAD_E: Returned if an error in the padding was encountered.
BAD_PADDING_E: Returned if an error happened during parsing past padding.
BAD_FUNC_ARG: Returned if a bad argument was passed into the function.
Parameters
inpointer to the buffer for decryption
inLenlength of the buffer to decrypt
outpointer to location of decrypted message in “in” buffer
keyinitialized RSA key struct
typetype of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
hashtype of hash to use (choices can be found in hash.h)
mgftype of mask generation function to use
labelan optional label to associate with encrypted message
labelSzsize of the optional label used

Example

1 WC_WC_WC_RNG rng;
2 RsaKey key;
3 byte in[] = “I use Turing Machines to ask questions”
4 byte out[256];
5 byte* plain;
6 int ret;
7 …
8 ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key,
9 &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
10 
11 if (ret < 0) {
12  //handle error
13 }
14 …
15 ret = wc_RsaPrivateDecryptInline_ex(out, ret, &plain, &key,
16 WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
17 
18 if (ret < 0) {
19  //handle error
20 }
See also
none
WOLFSSL_API int wc_RsaPrivateKeyDecode ( const byte *  input,
word32 *  inOutIdx,
RsaKey *  ,
word32   
)

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.

Returns
0 Returned upon successfully parsing the private key from the DER encoded input
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
ASN_RSA_KEY_E Returned if there is an error reading the private key elements of the RSA key input
Parameters
inputpointer to the buffer containing the DER formatted private key to decode
inOutIdxpointer 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
keypointer to the RsaKey structure in which to store the decoded private key
inSzsize of the input buffer

Example

1 RsaKey enc;
2 word32 idx = 0;
3 int ret = 0;
4 byte der[] = { // initialize with DER-encoded RSA private key };
5 
6 wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
7 ret = wc_RsaPrivateKeyDecode(der, &idx, &enc, sizeof(der));
8 if( ret != 0 ) {
9  // error parsing private key
10 }
See also
wc_RsaPublicKeyDecode
wc_MakeRsaKey
WOLFSSL_API int wc_RsaPSS_CheckPadding ( const byte *  in,
word32  inLen,
byte *  sig,
word32  sigSz,
enum wc_HashType  hashType 
)

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.

Returns
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.
MEMORY_E memory exception.
Parameters
inHash of the data that is being verified.
inSzLength of hash.
sigBuffer holding PSS data.
sigSzSize of PSS data.
hashTypeHash algorithm.

Example

1 ret = wc_InitRsaKey(&key, NULL);
2 if (ret == 0) {
3  ret = wc_InitRng(&rng);
4 } else return -1;
5 if (ret == 0) {
6  ret = wc_RsaSetRNG(&key, &rng);
7 } else return -1;
8 if (ret == 0) {
9  ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
10 } else return -1;
11 if (ret == 0) {
12  digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
13  ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
14 } else return -1;
15 ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, sizeof(pSignature),
16  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
17 if (ret > 0 ){
18  sz = ret;
19 } else return -1;
20 
21 verify = wc_RsaPSS_Verify(pSignature, sz, out, outLen,
22  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
23 if (verify <= 0)return -1;
24 
25 ret = wc_RsaPSS_CheckPadding(digest, digestSz, out, verify, hash);
26 
27 wc_FreeRsaKey(&key);
28 wc_FreeRng(&rng);
See also
wc_RsaPSS_Sign
wc_RsaPSS_Verify
wc_RsaPSS_VerifyInline
wc_RsaPSS_VerifyCheck
wc_RsaPSS_VerifyCheck_ex
wc_RsaPSS_VerifyCheckInline
wc_RsaPSS_VerifyCheckInline_ex
wc_RsaPSS_CheckPadding_ex
wc_RsaSetRNG
WOLFSSL_API int wc_RsaPSS_CheckPadding_ex ( const byte *  in,
word32  inLen,
byte *  sig,
word32  sigSz,
enum wc_HashType  hashType,
int  saltLen,
int  bits 
)

Checks the PSS data to ensure that the signature matches. Salt length is equal to hash length.

Returns
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.
MEMORY_E memory exception.
Parameters
inHash of the data that is being verified.
inSzLength of hash.
sigBuffer holding PSS data.
sigSzSize of PSS data.
hashTypeHash algorithm.
saltLenLength 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.
bitsCan be used to calculate salt size in FIPS case

Example

1 ret = wc_InitRsaKey(&key, NULL);
2 if (ret == 0) {
3  ret = wc_InitRng(&rng);
4 } else return -1;
5 if (ret == 0) {
6  ret = wc_RsaSetRNG(&key, &rng);
7 } else return -1;
8 if (ret == 0) {
9  ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
10 } else return -1;
11 if (ret == 0) {
12  digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
13  ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
14 } else return -1;
15 ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, sizeof(pSignature),
16  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
17 if (ret > 0 ){
18  sz = ret;
19 } else return -1;
20 
21 verify = wc_RsaPSS_Verify(pSignature, sz, out, outLen,
22  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
23 if (verify <= 0)return -1;
24 
25 ret = wc_RsaPSS_CheckPadding_ex(digest, digestSz, out, verify, hash, saltLen, 0);
26 
27 wc_FreeRsaKey(&key);
28 wc_FreeRng(&rng);
See also
wc_RsaPSS_Sign
wc_RsaPSS_Verify
wc_RsaPSS_VerifyInline
wc_RsaPSS_VerifyCheck
wc_RsaPSS_VerifyCheck_ex
wc_RsaPSS_VerifyCheckInline
wc_RsaPSS_VerifyCheckInline_ex
wc_RsaPSS_CheckPadding
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 
)

Signs the provided array with the private key.

Returns
RSA_BUFFER_E: -131, RSA buffer error, output too small or input too large
Parameters
inThe byte array to be encrypted.
inLenThe length of in.
outThe byte array for the encrypted data to be stored.
outLenThe length of out.
hashThe hash type to be in message
mgfMask Generation Function Identifiers
keyThe key to use for verification.

Example

1 ret = wc_InitRsaKey(&key, NULL);
2 if (ret == 0) {
3  ret = wc_InitRng(&rng);
4 } else return -1;
5 if (ret == 0) {
6  ret = wc_RsaSetRNG(&key, &rng);
7 } else return -1;
8 if (ret == 0) {
9  ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
10 } else return -1;
11 
12 ret = wc_RsaPSS_Sign((byte*)szMessage, (word32)XSTRLEN(szMessage)+1,
13  pSignature, sizeof(pSignature),
14  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
15 if (ret > 0 ){
16  sz = ret;
17 } else return -1;
18 
19 ret = wc_RsaPSS_Verify(pSignature, sz, pt, outLen,
20  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
21 if (ret <= 0)return -1;
22 
23 wc_FreeRsaKey(&key);
24 wc_FreeRng(&rng);
See also
wc_RsaPSS_Verify
wc_RsaSetRNG
WOLFSSL_API int wc_RsaPSS_Verify ( byte *  in,
word32  inLen,
byte *  out,
word32  outLen,
enum wc_HashType  hash,
int  mgf,
RsaKey *  key 
)

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.

Returns
Success Length of text on no error.
MEMORY_E memory exception.
Parameters
inThe byte array to be decrypted.
inLenThe length of in.
outThe byte array for the decrypted data to be stored.
outLenThe length of out.
hashThe hash type to be in message
mgfMask Generation Function Identifiers
keyThe key to use for verification.

Example

1 ret = wc_InitRsaKey(&key, NULL);
2 if (ret == 0) {
3  ret = wc_InitRng(&rng);
4 } else return -1;
5 if (ret == 0) {
6  ret = wc_RsaSetRNG(&key, &rng);
7 } else return -1;
8 if (ret == 0) {
9  ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
10 } else return -1;
11 ret = wc_RsaPSS_Sign((byte*)szMessage, (word32)XSTRLEN(szMessage)+1,
12  pSignature, sizeof(pSignature),
13  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
14 if (ret > 0 ){
15  sz = ret;
16 } else return -1;
17 
18 ret = wc_RsaPSS_Verify(pSignature, sz, pt, outLen,
19  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
20 if (ret <= 0)return -1;
21 
22 wc_FreeRsaKey(&key);
23 wc_FreeRng(&rng);
See also
wc_RsaPSS_Sign
wc_RsaPSS_VerifyInline
wc_RsaPSS_CheckPadding
wc_RsaSetRNG
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 
)

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.

Returns
the length of the PSS data on success and negative indicates failure.
MEMORY_E memory exception.
Parameters
inThe byte array to be decrypted.
inLenThe length of in.
outPointer to address containing the PSS data.
outLenThe length of out.
digestHash of the data that is being verified.
digestLenLength of hash.
hashHash algorithm.
mgfMask generation function.
keyPublic RSA key.

Example

1 ret = wc_InitRsaKey(&key, NULL);
2 if (ret == 0) {
3  ret = wc_InitRng(&rng);
4 } else return -1;
5 if (ret == 0) {
6  ret = wc_RsaSetRNG(&key, &rng);
7 } else return -1;
8 if (ret == 0) {
9  ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
10 } else return -1;
11 
12 if (ret == 0) {
13  digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
14  ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
15 } else return -1;
16 
17 if (ret == 0) {
18  ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
19  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
20  if (ret > 0 ){
21  sz = ret;
22  } else return -1;
23 } else return -1;
24 if (ret == 0) {
25  ret = wc_RsaPSS_VerifyCheck(pSignature, sz, pt, outLen,
26  digest, digestSz, WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
27  if (ret <= 0) return -1;
28 } else return -1;
29 
30 wc_FreeRsaKey(&key);
31 wc_FreeRng(&rng);
See also
wc_RsaPSS_Sign
wc_RsaPSS_Verify
wc_RsaPSS_VerifyCheck_ex
wc_RsaPSS_VerifyCheckInline
wc_RsaPSS_VerifyCheckInline_ex
wc_RsaPSS_CheckPadding
wc_RsaPSS_CheckPadding_ex
wc_RsaSetRNG
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 
)

Verify the message signed with RSA-PSS. The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.

Returns
the length of the PSS data on success and negative indicates failure.
MEMORY_E memory exception.
Parameters
inThe byte array to be decrypted.
inLenThe length of in.
outPointer to address containing the PSS data.
outLenThe length of out.
digestHash of the data that is being verified.
digestLenLength of hash.
hashHash algorithm.
mgfMask generation function.
saltLenLength 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.
keyPublic RSA key.

Example

1 ret = wc_InitRsaKey(&key, NULL);
2 if (ret == 0) {
3  ret = wc_InitRng(&rng);
4 } else return -1;
5 if (ret == 0) {
6  ret = wc_RsaSetRNG(&key, &rng);
7 } else return -1;
8 if (ret == 0) {
9  ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
10 } else return -1;
11 
12 if (ret == 0) {
13  digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
14  ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
15 } else return -1;
16 
17 if (ret == 0) {
18  ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
19  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
20  if (ret > 0 ){
21  sz = ret;
22  } else return -1;
23 } else return -1;
24 if (ret == 0) {
25  ret = wc_RsaPSS_VerifyCheck_ex(pSignature, sz, pt, outLen,
26  digest, digestSz, WC_HASH_TYPE_SHA256, WC_MGF1SHA256, saltLen, &key);
27  if (ret <= 0) return -1;
28 } else return -1;
29 
30 wc_FreeRsaKey(&key);
31 wc_FreeRng(&rng);
See also
wc_RsaPSS_Sign
wc_RsaPSS_Verify
wc_RsaPSS_VerifyCheck
wc_RsaPSS_VerifyCheckInline
wc_RsaPSS_VerifyCheckInline_ex
wc_RsaPSS_CheckPadding
wc_RsaPSS_CheckPadding_ex
wc_RsaSetRNG
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 
)

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.

Returns
the length of the PSS data on success and negative indicates failure.
Parameters
inThe byte array to be decrypted.
inLenThe length of in.
outThe byte array for the decrypted data to be stored.
digestHash of the data that is being verified.
digestLenLength of hash.
hashThe hash type to be in message
mgfMask Generation Function Identifiers
keyThe key to use for verification.

Example

1 ret = wc_InitRsaKey(&key, NULL);
2 if (ret == 0) {
3  ret = wc_InitRng(&rng);
4 } else return -1;
5 if (ret == 0) {
6  ret = wc_RsaSetRNG(&key, &rng);
7 } else return -1;
8 if (ret == 0) {
9  ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
10 } else return -1;
11 
12 if (ret == 0) {
13  digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
14  ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
15 } else return -1;
16 
17 if (ret == 0) {
18  ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
19  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
20  if (ret > 0 ){
21  sz = ret;
22  } else return -1;
23 } else return -1;
24 if (ret == 0) {
25  ret = wc_RsaPSS_VerifyCheckInline(pSignature, sz, pt,
26  digest, digestSz, WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
27  if (ret <= 0) return -1;
28 } else return -1;
29 
30 wc_FreeRsaKey(&key);
31 wc_FreeRng(&rng);
See also
wc_RsaPSS_Sign
wc_RsaPSS_Verify
wc_RsaPSS_VerifyCheck
wc_RsaPSS_VerifyCheck_ex
wc_RsaPSS_VerifyCheckInline_ex
wc_RsaPSS_CheckPadding
wc_RsaPSS_CheckPadding_ex
wc_RsaSetRNG
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 
)

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.

Returns
the length of the PSS data on success and negative indicates failure.
Parameters
inThe byte array to be decrypted.
inLenThe length of in.
outThe byte array for the decrypted data to be stored.
digestHash of the data that is being verified.
digestLenLength of hash.
hashThe hash type to be in message
mgfMask Generation Function Identifiers
saltLenLength 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.
keyThe key to use for verification.

Example

1 ret = wc_InitRsaKey(&key, NULL);
2 if (ret == 0) {
3  ret = wc_InitRng(&rng);
4 } else return -1;
5 if (ret == 0) {
6  ret = wc_RsaSetRNG(&key, &rng);
7 } else return -1;
8 if (ret == 0) {
9  ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
10 } else return -1;
11 
12 if (ret == 0) {
13  digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
14  ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
15 } else return -1;
16 
17 if (ret == 0) {
18  ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
19  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
20  if (ret > 0 ){
21  sz = ret;
22  } else return -1;
23 } else return -1;
24 if (ret == 0) {
25  ret = wc_RsaPSS_VerifyCheckInline_ex(pSignature, sz, pt,
26  digest, digestSz, WC_HASH_TYPE_SHA256, WC_MGF1SHA256, saltLen, &key);
27  if (ret <= 0) return -1;
28 } else return -1;
29 
30 wc_FreeRsaKey(&key);
31 wc_FreeRng(&rng);
See also
wc_RsaPSS_Sign
wc_RsaPSS_Verify
wc_RsaPSS_VerifyCheck
wc_RsaPSS_VerifyCheck_ex
wc_RsaPSS_VerifyCheckInline
wc_RsaPSS_CheckPadding
wc_RsaPSS_CheckPadding_ex
wc_RsaSetRNG
WOLFSSL_API int wc_RsaPSS_VerifyInline ( byte *  in,
word32  inLen,
byte **  out,
enum wc_HashType  hash,
int  mgf,
RsaKey *  key 
)

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.

Returns
>0 Length of text.
<0 An error occurred.
Parameters
inByte array to be decrypted.
inLenLength of the buffer input.
outPointer to address containing the PSS data.
hashThe hash type to be in message
mgfMask Generation Function Identifiers
keyRsaKey to use.

_Example_

1 ret = wc_InitRsaKey(&key, NULL);
2 if (ret == 0) {
3  ret = wc_InitRng(&rng);
4 } else return -1;
5 if (ret == 0) {
6  ret = wc_RsaSetRNG(&key, &rng);
7 } else return -1;
8 if (ret == 0) {
9  ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
10 } else return -1;
11 ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
12  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
13 if (ret > 0 ){
14  sz = ret;
15 } else return -1;
16 
17 ret = wc_RsaPSS_VerifyInline(pSignature, sz, pt,
18  WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
19 if (ret <= 0)return -1;
20 
21 wc_FreeRsaKey(&key);
22 wc_FreeRng(&rng);
See also
wc_RsaPSS_Verify
wc_RsaPSS_Sign
wc_RsaPSS_VerifyCheck
wc_RsaPSS_VerifyCheck_ex
wc_RsaPSS_VerifyCheckInline
wc_RsaPSS_VerifyCheckInline_ex
wc_RsaPSS_CheckPadding
wc_RsaPSS_CheckPadding_ex
wc_RsaSetRNG
WOLFSSL_API int wc_RsaPublicEncrypt ( const byte *  in,
word32  inLen,
byte *  out,
word32  outLen,
RsaKey *  key,
WC_RNG *  rng 
)

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.

Returns
Success Upon successfully encrypting the input message, returns 0 for success and less than zero for failure. Also returns the number bytes written to out by storing the value in outLen
BAD_FUNC_ARG Returned if any of the input parameters are invalid
RSA_BUFFER_E Returned if the output buffer is too small to store the ciphertext
RNG_FAILURE_E Returned if there is an error generating a random block using the provided RNG structure
MP_INIT_E May be returned if there is an error in the math library used while encrypting the message
MP_READ_E May be returned if there is an error in the math library used while encrypting the message
MP_CMP_E May be returned if there is an error in the math library used while encrypting the message
MP_INVMOD_E May be returned if there is an error in the math library used while encrypting the message
MP_EXPTMOD_E May be returned if there is an error in the math library used while encrypting the message
MP_MOD_E May be returned if there is an error in the math library used while encrypting the message
MP_MUL_E May be returned if there is an error in the math library used while encrypting the message
MP_ADD_E May be returned if there is an error in the math library used while encrypting the message
MP_MULMOD_E May be returned if there is an error in the math library used while encrypting the message
MP_TO_E May be returned if there is an error in the math library used while encrypting the message
MP_MEM May be returned if there is an error in the math library used while encrypting the message
MP_ZERO_E May be returned if there is an error in the math library used while encrypting the message
Parameters
inpointer to a buffer containing the input message to encrypt
inLenthe length of the message to encrypt
outpointer to the buffer in which to store the output ciphertext
outLenthe length of the output buffer
keypointer to the RsaKey structure containing the public key to use for encryption
rngThe RNG structure with which to generate random block padding

Example

1 RsaKey pub;
2 int ret = 0;
3 byte n[] = { // initialize with received n component of public key };
4 byte e[] = { // initialize with received e component of public key };
5 byte msg[] = { // initialize with plaintext of message to encrypt };
6 byte cipher[256]; // 256 bytes is large enough to store 2048 bit RSA
7 ciphertext
8 
9 wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
10 wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub);
11 // initialize with received public key parameters
12 ret = wc_RsaPublicEncrypt(msg, sizeof(msg), out, sizeof(out), &pub, &rng);
13 if ( ret != 0 ) {
14  // error encrypting message
15 }
See also
wc_RsaPrivateDecrypt
WOLFSSL_API 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 
)

This function performs RSA encrypt while allowing the choice of which padding to use.

Returns
size On successfully encryption the size of the encrypted buffer is returned
RSA_BUFFER_E RSA buffer error, output too small or input too large
Parameters
inpointer to the buffer for encryption
inLenlength of the buffer to encrypt
outencrypted msg created
outLenlength of buffer available to hold encrypted msg
keyinitialized RSA key struct
rnginitialized WC_RNG struct
typetype of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
hashtype of hash to use (choices can be found in hash.h)
mgftype of mask generation function to use
labelan optional label to associate with encrypted message
labelSzsize of the optional label used

Example

1 WC_WC_WC_RNG rng;
2 RsaKey key;
3 byte in[] = “I use Turing Machines to ask questions”
4 byte out[256];
5 int ret;
6 …
7 
8 ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, &rng,
9 WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
10 if (ret < 0) {
11  //handle error
12 }
See also
wc_RsaPublicEncrypt
wc_RsaPrivateDecrypt_ex
WOLFSSL_API int wc_RsaPublicKeyDecode ( const byte *  input,
word32 *  inOutIdx,
RsaKey *  ,
word32   
)

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.

Returns
0 Returned upon successfully parsing the public key from the DER encoded input
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
ASN_OBJECT_ID_E Returned if the ASN.1 Object ID does not match that of a RSA public key
ASN_EXPECT_0_E Returned if the input key is not correctly formatted according to ASN.1 standards
ASN_BITSTR_E Returned if the input key is not correctly formatted according to ASN.1 standards
ASN_RSA_KEY_E Returned if there is an error reading the public key elements of the RSA key input
Parameters
inputpointer to the buffer containing the input DER-encoded RSA public key to decode
inOutIdxpointer 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
keypointer to the RsaKey structure in which to store the decoded public key
inSzsize of the input buffer

Example

1 RsaKey pub;
2 word32 idx = 0;
3 int ret = 0;
4 byte der[] = { // initialize with DER-encoded RSA public key };
5 
6 wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
7 ret = wc_RsaPublicKeyDecode(der, &idx, &pub, sizeof(der));
8 if( ret != 0 ) {
9  // error parsing public key
10 }
See also
wc_RsaPublicKeyDecodeRaw
WOLFSSL_API int wc_RsaPublicKeyDecodeRaw ( const byte *  n,
word32  nSz,
const byte *  e,
word32  eSz,
RsaKey *  key 
)

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.

Returns
0 Returned upon successfully decoding the raw elements of the public key into the RsaKey structure
BAD_FUNC_ARG Returned if any of the input arguments evaluates to NULL
MP_INIT_E Returned if there is an error initializing an integer for use with the multiple precision integer (mp_int) library
ASN_GETINT_E Returned if there is an error reading one of the provided RSA key elements, n or e
Parameters
npointer to a buffer containing the raw modulus parameter of the public RSA key
nSzsize of the buffer containing n
epointer to a buffer containing the raw exponent parameter of the public RSA key
eSzsize of the buffer containing e
keypointer to the RsaKey struct to initialize with the provided public key elements

Example

1 RsaKey pub;
2 int ret = 0;
3 byte n[] = { // initialize with received n component of public key };
4 byte e[] = { // initialize with received e component of public key };
5 
6 wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
7 ret = wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub);
8 if( ret != 0 ) {
9  // error parsing public key elements
10 }
See also
wc_RsaPublicKeyDecode
WOLFSSL_API int wc_RsaSetNonBlock ( RsaKey *  key,
RsaNb *  nb 
)

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.

Returns
0 Success
BAD_FUNC_ARG Returned if key or nb is null.
Parameters
keyThe RSA key structure
nbThe RSA non-blocking structure for this RSA key to use.

Example

1 int ret, count = 0;
2 RsaKey key;
3 RsaNb nb;
4 
5 wc_InitRsaKey(&key, NULL);
6 
7 // Enable non-blocking RSA mode - provide context
8 ret = wc_RsaSetNonBlock(key, &nb);
9 if (ret != 0)
10  return ret;
11 
12 do {
13  ret = wc_RsaSSL_Sign(in, inLen, out, outSz, key, rng);
14  count++; // track number of would blocks
15  if (ret == FP_WOULDBLOCK) {
16  // do "other" work here
17  }
18 } while (ret == FP_WOULDBLOCK);
19 if (ret < 0) {
20  return ret;
21 }
22 
23 printf("RSA non-block sign: size %d, %d times\n", ret, count);
See also
wc_RsaSetNonBlockTime
WOLFSSL_API int wc_RsaSetNonBlockTime ( RsaKey *  key,
word32  maxBlockUs,
word32  cpuMHz 
)

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.

Returns
0 Success
BAD_FUNC_ARG Returned if key is null or wc_RsaSetNonBlock was not previously called and key->nb is null.
Parameters
keyThe RSA key structure.
maxBlockUsMaximum time to block microseconds.
cpuMHzCPU speed in megahertz.

Example

1 RsaKey key;
2 RsaNb nb;
3 
4 wc_InitRsaKey(&key, NULL);
5 wc_RsaSetNonBlock(key, &nb);
6 wc_RsaSetNonBlockTime(&key, 4000, 160); // Block Max = 4 ms, CPU = 160MHz
See also
wc_RsaSetNonBlock
WOLFSSL_API int wc_RsaSetRNG ( RsaKey *  key,
WC_RNG *  rng 
)

This function associates RNG with Key. It is needed when WC_RSA_BLINDING is enabled.

Returns
0 Returned upon success
BAD_FUNC_ARGS Returned if the RSA key, rng pointer evaluates to NULL
Parameters
keypointer to the RsaKey structure to be associated
rngpointer to the WC_RNG structure to associate with

Example

1 ret = wc_InitRsaKey(&key, NULL);
2 if (ret == 0) {
3  ret = wc_InitRng(&rng);
4 } else return -1;
5 if (ret == 0) {
6  ret = wc_RsaSetRNG(&key, &rng);
See also
wc_InitRsaKey
wc_RsaSetRNG
WOLFSSL_API int wc_RsaSSL_Sign ( const byte *  in,
word32  inLen,
byte *  out,
word32  outLen,
RsaKey *  key,
WC_RNG *  rng 
)

Signs the provided array with the private key.

Returns
RSA_BUFFER_E: -131, RSA buffer error, output too small or input too large
Parameters
inThe byte array to be encrypted.
inLenThe length of in.
outThe byte array for the encrypted data to be stored.
outLenThe length of out.
keyThe key to use for encryption.
RNGThe RNG struct to use for random number purposes.

Example

1 ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng);
2 if (ret < 0) {
3  return -1;
4 }
5 memset(plain, 0, sizeof(plain));
6 ret = wc_RsaSSL_Verify(out, ret, plain, sizeof(plain), &key);
7 if (ret < 0) {
8  return -1;
9 }
See also
wc_RsaPad
WOLFSSL_API int wc_RsaSSL_Verify ( const byte *  in,
word32  inLen,
byte *  out,
word32  outLen,
RsaKey *  key 
)

Used to verify that the message was signed by key.

Returns
Success Length of text on no error.
MEMORY_E memory exception.
Parameters
inThe byte array to be decrypted.
inLenThe length of in.
outThe byte array for the decrypted data to be stored.
outLenThe length of out.
keyThe key to use for verification.

Example

1 ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng);
2 if (ret < 0) {
3  return -1;
4 }
5 memset(plain, 0, sizeof(plain));
6 ret = wc_RsaSSL_Verify(out, ret, plain, sizeof(plain), &key);
7 if (ret < 0) {
8  return -1;
9 }
See also
wc_RsaSSL_Sign
WOLFSSL_API int wc_RsaSSL_VerifyInline ( byte *  in,
word32  inLen,
byte **  out,
RsaKey *  key 
)

Used to verify that the message was signed by RSA key. The output uses the same byte array as the input.

Returns
>0 Length of text.
<0 An error occurred.
Parameters
inByte array to be decrypted.
inLenLength of the buffer input.
outPointer to a pointer for decrypted information.
keyRsaKey to use.

Example

1 RsaKey key;
2 WC_WC_RNG rng;
3 int ret = 0;
4 long e = 65537; // standard value to use for exponent
5 wc_InitRsaKey(&key, NULL); // not using heap hint. No custom memory
6 wc_InitRng(&rng);
7 wc_MakeRsaKey(&key, 2048, e, &rng);
8 
9 byte in[] = { // Initialize with some RSA encrypted information }
10 byte* out;
11 if(wc_RsaSSL_VerifyInline(in, sizeof(in), &out, &key) < 0)
12 {
13  // handle error
14 }
See also
wc_RsaSSL_Verify
wc_RsaSSL_Sign
WOLFSSL_API int wc_SetKeyUsage ( Cert *  cert,
const char *  value 
)

This function allows you to set the key usage using a comma delimited string of tokens. Accepted tokens are: digitalSignature, nonRepudiation, contentCommitment, keyCertSign, cRLSign, dataEncipherment, keyAgreement, keyEncipherment, encipherOnly, decipherOnly. Example: "digitalSignature,nonRepudiation" nonRepudiation and contentCommitment are for the same usage.

Returns
0 Success
BAD_FUNC_ARG Returned when either arg is null.
MEMORY_E Returned when there is an error allocating memory.
KEYUSAGE_E Returned if an unrecognized token is entered.
Parameters
certPointer to initialized Cert structure.
valueComma delimited string of tokens to set usage.

Example

1 Cert cert;
2 wc_InitCert(&cert);
3 
4 if(wc_SetKeyUsage(&cert, "cRLSign,keyCertSign") != 0)
5 {
6  // Handle error
7 }
See also
wc_InitCert
wc_MakeRsaKey