Platform Security Architecture — cryptography and keystore interface  beta 2 — 2019-02-22
Macros | Typedefs | Functions
Key derivation

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)
 

Detailed Description

Macro Definition Documentation

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

Function Documentation

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.

Parameters
[in,out]generatorThe 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.
stepWhich step the input data is for.
private_keyHandle to the private key to use.
[in]peer_keyPublic 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_lengthSize of peer_key in bytes.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENTprivate_key is not compatible with alg, or peer_key is not valid for alg or not compatible with private_key.
PSA_ERROR_NOT_SUPPORTEDalg 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.

Warning
The raw result of a key agreement algorithm such as finite-field Diffie-Hellman or elliptic curve Diffie-Hellman has biases and should not be used directly as key material. It should instead be passed as input to a key derivation algorithm. To chain a key agreement with a key derivation, use psa_key_agreement() and other functions from the key derivation and generator interface.
Parameters
algThe key agreement algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) is true).
private_keyHandle to the private key to use.
[in]peer_keyPublic 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_lengthSize of peer_key in bytes.
[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_SUCCESSSuccess.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENTalg is not a key agreement algorithm
PSA_ERROR_INVALID_ARGUMENTprivate_key is not compatible with alg, or peer_key is not valid for alg or not compatible with private_key.
PSA_ERROR_NOT_SUPPORTEDalg 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.

Parameters
[in,out]generatorThe generator object to use. It must have been set up with psa_key_derivation_setup() and must not have produced any output yet.
stepWhich step the input data is for.
[in]dataInput data to use.
data_lengthSize of the data buffer in bytes.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_ARGUMENTstep is not compatible with the generator's algorithm.
PSA_ERROR_INVALID_ARGUMENTstep does not allow direct inputs.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED
PSA_ERROR_BAD_STATEThe value of step is not valid given the state of generator.
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_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.

Parameters
[in,out]generatorThe generator object to use. It must have been set up with psa_key_derivation_setup() and must not have produced any output yet.
stepWhich step the input data is for.
handleHandle to the key. It must have an appropriate type for step and must allow the usage PSA_KEY_USAGE_DERIVE.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENTstep is not compatible with the generator's algorithm.
PSA_ERROR_INVALID_ARGUMENTstep does not allow key inputs.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED
PSA_ERROR_BAD_STATEThe value of step is not valid given the state of generator.
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_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:

Parameters
[in,out]generatorThe generator object to set up. It must have been initialized but not set up yet.
algThe key derivation algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_KEY_DERIVATION(alg) is true).
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_ARGUMENTalg is not a key derivation algorithm.
PSA_ERROR_NOT_SUPPORTEDalg 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