asymmetric

# Asymmetric cryptography

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

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_SIGN_GET_HASH(`alg`) can be used to determine the hash algorithm to use.

key

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

alg

An 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`.

input

The input message to sign.

input_length

Size of the `input` buffer in bytes.

signature

Buffer where the signature is to be written.

signature_size

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

signature_length

On success, the number of bytes that make up the returned signature value.

PSA_SUCCESS

PSA_ERROR_INVALID_HANDLE

PSA_ERROR_NOT_PERMITTED

The key does not have the PSA_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.

PSA_ERROR_BUFFER_TOO_SMALL

The 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_STATE

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

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_SIGN_GET_HASH(`alg`) can be used to determine the hash algorithm to use.

key

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

alg

An 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`.

input

The message whose signature is to be verified.

input_length

Size of the `input` buffer in bytes.

signature

Buffer containing the signature to verify.

signature_length

Size of the `signature` buffer in bytes.

PSA_SUCCESS

PSA_ERROR_INVALID_HANDLE

PSA_ERROR_NOT_PERMITTED

The key does not have the PSA_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.

PSA_ERROR_INVALID_SIGNATURE

The 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_STATE

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

key

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

alg

A signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_HASH(`alg`) is true), that is compatible with the type of `key`.

hash

The hash or message to sign.

hash_length

Size of the `hash` buffer in bytes.

signature

Buffer where the signature is to be written.

signature_size

Size of the `signature` buffer in bytes.

signature_length

On success, the number of bytes that make up the returned signature value.

PSA_SUCCESS

PSA_ERROR_INVALID_HANDLE

PSA_ERROR_NOT_PERMITTED

PSA_ERROR_BUFFER_TOO_SMALL

The 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_STATE

The 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_sign
psa_status_t 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) 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.

key

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

alg

A signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_HASH(`alg`) is true), that is compatible with the type of `key`.

hash

The hash or message whose signature is to be verified.

hash_length

Size of the `hash` buffer in bytes.

signature

Buffer containing the signature to verify.

signature_length

Size of the `signature` buffer in bytes.

PSA_SUCCESS

The signature is valid.

PSA_ERROR_INVALID_HANDLE

PSA_ERROR_NOT_PERMITTED

PSA_ERROR_INVALID_SIGNATURE

The 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_BAD_STATE

The 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_verify
psa_status_t 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) 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.

key

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

alg

An asymmetric encryption algorithm that is compatible with the type of `key`.

input

The message to encrypt.

input_length

Size of the `input` buffer in bytes.

salt

A 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. salt_length

  Size of the `salt` buffer in bytes. If `salt` is `NULL`, pass 0.

  output

  Buffer where the encrypted message is to be written.

  output_size

  Size of the `output` buffer in bytes.

  output_length

  On success, the number of bytes that make up the returned output.

  PSA_SUCCESS

  PSA_ERROR_INVALID_HANDLE

  PSA_ERROR_NOT_PERMITTED

  PSA_ERROR_BUFFER_TOO_SMALL

  The 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_STATE

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

key

Identifier of the key to use for the operation. It must be an asymmetric key pair. It must allow the usage PSA_KEY_USAGE_DECRYPT.

alg

An asymmetric encryption algorithm that is compatible with the type of `key`.

input

The message to decrypt.

input_length

Size of the `input` buffer in bytes.

salt

A 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. salt_length

  Size of the `salt` buffer in bytes. If `salt` is `NULL`, pass 0.

  output

  Buffer where the decrypted message is to be written.

  output_size

  Size of the `output` buffer in bytes.

  output_length

  On success, the number of bytes that make up the returned output.

  PSA_SUCCESS

  PSA_ERROR_INVALID_HANDLE

  PSA_ERROR_NOT_PERMITTED

  PSA_ERROR_BUFFER_TOO_SMALL

  The 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_STATE

  The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.