Asymmetric cryptography

Description

Functions

psa_status_t psa_sign_message (mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *signature, size_t signature_size, size_t *signature_length)
 Sign a message with a private key.
 
psa_status_t psa_verify_message (mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length)
 Verify the signature of a message with a public key, using a hash-and-sign verification algorithm.
 
psa_status_t psa_sign_hash (mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, uint8_t *signature, size_t signature_size, size_t *signature_length)
 Sign a hash or short message with a private key.
 
psa_status_t psa_verify_hash (mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length)
 Verify the signature of a hash or short message using a public key.
 
psa_status_t psa_asymmetric_encrypt (mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length)
 Encrypt a short message with a public key.
 
psa_status_t psa_asymmetric_decrypt (mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length)
 Decrypt a short message with a private key.
 

Function Documentation

◆ psa_sign_message()

psa_status_t psa_sign_message ( mbedtls_svc_key_id_t  key,
psa_algorithm_t  alg,
const uint8_t *  input,
size_t  input_length,
uint8_t *  signature,
size_t  signature_size,
size_t *  signature_length 
)

Sign a message with a private key.

For hash-and-sign algorithms, this includes the hashing step.

Note
To perform a multi-part hash-and-sign signature algorithm, first use a multi-part hash operation and then pass the resulting hash to psa_sign_hash(). PSA_ALG_GET_HASH(alg) can be used to determine the hash algorithm to use.
Parameters
[in]keyIdentifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE.
[in]algAn asymmetric signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_MESSAGE(alg) is true), that is compatible with the type of key.
[in]inputThe input message to sign.
[in]input_lengthSize of the input buffer in bytes.
[out]signatureBuffer where the signature is to be written.
[in]signature_sizeSize of the signature buffer in bytes. This must be appropriate for the selected algorithm and key:
  • The required signature size is #PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
  • #PSA_SIGNATURE_MAX_SIZE evaluates to the maximum signature size of any supported signature algorithm.
[out]signature_lengthOn success, the number of bytes that make up the returned signature value.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_PERMITTEDThe key does not have the PSA_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.
PSA_ERROR_BUFFER_TOO_SMALLThe size of the signature buffer is too small. You can determine a sufficient buffer size by calling #PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
PSA_ERROR_INSUFFICIENT_ENTROPY
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_verify_message()

psa_status_t psa_verify_message ( mbedtls_svc_key_id_t  key,
psa_algorithm_t  alg,
const uint8_t *  input,
size_t  input_length,
const uint8_t *  signature,
size_t  signature_length 
)

Verify the signature of a message with a public key, using a hash-and-sign verification algorithm.

Note
To perform a multi-part hash-and-sign signature verification algorithm, first use a multi-part hash operation to hash the message and then pass the resulting hash to psa_verify_hash(). PSA_ALG_GET_HASH(alg) can be used to determine the hash algorithm to use.
Parameters
[in]keyIdentifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_VERIFY_MESSAGE.
[in]algAn asymmetric signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_MESSAGE(alg) is true), that is compatible with the type of key.
[in]inputThe message whose signature is to be verified.
[in]input_lengthSize of the input buffer in bytes.
[out]signatureBuffer containing the signature to verify.
[in]signature_lengthSize of the signature buffer in bytes.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_PERMITTEDThe key does not have the PSA_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.
PSA_ERROR_INVALID_SIGNATUREThe calculation was performed successfully, but the passed signature is not a valid signature.
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_sign_hash()

psa_status_t psa_sign_hash ( mbedtls_svc_key_id_t  key,
psa_algorithm_t  alg,
const uint8_t *  hash,
size_t  hash_length,
uint8_t *  signature,
size_t  signature_size,
size_t *  signature_length 
)

Sign a hash or short message with a private key.

Note that to perform a hash-and-sign signature algorithm, you must first calculate the hash by calling psa_hash_setup(), psa_hash_update() and psa_hash_finish(), or alternatively by calling psa_hash_compute(). Then pass the resulting hash as the hash parameter to this function. You can use PSA_ALG_SIGN_GET_HASH(alg) to determine the hash algorithm to use.

Parameters
keyIdentifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_SIGN_HASH.
algA signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_HASH(alg) is true), that is compatible with the type of key.
[in]hashThe hash or message to sign.
hash_lengthSize of the hash buffer in bytes.
[out]signatureBuffer where the signature is to be written.
signature_sizeSize of the signature buffer in bytes.
[out]signature_lengthOn success, the number of bytes that make up the returned signature value.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_BUFFER_TOO_SMALLThe size of the signature buffer is too small. You can determine a sufficient buffer size by calling #PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_INSUFFICIENT_ENTROPY
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_verify_hash()

psa_status_t psa_verify_hash ( mbedtls_svc_key_id_t  key,
psa_algorithm_t  alg,
const uint8_t *  hash,
size_t  hash_length,
const uint8_t *  signature,
size_t  signature_length 
)

Verify the signature of a hash or short message using a public key.

Note that to perform a hash-and-sign signature algorithm, you must first calculate the hash by calling psa_hash_setup(), psa_hash_update() and psa_hash_finish(), or alternatively by calling psa_hash_compute(). Then pass the resulting hash as the hash parameter to this function. You can use PSA_ALG_SIGN_GET_HASH(alg) to determine the hash algorithm to use.

Parameters
keyIdentifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_VERIFY_HASH.
algA signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_HASH(alg) is true), that is compatible with the type of key.
[in]hashThe hash or message whose signature is to be verified.
hash_lengthSize of the hash buffer in bytes.
[in]signatureBuffer containing the signature to verify.
signature_lengthSize of the signature buffer in bytes.
Return values
PSA_SUCCESSThe signature is valid.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_SIGNATUREThe calculation was perfomed successfully, but the passed signature is not a valid signature.
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_asymmetric_encrypt()

psa_status_t psa_asymmetric_encrypt ( mbedtls_svc_key_id_t  key,
psa_algorithm_t  alg,
const uint8_t *  input,
size_t  input_length,
const uint8_t *  salt,
size_t  salt_length,
uint8_t *  output,
size_t  output_size,
size_t *  output_length 
)

Encrypt a short message with a public key.

Parameters
keyIdentifer of the key to use for the operation. It must be a public key or an asymmetric key pair. It must allow the usage PSA_KEY_USAGE_ENCRYPT.
algAn asymmetric encryption algorithm that is compatible with the type of key.
[in]inputThe message to encrypt.
input_lengthSize of the input buffer in bytes.
[in]saltA salt or label, if supported by the encryption algorithm. If the algorithm does not support a salt, pass NULL. If the algorithm supports an optional salt and you do not want to pass a salt, pass NULL.
  • For PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.
    Parameters
    salt_lengthSize of the salt buffer in bytes. If salt is NULL, pass 0.
    [out]outputBuffer where the encrypted message is to be written.
    output_sizeSize of the output buffer in bytes.
    [out]output_lengthOn success, the number of bytes that make up the returned output.
    Return values
    PSA_SUCCESS
    PSA_ERROR_INVALID_HANDLE
    PSA_ERROR_NOT_PERMITTED
    PSA_ERROR_BUFFER_TOO_SMALLThe size of the output buffer is too small. You can determine a sufficient buffer size by calling #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
    PSA_ERROR_NOT_SUPPORTED
    PSA_ERROR_INVALID_ARGUMENT
    PSA_ERROR_INSUFFICIENT_MEMORY
    PSA_ERROR_COMMUNICATION_FAILURE
    PSA_ERROR_HARDWARE_FAILURE
    PSA_ERROR_CORRUPTION_DETECTED
    PSA_ERROR_STORAGE_FAILURE
    PSA_ERROR_INSUFFICIENT_ENTROPY
    PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_asymmetric_decrypt()

psa_status_t psa_asymmetric_decrypt ( mbedtls_svc_key_id_t  key,
psa_algorithm_t  alg,
const uint8_t *  input,
size_t  input_length,
const uint8_t *  salt,
size_t  salt_length,
uint8_t *  output,
size_t  output_size,
size_t *  output_length 
)

Decrypt a short message with a private key.

Parameters
keyIdentifier of the key to use for the operation. It must be an asymmetric key pair. It must allow the usage PSA_KEY_USAGE_DECRYPT.
algAn asymmetric encryption algorithm that is compatible with the type of key.
[in]inputThe message to decrypt.
input_lengthSize of the input buffer in bytes.
[in]saltA salt or label, if supported by the encryption algorithm. If the algorithm does not support a salt, pass NULL. If the algorithm supports an optional salt and you do not want to pass a salt, pass NULL.
  • For PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.
    Parameters
    salt_lengthSize of the salt buffer in bytes. If salt is NULL, pass 0.
    [out]outputBuffer where the decrypted message is to be written.
    output_sizeSize of the output buffer in bytes.
    [out]output_lengthOn success, the number of bytes that make up the returned output.
    Return values
    PSA_SUCCESS
    PSA_ERROR_INVALID_HANDLE
    PSA_ERROR_NOT_PERMITTED
    PSA_ERROR_BUFFER_TOO_SMALLThe size of the output buffer is too small. You can determine a sufficient buffer size by calling #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
    PSA_ERROR_NOT_SUPPORTED
    PSA_ERROR_INVALID_ARGUMENT
    PSA_ERROR_INSUFFICIENT_MEMORY
    PSA_ERROR_COMMUNICATION_FAILURE
    PSA_ERROR_HARDWARE_FAILURE
    PSA_ERROR_CORRUPTION_DETECTED
    PSA_ERROR_STORAGE_FAILURE
    PSA_ERROR_INSUFFICIENT_ENTROPY
    PSA_ERROR_INVALID_PADDING
    PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.