RSA API#

RSA algorithm is a public-key cryptosystem. In a public-key cryptosystem, the encryption key is public and decryption key is private. RSA algorithm involves key generation, encryption / decryption and signature.


Data Structures#

struct alc_rsa_handle_t#

Handle for maintaining session.

Param context:

pointer to the context of the RSA


Functions#

Int32 alcp_rsa_get_digest_info_index(alc_digest_mode_t mode)#

Returns the digest info index.

Parameters:

mode – [in] - digest mode

Returns:

index in DigestInfo array

Int32 alcp_rsa_get_digest_info_size(alc_digest_mode_t mode)#

Returns the digest info size.

Parameters:

mode – [in] - digest mode

Returns:

size of entry in DigestInfo array

Uint64 alcp_rsa_context_size(void)#

Returns the context size of the interaction.

This API can be called after alcp_rsa_request only otherwise Context will be empty

Returns:

Size of Context

alc_error_t alcp_rsa_request(alc_rsa_handle_p pRsaHandle)#

Request a handle for rsa for a configuration.

Note

Only 1024 and 2048 key size supported

Parameters:

pRsaHandle – [out] - Library populated session handle for future rsa operations.

Returns:

Error Code for the API called. If alc_error_t is not ALC_ERROR_NONE, an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_add_digest(const alc_rsa_handle_p pRsaHandle, alc_digest_mode_t mode)#

Function adds the digest algorithm to be used in oaep / pss / pkcsv15 padding.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • mode – [in] - Description of the digest

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_add_mgf(const alc_rsa_handle_p pRsaHandle, alc_digest_mode_t mode)#

Function adds the digest algorithm for mask generation in oaep / pkcsv15 padding.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • mode – [in] - Description of the digest

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_publickey_encrypt(const alc_rsa_handle_p pRsaHandle, const Uint8 *pText, Uint64 textSize, Uint8 *pEncText)#

Function encrypts text using using public key.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Note

This API has following limitations

  • textSize should equal to the modulus/private_key size

  • pText absolute value should be less than modulus

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • pText – [in] - pointer to raw bytes

  • textSize – [in] - size of raw bytes

  • pEncText – [out] - pointer to encrypted bytes bytes

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_publickey_encrypt_oaep(const alc_rsa_handle_p pRsaHandle, const Uint8 *pText, Uint64 textSize, const Uint8 *label, Uint64 labelSize, const Uint8 *pSeed, Uint8 *pEncText)#

Function encrypts text using using public key and oaep padding.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • pText – [in] - pointer to raw bytes

  • textSize – [in] - size of raw bytes

  • label – [in] - pointer to label

  • labelSize – [in] - size of label

  • pSeed – [in] - random seed of size hashlen

  • pEncText – [out] - pointer to encrypted bytes bytes

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_privatekey_decrypt(const alc_rsa_handle_p pRsaHandle, alc_rsa_padding pad, const Uint8 *pEncText, Uint64 encSize, Uint8 *pText)#

Function decrypts encrypted text using private key.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Note

This API has following limitations

  • textSize should equal to the modulus/private_key size

  • pText absolute value should be less than modulus

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • pad – [in] - padding scheme to be used for rsa decrytion

  • pEncText – [in] - pointer to encrypted bytes

  • encSize – [in] - pointer to encrypted bytes

  • pText – [out] - pointer to decrypted bytes

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_privatekey_decrypt_oaep(const alc_rsa_handle_p pRsaHandle, const Uint8 *pEncText, Uint64 encSize, const Uint8 *label, Uint64 labelSize, Uint8 *pText, Uint64 *textSize)#

Function decrypts encrypted text using private key and OAEP padding.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • pEncText – [in] - pointer to encrypted bytes

  • encSize – [in] - size of encrypted bytes

  • label – [in] - pointer to label

  • labelSize – [in] - sizeof label

  • pText – [out] - pointer to decrypted text

  • textSize – [out] - pointer to size of decrypted text

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_privatekey_sign_pss(const alc_rsa_handle_p pRsaHandle, bool check, const Uint8 *pText, Uint64 textSize, const Uint8 *pSalt, Uint64 saltSize, Uint8 *pSignedBuff)#

Function signs text using private key and PSS padding.

This API can be called after alcp_rsa_request and the before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • check – [in] - Verify the signed message to prevent fault attack

  • pText – [in] - pointer to input text

  • textSize – [in] - size of input text

  • pSalt – [in] - pointer to salt

  • saltSize – [in] - size of salt

  • pSignedBuff – [out] - pointer to signed text

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_publickey_verify_pss(const alc_rsa_handle_p pRsaHandle, const Uint8 *pText, Uint64 textSize, const Uint8 *pSignedBuff)#

Function verifies text using public key and PSS padding.

This API can be called after alcp_rsa_request and the before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • pText – [in] - pointer to input text

  • textSize – [in] - size of input text

  • pSignedBuff – [in] - pointer to signed text

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_privatekey_sign_pkcs1v15(const alc_rsa_handle_p pRsaHandle, bool check, const Uint8 *pText, Uint64 textSize, Uint8 *pSignedBuff)#

Function signs text using private key and PKCS1-v1_5 padding.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • check – [in] - Verify the signed message to prevent fault attack

  • pText – [in] - pointer to input text

  • textSize – [in] - size of input text

  • pSignedBuff – [out] - pointer to signed text

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_publickey_verify_pkcs1v15(const alc_rsa_handle_p pRsaHandle, const Uint8 *pText, Uint64 textSize, const Uint8 *pSignedBuff)#

Function verifies text using public key and PKCS1-v1_5 padding.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • pText – [in] - pointer to input text

  • textSize – [in] - size of input text

  • pSignedBuff – [in] - pointer to signed text

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_privatekey_sign_hash_pkcs1v15(const alc_rsa_handle_p pRsaHandle, const Uint8 *pText, Uint64 textSize, Uint8 *pSignedText)#

Function signs hash using private key and PKCS1-v1_5 padding.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • pText – [in] - pointer to input hash

  • textSize – [in] - size of input hash

  • pSignedText – [out] - pointer to signed text

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_publickey_verify_hash_pkcs1v15(const alc_rsa_handle_p pRsaHandle, const Uint8 *pText, Uint64 textSize, const Uint8 *pSignedBuff)#

Function verifies hash using public key and PKCS1-v1_5 padding.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • pText – [in] - pointer to input hash

  • textSize – [in] - size of input hash

  • pSignedBuff – [in] - pointer to signed text

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_publickey_encrypt_pkcs1v15(const alc_rsa_handle_p pRsaHandle, const Uint8 *pText, Uint64 textSize, Uint8 *pEncryptText, const Uint8 *randomPad)#

Function encrypts text using using public key and pkcs padding.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • pText – [in] - pointer to raw bytes

  • textSize – [in] - size of raw bytes

  • pEncryptText – [out] - pointer to encrypted bytes

  • randomPad – [in] - random pad

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_privatekey_decrypt_pkcs1v15(const alc_rsa_handle_p pRsaHandle, const Uint8 *pText, Uint8 *pDecryptText, Uint64 *textSize)#

Function decrypts encrypted text using private key and pkcs padding.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • pText – [in] - pointer to encrypted bytes

  • pDecryptText – [out] - pointer to decrypted text

  • textSize – [out] - pointer to size of decrypted text

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_privatekey_sign_hash_pss(const alc_rsa_handle_p pRsaHandle, const Uint8 *pHash, Uint64 hashSize, const Uint8 *pSalt, Uint64 saltSize, Uint8 *pSignedBuff)#

Function signs hash using private key and PSS padding.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • pHash – [in] - pointer to input hash

  • hashSize – [in] - size of hash

  • pSalt – [in] - pointer to salt

  • saltSize – [in] - size of salt

  • pSignedBuff – [out] - pointer to signed text

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_publickey_verify_hash_pss(const alc_rsa_handle_p pRsaHandle, const Uint8 *pHash, Uint64 hashSize, const Uint8 *pSignedBuff)#

Function verifies hash using public key and PSS padding.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • pHash – [in] - pointer to input hash

  • hashSize – [in] - size of input hash

  • pSignedBuff – [in] - pointer to signed text

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_set_publickey(const alc_rsa_handle_p pRsaHandle, Uint64 exponent, const Uint8 *pModulus, Uint64 size)#

Function sets the public key inside the handle.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • exponent – [in] - public key exponent

  • pModulus – [in] - pointer to modulus

  • size – [in] - size of modulus

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_set_bignum_public_key(const alc_rsa_handle_p pRsaHandle, const BigNum *exponent, const BigNum *pModulus)#

Function sets the public key in big num format inside the handle.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - Handler of the Context for the session

  • exponent – [in] - BigNum pointer to public key exponent

  • pModulus – [in] - BigNum pointer to modulus

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_set_bignum_private_key(const alc_rsa_handle_p pRsaHandle, const BigNum *dp, const BigNum *dq, const BigNum *p, const BigNum *q, const BigNum *qinv, const BigNum *mod)#

Function sets the private key inside the handle.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - handler of the Context for the session

  • dp – [in] - pointer to BigNum first exponent

  • dq – [in] - pointer to BigNum second exponent

  • p – [in] - pointer to BigNum first modulus

  • q – [in] - pointer to BigNum second modulus

  • qinv – [in] - pointer to BigNum inverse of second modulus

  • mod – [in] - pointer to BigNum mult of first and second modulus

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

alc_error_t alcp_rsa_set_privatekey(const alc_rsa_handle_p pRsaHandle, const Uint8 *dp, const Uint8 *dq, const Uint8 *p, const Uint8 *q, const Uint8 *qinv, const Uint8 *mod, Uint64 size)#

Function sets the private key inside the handle.

This API can be called after alcp_rsa_request and before alcp_rsa_finish

Parameters:
  • pRsaHandle – [in] - handler of the Context for the session

  • dp – [in] - pointer to first exponent

  • dq – [in] - pointer to second exponent

  • p – [in] - pointer to first modulus

  • q – [in] - pointer to second modulus

  • qinv – [in] - pointer to inverse of second modulus

  • mod – [in] - pointer to mult of first and second modulus

  • size – [in] - size of modulus

Returns:

Error Code for the API called . if alc_error_t is not zero then an error has occurred and handle will be invalid for future operations

Uint64 alcp_rsa_get_key_size(const alc_rsa_handle_p pRsaHandle)#

Fetches key size.

This API is called fetch the key size session

Parameters:

pRsaHandle – [in] - Handler of the Context for the session

Returns:

modulus/private_key size

alc_error_t alcp_rsa_context_copy(const alc_rsa_handle_p pSrcHandle, const alc_rsa_handle_p pDestHandle)#

copies a handle for rsa from pSrcHandle to pDestHandle

Note

Only 1024 and 2048 key size supported

Parameters:
  • pSrcHandle – [in] - Input source handle.

  • pDestHandle – [out] - Output source handle.

Returns:

Error Code for the API called. If alc_error_t is not ALC_ERROR_NONE, an error has occurred and handle will be invalid for future operations

void alcp_rsa_finish(const alc_rsa_handle_p pRsaHandle)#

Performs any cleanup actions. Once this function is called, the handle will not be valid for future calls.

This API is called to free resources so should be called to free the session

Note

Must be called to ensure memory allotted (if any) is cleaned.

Parameters:

pRsaHandle – [in] The handle used with alcp_rsa_request()

Returns:

None


Variables#

enum [anonymous] alc_rsa_padding#

Store info about padding used for encryption / decryption.

enum [anonymous] alc_rsa_key_size#

Store info about supported RSA key sizes.

void alc_rsa_context_t#

Store Context for the future operation of RSA.