mbed TLS v2.23.0: Asymmetric cryptography

mbed TLS v2.23.0

Functions
Asymmetric cryptography

## Functions
psa_status_t | psa_sign_hash (psa_key_handle_t handle, 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. More...
psa_status_t | psa_verify_hash (psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length)
| Verify the signature a hash or short message using a public key. More...
psa_status_t | psa_asymmetric_encrypt (psa_key_handle_t handle, 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. More...
psa_status_t | psa_asymmetric_decrypt (psa_key_handle_t handle, 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. More...

## Detailed Description

## Function Documentation

## ◆ psa_asymmetric_decrypt()

psa_status_t psa_asymmetric_decrypt | ( | psa_key_handle_t | handle,
|  | 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

  | handle | Handle to the key to use for the operation. It must be an asymmetric key pair.
  | alg | An asymmetric encryption algorithm that is compatible with the type of `handle`.
  [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 `handle`.
    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 | ( | psa_key_handle_t | handle,
|  | 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

  | handle | Handle to the key to use for the operation. It must be a public key or an asymmetric key pair.
  | alg | An asymmetric encryption algorithm that is compatible with the type of `handle`.
  [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 `handle`.
    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 | ( | psa_key_handle_t | handle,
|  | 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(). 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

  | handle | Handle to the key to use for the operation. It must be an asymmetric key pair.
  | alg | A signature algorithm that is compatible with the type of `handle`.
  [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 `handle`.
  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.

Referenced by psa_asymmetric_sign().

## ◆ psa_verify_hash()

psa_status_t psa_verify_hash | ( | psa_key_handle_t | handle,
|  | psa_algorithm_t | alg,
|  | const uint8_t * | hash,
|  | size_t | hash_length,
|  | const uint8_t * | signature,
|  | size_t | signature_length
| ) |  |

Verify the signature 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(). 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

  | handle | Handle to the key to use for the operation. It must be a public key or an asymmetric key pair.
  | alg | A signature algorithm that is compatible with the type of `handle`.
  [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 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_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.

Referenced by psa_asymmetric_verify().