|
Platform Security Architecture — cryptography and keystore interface
beta 2 — 2019-02-22
|
Macros | |
| #define | PSA_KDF_STEP_SECRET ((psa_key_derivation_step_t)0x0101) |
| #define | PSA_KDF_STEP_LABEL ((psa_key_derivation_step_t)0x0201) |
| #define | PSA_KDF_STEP_SALT ((psa_key_derivation_step_t)0x0202) |
| #define | PSA_KDF_STEP_INFO ((psa_key_derivation_step_t)0x0203) |
Typedefs | |
| typedef uint16_t | psa_key_derivation_step_t |
| Encoding of the step of a key derivation. | |
Functions | |
| psa_status_t | psa_key_derivation_setup (psa_crypto_generator_t *generator, psa_algorithm_t alg) |
| psa_status_t | psa_key_derivation_input_bytes (psa_crypto_generator_t *generator, psa_key_derivation_step_t step, const uint8_t *data, size_t data_length) |
| psa_status_t | psa_key_derivation_input_key (psa_crypto_generator_t *generator, psa_key_derivation_step_t step, psa_key_handle_t handle) |
| psa_status_t | psa_key_agreement (psa_crypto_generator_t *generator, psa_key_derivation_step_t step, psa_key_handle_t private_key, const uint8_t *peer_key, size_t peer_key_length) |
| psa_status_t | psa_key_agreement_raw_shared_secret (psa_algorithm_t alg, psa_key_handle_t private_key, const uint8_t *peer_key, size_t peer_key_length, uint8_t *output, size_t output_size, size_t *output_length) |
| #define PSA_KDF_STEP_INFO ((psa_key_derivation_step_t)0x0203) |
An information string for key derivation.
This must be a direct input.
| #define PSA_KDF_STEP_LABEL ((psa_key_derivation_step_t)0x0201) |
A label for key derivation.
This must be a direct input.
| #define PSA_KDF_STEP_SALT ((psa_key_derivation_step_t)0x0202) |
A salt for key derivation.
This must be a direct input.
| #define PSA_KDF_STEP_SECRET ((psa_key_derivation_step_t)0x0101) |
A secret input for key derivation.
This must be a key of type PSA_KEY_TYPE_DERIVE.
| psa_status_t psa_key_agreement | ( | psa_crypto_generator_t * | generator, |
| psa_key_derivation_step_t | step, | ||
| psa_key_handle_t | private_key, | ||
| const uint8_t * | peer_key, | ||
| size_t | peer_key_length | ||
| ) |
Perform a key agreement and use the shared secret as input to a key derivation.
A key agreement algorithm takes two inputs: a private key private_key a public key peer_key. The result of this function is passed as input to a key derivation. The output of this key derivation can be extracted by reading from the resulting generator to produce keys and other cryptographic material.
| [in,out] | generator | The generator object to use. It must have been set up with psa_key_derivation_setup() with a key agreement and derivation algorithm alg (PSA_ALG_XXX value such that PSA_ALG_IS_KEY_AGREEMENT(alg) is true and PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) is false). The generator must be ready for an input of the type given by step. |
| step | Which step the input data is for. | |
| private_key | Handle to the private key to use. | |
| [in] | peer_key | Public key of the peer. The peer key must be in the same format that psa_import_key() accepts for the public key type corresponding to the type of private_key. That is, this function performs the equivalent of psa_import_key(internal_public_key_handle, PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(private_key_type), peer_key, peer_key_length) where private_key_type is the type of private_key. For example, for EC keys, this means that peer_key is interpreted as a point on the curve that the private key is on. The standard formats for public keys are documented in the documentation of psa_export_public_key(). |
| peer_key_length | Size of peer_key in bytes. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_INVALID_HANDLE | |
| PSA_ERROR_EMPTY_SLOT | |
| PSA_ERROR_NOT_PERMITTED | |
| PSA_ERROR_INVALID_ARGUMENT | private_key is not compatible with alg, or peer_key is not valid for alg or not compatible with private_key. |
| PSA_ERROR_NOT_SUPPORTED | alg is not supported or is not a key derivation algorithm. |
| PSA_ERROR_INSUFFICIENT_MEMORY | |
| PSA_ERROR_COMMUNICATION_FAILURE | |
| PSA_ERROR_HARDWARE_FAILURE | |
| PSA_ERROR_TAMPERING_DETECTED |
| psa_status_t psa_key_agreement_raw_shared_secret | ( | psa_algorithm_t | alg, |
| psa_key_handle_t | private_key, | ||
| const uint8_t * | peer_key, | ||
| size_t | peer_key_length, | ||
| uint8_t * | output, | ||
| size_t | output_size, | ||
| size_t * | output_length | ||
| ) |
Perform a key agreement and use the shared secret as input to a key derivation.
A key agreement algorithm takes two inputs: a private key private_key a public key peer_key.
| alg | The key agreement algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) is true). | |
| private_key | Handle to the private key to use. | |
| [in] | peer_key | Public key of the peer. It must be in the same format that psa_import_key() accepts. The standard formats for public keys are documented in the documentation of psa_export_public_key(). |
| peer_key_length | Size of peer_key in bytes. | |
| [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. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_INVALID_HANDLE | |
| PSA_ERROR_EMPTY_SLOT | |
| PSA_ERROR_NOT_PERMITTED | |
| PSA_ERROR_INVALID_ARGUMENT | alg is not a key agreement algorithm |
| PSA_ERROR_INVALID_ARGUMENT | private_key is not compatible with alg, or peer_key is not valid for alg or not compatible with private_key. |
| PSA_ERROR_NOT_SUPPORTED | alg is not a supported key agreement algorithm. |
| PSA_ERROR_INSUFFICIENT_MEMORY | |
| PSA_ERROR_COMMUNICATION_FAILURE | |
| PSA_ERROR_HARDWARE_FAILURE | |
| PSA_ERROR_TAMPERING_DETECTED |
| psa_status_t psa_key_derivation_input_bytes | ( | psa_crypto_generator_t * | generator, |
| psa_key_derivation_step_t | step, | ||
| const uint8_t * | data, | ||
| size_t | data_length | ||
| ) |
Provide an input for key derivation or key agreement.
Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information.
This function passes direct inputs. Some inputs must be passed as keys using psa_key_derivation_input_key() instead of this function. Refer to the documentation of individual step types for information.
| [in,out] | generator | The generator object to use. It must have been set up with psa_key_derivation_setup() and must not have produced any output yet. |
| step | Which step the input data is for. | |
| [in] | data | Input data to use. |
| data_length | Size of the data buffer in bytes. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_INVALID_ARGUMENT | step is not compatible with the generator's algorithm. |
| PSA_ERROR_INVALID_ARGUMENT | step does not allow direct inputs. |
| PSA_ERROR_INSUFFICIENT_MEMORY | |
| PSA_ERROR_COMMUNICATION_FAILURE | |
| PSA_ERROR_HARDWARE_FAILURE | |
| PSA_ERROR_TAMPERING_DETECTED | |
| PSA_ERROR_BAD_STATE | The value of step is not valid given the state of generator. |
| 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_key_derivation_input_key | ( | psa_crypto_generator_t * | generator, |
| psa_key_derivation_step_t | step, | ||
| psa_key_handle_t | handle | ||
| ) |
Provide an input for key derivation in the form of a key.
Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information.
This function passes key inputs. Some inputs must be passed as keys of the appropriate type using this function, while others must be passed as direct inputs using psa_key_derivation_input_bytes(). Refer to the documentation of individual step types for information.
| [in,out] | generator | The generator object to use. It must have been set up with psa_key_derivation_setup() and must not have produced any output yet. |
| step | Which step the input data is for. | |
| handle | Handle to the key. It must have an appropriate type for step and must allow the usage PSA_KEY_USAGE_DERIVE. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_INVALID_HANDLE | |
| PSA_ERROR_EMPTY_SLOT | |
| PSA_ERROR_NOT_PERMITTED | |
| PSA_ERROR_INVALID_ARGUMENT | step is not compatible with the generator's algorithm. |
| PSA_ERROR_INVALID_ARGUMENT | step does not allow key inputs. |
| PSA_ERROR_INSUFFICIENT_MEMORY | |
| PSA_ERROR_COMMUNICATION_FAILURE | |
| PSA_ERROR_HARDWARE_FAILURE | |
| PSA_ERROR_TAMPERING_DETECTED | |
| PSA_ERROR_BAD_STATE | The value of step is not valid given the state of generator. |
| 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_key_derivation_setup | ( | psa_crypto_generator_t * | generator, |
| psa_algorithm_t | alg | ||
| ) |
Set up a key derivation operation.
A key derivation algorithm takes some inputs and uses them to create a byte generator which can be used to produce keys and other cryptographic material.
To use a generator for key derivation:
| [in,out] | generator | The generator object to set up. It must have been initialized but not set up yet. |
| alg | The key derivation algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_KEY_DERIVATION(alg) is true). |
| PSA_SUCCESS | Success. |
| PSA_ERROR_INVALID_ARGUMENT | alg is not a key derivation algorithm. |
| PSA_ERROR_NOT_SUPPORTED | alg is not supported or is not a key derivation algorithm. |
| PSA_ERROR_INSUFFICIENT_MEMORY | |
| PSA_ERROR_COMMUNICATION_FAILURE | |
| PSA_ERROR_HARDWARE_FAILURE | |
| PSA_ERROR_TAMPERING_DETECTED | |
| PSA_ERROR_BAD_STATE |
1.8.11