rsa.h
Functions
Name | |
---|---|
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). |
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). |
int | wc_RsaSetRNG(RsaKey * key, WC_RNG * rng) This function associates RNG with Key. It is needed when WC_RSA_BLINDING is enabled. |
int | wc_FreeRsaKey(RsaKey * key) This function frees a provided RsaKey struct using mp_clear. |
int | wc_RsaDirect(byte * in, word32 inLen, byte * out, word32 * outSz, RsaKey * key, int type, WC_RNG * rng) 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. |
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. |
int | wc_RsaPrivateDecryptInline(byte * in, word32 inLen, byte ** out, RsaKey * key) This functions is utilized by the wc_RsaPrivateDecrypt function for decrypting. |
int | wc_RsaPrivateDecrypt(const byte * in, word32 inLen, byte * out, word32 outLen, RsaKey * key) This functions provides private RSA decryption. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
int | wc_RsaEncryptSize(RsaKey * key) Returns the encryption size for the provided key structure. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
Functions Documentation
function 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).
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
See:
Return:
- 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
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
Example
RsaKey enc;
int ret;
ret = wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
if ( ret != 0 ) {
// error initializing RSA key
}
function wc_InitRsaKey_Id
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).
Parameters:
- key pointer to the RsaKey structure to initialize
- id identifier of key on device
- len length of identifier in bytes
- 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
- devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
See:
Return:
- 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.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
Example
RsaKey enc;
unsigned char* id = (unsigned char*)"RSA2048";
int len = 6;
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
}
function wc_RsaSetRNG
int wc_RsaSetRNG(
RsaKey * key,
WC_RNG * rng
)
This function associates RNG with Key. It is needed when WC_RSA_BLINDING is enabled.
Parameters:
- key pointer to the RsaKey structure to be associated
- rng pointer to the WC_RNG structure to associate with
See:
Return:
- 0 Returned upon success
- BAD_FUNC_ARGS Returned if the RSA key, rng pointer evaluates to NULL
Example
ret = wc_InitRsaKey(&key, NULL);
if (ret == 0) {
ret = wc_InitRng(&rng);
} else return -1;
if (ret == 0) {
ret = wc_RsaSetRNG(&key, &rng);
function wc_FreeRsaKey
int wc_FreeRsaKey(
RsaKey * key
)
This function frees a provided RsaKey struct using mp_clear.
Parameters:
- key pointer to the RsaKey structure to free
See: wc_InitRsaKey
Return: 0 Returned upon successfully freeing the key
Example
RsaKey enc;
wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
... set key, do encryption
wc_FreeRsaKey(&enc);
function wc_RsaDirect
int wc_RsaDirect(
byte * in,
word32 inLen,
byte * out,
word32 * outSz,
RsaKey * key,
int type,
WC_RNG * rng
)
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.
Parameters:
- in buffer to do operation on
- inLen length of input buffer
- out buffer to hold results
- 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.
- key initialized RSA key to use for encrypt/decrypt
- type if using private or public key (RSA_PUBLIC_ENCRYPT, RSA_PUBLIC_DECRYPT, RSA_PRIVATE_ENCRYPT, RSA_PRIVATE_DECRYPT)
- rng initialized WC_RNG struct
See:
Return:
- 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
Example
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
}
function 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.
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
See: wc_RsaPrivateDecrypt
Return:
- 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
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
}
function wc_RsaPrivateDecryptInline
int wc_RsaPrivateDecryptInline(
byte * in,
word32 inLen,
byte ** out,
RsaKey * key
)
This functions is utilized by the wc_RsaPrivateDecrypt function for decrypting.
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.
See: wc_RsaPrivateDecrypt
Return:
- Success Length of decrypted data.
- RSA_PAD_E RsaUnPad error, bad formatting
Example
none
function wc_RsaPrivateDecrypt
int wc_RsaPrivateDecrypt(
const byte * in,
word32 inLen,
byte * out,
word32 outLen,
RsaKey * key
)
This functions provides private RSA decryption.
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.
See:
- RsaUnPad
- wc_RsaFunction
- wc_RsaPrivateDecryptInline
Return:
- Success length of decrypted data.
- MEMORY_E -125, out of memory error
- BAD_FUNC_ARG -173, Bad function argument provided
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;
}
function 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.
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.
See: wc_RsaPad
Return: RSA_BUFFER_E: -131, RSA buffer error, output too small or input too large
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;
}
if (ret != inLen) {
return -1;
}
if (XMEMCMP(in, plain, ret) != 0) {
return -1;
}
function 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.
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.
See:
Return:
-
0 Length of text.
- <0 An error occurred.
Example
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
}
function 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.
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.
See: wc_RsaSSL_Sign
Return:
- Success Length of text on no error.
- MEMORY_E memory exception.
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;
}
if (ret != inLen) {
return -1;
}
if (XMEMCMP(in, plain, ret) != 0) {
return -1;
}
function wc_RsaPSS_Sign
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.
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.
- hash The hash type to be in message
- mgf Mask Generation Function Identifiers
- key The key to use for verification.
See:
Return: RSA_BUFFER_E: -131, RSA buffer error, output too small or input too large
Example
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);
function wc_RsaPSS_Verify
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.
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.
- hash The hash type to be in message
- mgf Mask Generation Function Identifiers
- key The key to use for verification.
See:
Return:
- Success Length of text on no error.
- MEMORY_E memory exception.
- 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)
Example
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);
function wc_RsaPSS_VerifyInline
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.
Parameters:
- in Byte array to be decrypted.
- inLen Length of the buffer input.
- out Pointer to address containing the PSS data.
- hash The hash type to be in message
- mgf Mask Generation Function Identifiers
- key RsaKey to use.
See:
- 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
Return:
-
0 Length of text.
- <0 An error occurred.
Example
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);
function wc_RsaPSS_VerifyCheck
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.
Parameters:
- in The byte array to be decrypted.
- inLen The length of in.
- out Pointer to address containing the PSS data.
- outLen The length of out.
- digest Hash of the data that is being verified.
- digestLen Length of hash.
- hash Hash algorithm.
- mgf Mask generation function.
- key Public RSA key.
See:
- 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
Return:
- the length of the PSS data on success and negative indicates failure.
- MEMORY_E memory exception.
Example
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);
function wc_RsaPSS_VerifyCheck_ex
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.
Parameters:
- in The byte array to be decrypted.
- inLen The length of in.
- out Pointer to address containing the PSS data.
- outLen The length of out.
- digest Hash of the data that is being verified.
- digestLen Length of hash.
- hash Hash algorithm.
- mgf Mask generation function.
- 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.
- key Public RSA key.
See:
- 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
Return:
- the length of the PSS data on success and negative indicates failure.
- MEMORY_E memory exception.
Example
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);
function wc_RsaPSS_VerifyCheckInline
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.
Parameters:
- in The byte array to be decrypted.
- inLen The length of in.
- out The byte array for the decrypted data to be stored.
- digest Hash of the data that is being verified.
- digestLen Length of hash.
- hash The hash type to be in message
- mgf Mask Generation Function Identifiers
- key The key to use for verification.
See:
- 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
Return: the length of the PSS data on success and negative indicates failure.
The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
Example
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);
function wc_RsaPSS_VerifyCheckInline_ex
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.
Parameters:
- in The byte array to be decrypted.
- inLen The length of in.
- out The byte array for the decrypted data to be stored.
- digest Hash of the data that is being verified.
- digestLen Length of hash.
- hash The hash type to be in message
- mgf Mask Generation Function Identifiers
- 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.
- key The key to use for verification.
See:
- 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
Return: the length of the PSS data on success and negative indicates failure.
Example
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);
function wc_RsaPSS_CheckPadding
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.
Parameters:
- in Hash of the data that is being verified.
- inSz Length of hash.
- sig Buffer holding PSS data.
- sigSz Size of PSS data.
- hashType Hash algorithm.
See:
- 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
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.
- MEMORY_E memory exception.
Example
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);
function wc_RsaPSS_CheckPadding_ex
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.
Parameters:
- in Hash of the data that is being verified.
- inSz Length of hash.
- sig Buffer holding PSS data.
- sigSz Size of PSS data.
- hashType Hash algorithm.
- 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.
- bits Can be used to calculate salt size in FIPS case
See:
- 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
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.
- MEMORY_E memory exception.
Example
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);
function wc_RsaEncryptSize
int wc_RsaEncryptSize(
RsaKey * key
)
Returns the encryption size for the provided key structure.
Parameters:
- key The key to use for verification.
See:
- wc_InitRsaKey
- wc_InitRsaKey_ex
- wc_MakeRsaKey
Return: Success Encryption size for the provided key structure.
Example
int sz = wc_RsaEncryptSize(&key);
function wc_RsaPrivateKeyDecode
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.
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
See:
Return:
- 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
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
}
function wc_RsaPublicKeyDecode
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.
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
Return:
- 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
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
}
function wc_RsaPublicKeyDecodeRaw
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.
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
Return:
- 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
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
}
function wc_RsaKeyToDer
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.
Parameters:
- key Initialized RsaKey structure.
- output Pointer to output buffer.
- inLen Size of output buffer.
See:
Return:
-
0 Success, number of bytes written.
- 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.
Example
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
}
function wc_RsaPublicEncrypt_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
)
This function performs RSA encrypt while allowing the choice of which padding to use.
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
See:
Return:
- 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
Example
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
}
function wc_RsaPrivateDecrypt_ex
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.
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
See: none
Return:
- 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.
Example
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
}
function wc_RsaPrivateDecryptInline_ex
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.
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
See: none
Return:
- 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.
Example
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
}
function 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.
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.
See:
- wc_InitRsaKey
- wc_InitRsaKey_ex
- wc_MakeRsaKey
Return:
- 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.
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.
}
function wc_RsaKeyToPublicDer
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.
Parameters:
- key The RSA key structure to convert.
- output Output buffer to hold DER. (if NULL will return length only)
- inLen Length of buffer.
See:
- wc_RsaPublicKeyDerSize
- wc_RsaKeyToPublicDer_ex
- wc_InitRsaKey
Return:
-
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
Example
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
}
function wc_RsaKeyToPublicDer_ex
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.
Parameters:
- key The RSA key structure to convert.
- output Output buffer to hold DER. (if NULL will return length only)
- inLen Length of buffer.
See:
- wc_RsaPublicKeyDerSize
- wc_RsaKeyToPublicDer
- wc_InitRsaKey
Return:
-
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
Example
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
}
function 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.
Parameters:
- key pointer to the RsaKey structure in which to store the generated private key
- size desired key length, 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
See: none
Return:
- 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
Example
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
}
function wc_RsaSetNonBlock
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.
Parameters:
- key The RSA key structure
- nb The RSA non-blocking structure for this RSA key to use.
Return:
- 0 Success
- BAD_FUNC_ARG Returned if key or nb is null.
Example
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);
function wc_RsaSetNonBlockTime
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.
Parameters:
- key The RSA key structure.
- maxBlockUs Maximum time to block microseconds.
- cpuMHz CPU speed in megahertz.
See: wc_RsaSetNonBlock
Return:
- 0 Success
- BAD_FUNC_ARG Returned if key is null or wc_RsaSetNonBlock was not previously called and key->nb is null.
Example
RsaKey key;
RsaNb nb;
wc_InitRsaKey(&key, NULL);
wc_RsaSetNonBlock(key, &nb);
wc_RsaSetNonBlockTime(&key, 4000, 160); // Block Max = 4 ms, CPU = 160MHz
Source code
int wc_InitRsaKey(RsaKey* key, void* heap);
int wc_InitRsaKey_Id(RsaKey* key, unsigned char* id, int len,
void* heap, int devId);
int wc_RsaSetRNG(RsaKey* key, WC_RNG* rng);
int wc_FreeRsaKey(RsaKey* key);
int wc_RsaDirect(byte* in, word32 inLen, byte* out, word32* outSz,
RsaKey* key, int type, WC_RNG* rng);
int wc_RsaPublicEncrypt(const byte* in, word32 inLen, byte* out,
word32 outLen, RsaKey* key, WC_RNG* rng);
int wc_RsaPrivateDecryptInline(byte* in, word32 inLen, byte** out,
RsaKey* key);
int wc_RsaPrivateDecrypt(const byte* in, word32 inLen, byte* out,
word32 outLen, RsaKey* key);
int wc_RsaSSL_Sign(const byte* in, word32 inLen, byte* out,
word32 outLen, RsaKey* key, WC_RNG* rng);
int wc_RsaSSL_VerifyInline(byte* in, word32 inLen, byte** out,
RsaKey* key);
int wc_RsaSSL_Verify(const byte* in, word32 inLen, byte* out,
word32 outLen, RsaKey* key);
int wc_RsaPSS_Sign(const byte* in, word32 inLen, byte* out,
word32 outLen, enum wc_HashType hash, int mgf,
RsaKey* key, WC_RNG* rng);
int wc_RsaPSS_Verify(byte* in, word32 inLen, byte* out,
word32 outLen, enum wc_HashType hash, int mgf,
RsaKey* key);
int wc_RsaPSS_VerifyInline(byte* in, word32 inLen, byte** out,
enum wc_HashType hash, int mgf,
RsaKey* key);
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);
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);
int wc_RsaPSS_VerifyCheckInline(byte* in, word32 inLen, byte** out,
const byte* digest, word32 digentLen,
enum wc_HashType hash, int mgf,
RsaKey* key);
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);
int wc_RsaPSS_CheckPadding(const byte* in, word32 inLen, byte* sig,
word32 sigSz,
enum wc_HashType hashType);
int wc_RsaPSS_CheckPadding_ex(const byte* in, word32 inLen, byte* sig,
word32 sigSz, enum wc_HashType hashType, int saltLen, int bits);
int wc_RsaEncryptSize(RsaKey* key);
int wc_RsaPrivateKeyDecode(const byte* input, word32* inOutIdx,
RsaKey* key, word32 inSz);
int wc_RsaPublicKeyDecode(const byte* input, word32* inOutIdx,
RsaKey* key, word32 inSz);
int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz,
const byte* e, word32 eSz, RsaKey* key);
int wc_RsaKeyToDer(RsaKey* key, byte* output, word32 inLen);
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);
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);
int wc_RsaPrivateDecryptInline_ex(byte* in, word32 inLen,
byte** out, RsaKey* key, int type, enum wc_HashType hash,
int mgf, byte* label, word32 labelSz);
int wc_RsaFlattenPublicKey(RsaKey* key, byte* e, word32* eSz, byte* n,
word32* nSz);
int wc_RsaKeyToPublicDer(RsaKey* key, byte* output, word32 inLen);
int wc_RsaKeyToPublicDer_ex(RsaKey* key, byte* output, word32 inLen,
int with_header);
int wc_MakeRsaKey(RsaKey* key, int size, long e, WC_RNG* rng);
int wc_RsaSetNonBlock(RsaKey* key, RsaNb* nb);
int wc_RsaSetNonBlockTime(RsaKey* key, word32 maxBlockUs,
word32 cpuMHz);
Updated on 2024-11-21 at 01:17:07 +0000