Loading...
Searching...
No Matches
Asymmetric cryptography

## 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. For hash-and-sign algorithms, this includes the hashing step.
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.

## Detailed Description

## Function Documentation

## 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

  | 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`.
  [in] | input | The message to decrypt.
  | input_length | Size of the `input` buffer in bytes.
  [in] | 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.
  Parameters

    | salt_length | Size of the `salt` buffer in bytes. If `salt` is `NULL`, pass 0.
    [out] | output | Buffer where the decrypted message is to be written.
    | output_size | Size of the `output` buffer in bytes.
    [out] | output_length | On 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_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.

## 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

  | 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`.
  [in] | input | The message to encrypt.
  | input_length | Size of the `input` buffer in bytes.
  [in] | 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.
  Parameters

    | salt_length | Size of the `salt` buffer in bytes. If `salt` is `NULL`, pass 0.
    [out] | output | Buffer where the encrypted message is to be written.
    | output_size | Size of the `output` buffer in bytes.
    [out] | output_length | On 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_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_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

  | 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`.
  [in] | hash | The hash or message to sign.
  | hash_length | Size of the `hash` buffer in bytes.
  [out] | signature | Buffer where the signature is to be written.
  | signature_size | Size of the `signature` buffer in bytes.
  [out] | signature_length | On 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_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_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] | 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.
  [in] | 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`.
  [in] | input | The input message to sign.
  [in] | input_length | Size of the `input` buffer in bytes.
  [out] | signature | Buffer where the signature is to be written.

  [in]

  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.

  [out] | signature_length | On success, the number of bytes that make up the returned signature value.

Return values

  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_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

  | 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`.
  [in] | hash | The hash or message whose signature is to be verified.
  | hash_length | Size of the `hash` buffer in bytes.
  [in] | signature | Buffer containing the signature to verify.
  | signature_length | Size of the `signature` buffer in bytes.

Return values

  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_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] | 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.
  [in] | 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`.
  [in] | input | The message whose signature is to be verified.
  [in] | input_length | Size of the `input` buffer in bytes.
  [in] | signature | Buffer containing the signature to verify.
  [in] | signature_length | Size of the `signature` buffer in bytes.

Return values

  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.