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.
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).
WOLFSSL_API int	wc_FreeRsaKey (RsaKey *key)
	This function frees a provided RsaKey struct using mp_clear.
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.
WOLFSSL_API int	wc_RsaPrivateDecryptInline (byte *in, word32 inLen, byte **out, RsaKey *key)
	This functions is utilized by the wc_RsaPrivateDecrypt function for decrypting.
WOLFSSL_API int	wc_RsaPrivateDecrypt (const byte *in, word32 inLen, byte *out, word32 outLen, RsaKey *key)
	This functions provides private RSA decryption.
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.
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.
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.
WOLFSSL_API int	wc_RsaEncryptSize (RsaKey *key)
	Returns the encryption size for the provided key structure.
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.
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.
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.
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.
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 lableSz)
	This function performs RSA encrypt while allowing the choice of which padding to use.
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 lableSz)
	This function uses RSA to decrypt a message and gives the option of what padding type.
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 lableSz)
	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.
WOLFSSL_API int	wc_RsaFlattenPublicKey (RsaKey *, byte *, word32 *, byte *, word32 *)
	Flattens the RsaKey structure into individual elements (e, n) used for the RSA algorithm.
WOLFSSL_API int	wc_RsaKeyToPublicDer (RsaKey *, byte *output, word32 inLen)
	Convert Rsa Public key to DER format. Writes to output, and returns count of bytes written.
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.
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.
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.

Detailed Description

Function Documentation

wc_FreeRsaKey()

int wc_FreeRsaKey

(

RsaKey *

key

)

This function frees a provided RsaKey struct using mp_clear.

Returns

0 Returned upon successfully freeing the key

Parameters

key	pointer to the RsaKey structure to free

Example

RsaKey enc;
wc_RsaInitKey(&enc, NULL); // not using heap hint. No custom memory
... set key, do encryption
 
wc_FreeRsaKey(&enc);

See also

wc_InitRsaKey

wc_InitRsaKey()

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

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

key	pointer to the RsaKey structure to initialize
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

RsaKey enc;
int ret;
ret = wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
if ( ret != 0 ) {
    // error initializing RSA key
}

See also

wc_RsaInitCavium

wc_FreeRsaKey

wc_MakeRsaKey()

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

key	pointer to the RsaKey structure in which to store the generated private key
size	desired keylenth, in bits. Required to be greater than RSA_MIN_SIZE and less than RSA_MAX_SIZE
e	exponent parameter to use for generating the key. A secure choice is 65537
rng	pointer to an RNG structure to use for random number generation while making the ke

Example

RsaKey priv;
WC_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
}

See also

none

wc_RsaEncryptSize()

int wc_RsaEncryptSize

(

RsaKey *

key

)

Returns the encryption size for the provided key structure.

Returns

Success Encryption size for the provided key structure.

Parameters

key	The key to use for verification.

Example

int sz = wc_RsaEncryptSize(&key);

See also

wc_InitRsaKey

wc_InitRsaKey_ex

wc_MakeRsaKey

XMEMSET

wc_RsaFlattenPublicKey()

int wc_RsaFlattenPublicKey	(	RsaKey *	key,
		byte *	e,
		word32 *	eSz,
		byte *	n,
		word32 *	nSz )

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

key	The key to use for verification.
e	a buffer for the value of e. e is a large positive integer in the RSA modular arithmetic operation.
eSz	the size of the e buffer.
n	a buffer for the value of n. n is a large positive integer in the RSA modular arithmetic operation.
nSz	the size of the n buffer.

Example

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

See also

wc_InitRsaKey

wc_InitRsaKey_ex

wc_MakeRsaKey

XMEMSET

wc_RsaKeyToDer()

WOLFSSL_API int wc_RsaKeyToDer	(	RsaKey *	key,
		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

key	Initialized RsaKey structure.
output	Pointer to output buffer.
inLen	Size of output buffer.

Example

byte* der;
// Allocate memory for der
int derSz = // Amount of memory allocated for der;
RsaKey key;
WC_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
}

See also

wc_RsaKeyToPublicDer

wc_InitRsaKey

wc_MakeRsaKey

wc_InitRng

wc_RsaKeyToPublicDer()

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

key	The RSA key structure to convert.
output	Output buffer to hold DER.
inLen	Length of buffer.

Example

RsaKey key;
 
wc_RsaInitKey(&key, NULL);
// Use key
 
int BUFFER_SIZE = // Some adequate size for the buffer
byte output[BUFFER_SIZE];
if(wc_RsaKeyToPublicDer(&key, output, sizeof(output)) != 0)
{
    // Handle Error
}

See also

wc_RsaKeyToPublicDer

wc_RsaInitKey

wc_RsaPrivateDecrypt()

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

in	The byte array to be decrypted.
inLen	The length of in.
out	The byte array for the decrypted data to be stored.
outLen	The length of out.
key	The key to use for decryption.

Example

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;
}

See also

RsaUnPad

wc_RsaFunction

wc_RsaPrivateDecryptInline

wc_RsaPrivateDecrypt_ex()

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	lableSz )

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

in	pointer to the buffer for decryption
inLen	length of the buffer to decrypt
out	decrypted msg created
outLen	length of buffer available to hold decrypted msg
key	initialized RSA key struct
type	type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
hash	type of hash to use (choices can be found in hash.h)
mgf	type of mask generation function to use
label	an optional label to associate with encrypted message
labelSz	size of the optional label used

Example

WC_WC_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
}

See also

none

wc_RsaPrivateDecryptInline()

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

in	The byte array to be decrypted.
inLen	The length of in.
out	The byte array for the decrypted data to be stored.
key	The key to use for decryption.

Example

none

See also

wc_RsaPrivateDecrypt

wc_RsaPrivateDecryptInline_ex()

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	lableSz )

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

in	pointer to the buffer for decryption
inLen	length of the buffer to decrypt
out	pointer to location of decrypted message in “in” buffer
key	initialized RSA key struct
type	type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
hash	type of hash to use (choices can be found in hash.h)
mgf	type of mask generation function to use
label	an optional label to associate with encrypted message
labelSz	size of the optional label used

Example

WC_WC_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
}

See also

none

wc_RsaPrivateKeyDecode()

WOLFSSL_API int wc_RsaPrivateKeyDecode	(	const byte *	input,
		word32 *	inOutIdx,
		RsaKey *	key,
		word32	inSz )

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

input	pointer to the buffer containing the DER formatted private key to decode
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
key	pointer to the RsaKey structure in which to store the decoded private key
inSz	size of the input buffer

Example

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
}

See also

wc_RsaPublicKeyDecode

wc_MakeRsaKey

wc_RsaPublicEncrypt()

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 the number bytes written to out

-1 Returned if there is an error during RSA encryption and hardware acceleration via Cavium is enabled

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

in	pointer to a buffer containing the input message to encrypt
inLen	the length of the message to encrypt
out	pointer to the buffer in which to store the output ciphertext
outLen	the length of the output buffer
key	pointer to the RsaKey structure containing the public key to use for encryption
rng	The RNG structure with which to generate random block padding

Example

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
}

See also

wc_RsaPrivateDecrypt

wc_RsaPublicEncrypt_ex()

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	lableSz )

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

in	pointer to the buffer for encryption
inLen	length of the buffer to encrypt
out	encrypted msg created
outLen	length of buffer available to hold encrypted msg
key	initialized RSA key struct
rng	initialized WC_RNG struct
type	type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
hash	type of hash to use (choices can be found in hash.h)
mgf	type of mask generation function to use
label	an optional label to associate with encrypted message
labelSz	size of the optional label used

Example

WC_WC_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
}

See also

wc_RsaPublicEncrypt

wc_RsaPrivateDecrypt_ex

wc_RsaPublicKeyDecode()

WOLFSSL_API int wc_RsaPublicKeyDecode	(	const byte *	input,
		word32 *	inOutIdx,
		RsaKey *	key,
		word32	inSz )

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

input	pointer to the buffer containing the input DER-encoded RSA public key to decode
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
key	pointer to the RsaKey structure in which to store the decoded public key
inSz	size of the input buffer

Example

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
}

See also

wc_RsaPublicKeyDecodeRaw

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

n	pointer to a buffer containing the raw modulus parameter of the public RSA key
nSz	size of the buffer containing n
e	pointer to a buffer containing the raw exponent parameter of the public RSA key
eSz	size of the buffer containing e
key	pointer to the RsaKey struct to initialize with the provided public key elements

Example

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
}

See also

wc_RsaPublicKeyDecode

wc_RsaSetNonBlock()

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

key	The RSA key structure
nb	The RSA non-blocking structure for this RSA key to use.

Example

int ret, count = 0;
RsaKey key;
RsaNb  nb;
 
wc_RsaInitKey(&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);

See also

wc_RsaSetNonBlockTime

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

key	The RSA key structure.
maxBlockUs	Maximum time to block microseconds.
cpuMHz	CPU speed in megahertz.

Example

RsaKey key;
RsaNb  nb;
 
wc_RsaInitKey(&key, NULL);
wc_RsaSetNonBlock(key, &nb);
wc_RsaSetNonBlockTime(&key, 4000, 160); // Block Max = 4 ms, CPU = 160MHz

See also

wc_RsaSetNonBlock

wc_RsaSSL_Sign()

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

in	The byte array to be encrypted.
inLen	The length of in.
out	The byte array for the encrypted data to be stored.
outLen	The length of out.
key	The key to use for encryption.
RNG	The RNG struct to use for random number purposes.

Example

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;
}

See also

wc_RsaPad

Set up Montgomery state

Check and reduce input This is needed for calls to MontExp since required value of a < modulus

wc_RsaSSL_Verify()

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

in	The byte array to be decrypted.
inLen	The length of in.
out	The byte array for the decrypted data to be stored.
outLen	The length of out.
key	The key to use for verification.

Example

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;
}

See also

wc_RsaSSL_Sign

wc_RsaSSL_VerifyInline()

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

in	Byte array to be decrypted.
inLen	Length of the buffer input.
out	Pointer to a pointer for decrypted information.
key	RsaKey to use.

Example

RsaKey key;
WC_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
}

See also

wc_RsaSSL_Verify

wc_RsaSSL_Sign

wc_SetKeyUsage()

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

cert	Pointer to initialized Cert structure.
value	Comma delimited string of tokens to set usage.

Example

Cert cert;
wc_InitCert(&cert);
 
if(wc_SetKeyUsage(&cert, "cRLSign,keyCertSign") != 0)
{
    // Handle error
}

See also

wc_InitCert

wc_MakeRsaKey