Platform Security Architecture — cryptography and keystore interface  beta 2 — 2019-02-22
Functions
Key import and export

Functions

psa_status_t psa_import_key (psa_key_handle_t handle, psa_key_type_t type, const uint8_t *data, size_t data_length)
 Import a key in binary format. More...
 
psa_status_t psa_destroy_key (psa_key_handle_t handle)
 Destroy a key. More...
 
psa_status_t psa_get_key_information (psa_key_handle_t handle, psa_key_type_t *type, size_t *bits)
 Get basic metadata about a key. More...
 
psa_status_t psa_set_key_domain_parameters (psa_key_handle_t handle, psa_key_type_t type, const uint8_t *data, size_t data_length)
 Set domain parameters for a key. More...
 
psa_status_t psa_get_key_domain_parameters (psa_key_handle_t handle, uint8_t *data, size_t data_size, size_t *data_length)
 Get domain parameters for a key. More...
 
psa_status_t psa_export_key (psa_key_handle_t handle, uint8_t *data, size_t data_size, size_t *data_length)
 Export a key in binary format. More...
 
psa_status_t psa_export_public_key (psa_key_handle_t handle, uint8_t *data, size_t data_size, size_t *data_length)
 Export a public key or the public part of a key pair in binary format. More...
 
psa_status_t psa_copy_key (psa_key_handle_t source_handle, psa_key_handle_t target_handle, const psa_key_policy_t *constraint)
 

Detailed Description

Function Documentation

psa_status_t psa_copy_key ( psa_key_handle_t  source_handle,
psa_key_handle_t  target_handle,
const psa_key_policy_t constraint 
)

Make a copy of a key.

Copy key material from one location to another.

This function is primarily useful to copy a key from one lifetime to another. The target key retains its lifetime and location.

In an implementation where slots have different ownerships, this function may be used to share a key with a different party, subject to implementation-defined restrictions on key sharing. In this case constraint would typically prevent the recipient from exporting the key.

The resulting key may only be used in a way that conforms to all three of: the policy of the source key, the policy previously set on the target, and the constraint parameter passed when calling this function.

  • The usage flags on the resulting key are the bitwise-and of the usage flags on the source policy, the previously-set target policy and the policy constraint.
  • If all three policies allow the same algorithm or wildcard-based algorithm policy, the resulting key has the same algorithm policy.
  • If one of the policies allows an algorithm and all the other policies either allow the same algorithm or a wildcard-based algorithm policy that includes this algorithm, the resulting key allows the same algorithm.

The effect of this function on implementation-defined metadata is implementation-defined.

Parameters
source_handleThe key to copy. It must be a handle to an occupied slot.
target_handleA handle to the target slot. It must not contain key material yet.
[in]constraintAn optional policy constraint. If this parameter is non-null then the resulting key will conform to this policy in addition to the source policy and the policy already present on the target slot. If this parameter is null then the function behaves in the same way as if it was the target policy, i.e. only the source and target policies apply.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_OCCUPIED_SLOTtarget already contains key material.
PSA_ERROR_EMPTY_SLOTsource does not contain key material.
PSA_ERROR_INVALID_ARGUMENTThe policy constraints on the source, on the target and constraints are incompatible.
PSA_ERROR_NOT_PERMITTEDThe source key is not exportable and its lifetime does not allow copying it to the target's lifetime.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED
psa_status_t psa_destroy_key ( psa_key_handle_t  handle)

Destroy a key.

This function destroys the content of the key slot from both volatile memory and, if applicable, non-volatile storage. Implementations shall make a best effort to ensure that any previous content of the slot is unrecoverable.

This function also erases any metadata such as policies and frees all resources associated with the key.

If the key is currently in use in a multipart operation, the multipart operation is aborted.

Parameters
handleHandle to the key slot to erase.
Return values
PSA_SUCCESSThe slot's content, if any, has been erased.
PSA_ERROR_NOT_PERMITTEDThe slot holds content and cannot be erased because it is read-only, either due to a policy or due to physical restrictions.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_COMMUNICATION_FAILUREThere was an failure in communication with the cryptoprocessor. The key material may still be present in the cryptoprocessor.
PSA_ERROR_STORAGE_FAILUREThe storage is corrupted. Implementations shall make a best effort to erase key material even in this stage, however applications should be aware that it may be impossible to guarantee that the key material is not recoverable in such cases.
PSA_ERROR_TAMPERING_DETECTEDAn unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor may have been compromised.
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_export_key ( psa_key_handle_t  handle,
uint8_t *  data,
size_t  data_size,
size_t *  data_length 
)

Export a key in binary format.

The output of this function can be passed to psa_import_key() to create an equivalent object.

If the implementation of psa_import_key() supports other formats beyond the format specified here, the output from psa_export_key() must use the representation specified here, not the original representation.

For standard key types, the output format is as follows:

  • For symmetric keys (including MAC keys), the format is the raw bytes of the key.
  • For DES, the key data consists of 8 bytes. The parity bits must be correct.
  • For Triple-DES, the format is the concatenation of the two or three DES keys.
  • For RSA key pairs (PSA_KEY_TYPE_RSA_KEYPAIR), the format is the non-encrypted DER encoding of the representation defined by PKCS#1 (RFC 8017) as RSAPrivateKey, version 0.
    1 RSAPrivateKey ::= SEQUENCE {
    2  version INTEGER, -- must be 0
    3  modulus INTEGER, -- n
    4  publicExponent INTEGER, -- e
    5  privateExponent INTEGER, -- d
    6  prime1 INTEGER, -- p
    7  prime2 INTEGER, -- q
    8  exponent1 INTEGER, -- d mod (p-1)
    9  exponent2 INTEGER, -- d mod (q-1)
    10  coefficient INTEGER, -- (inverse of q) mod p
    11 }
  • For DSA private keys (PSA_KEY_TYPE_DSA_KEYPAIR), the format is the representation of the private key x as a big-endian byte string. The length of the byte string is the private key size in bytes (leading zeroes are not stripped).
  • For elliptic curve key pairs (key types for which PSA_KEY_TYPE_IS_ECC_KEYPAIR is true), the format is a representation of the private value as a ceiling(m/8)-byte string where m is the bit size associated with the curve, i.e. the bit size of the order of the curve's coordinate field. This byte string is in little-endian order for Montgomery curves (curve types PSA_ECC_CURVE_CURVEXXX), and in big-endian order for Weierstrass curves (curve types PSA_ECC_CURVE_SECTXXX, PSA_ECC_CURVE_SECPXXX and PSA_ECC_CURVE_BRAINPOOL_PXXX). This is the content of the privateKey field of the ECPrivateKey format defined by RFC 5915.
  • For Diffie-Hellman key exchange key pairs (PSA_KEY_TYPE_DH_KEYPAIR), the format is the representation of the private key x as a big-endian byte string. The length of the byte string is the private key size in bytes (leading zeroes are not stripped).
  • For public keys (key types for which PSA_KEY_TYPE_IS_PUBLIC_KEY is true), the format is the same as for psa_export_public_key().
Parameters
handleHandle to the key to export.
[out]dataBuffer where the key data is to be written.
data_sizeSize of the data buffer in bytes.
[out]data_lengthOn success, the number of bytes that make up the key data.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_BUFFER_TOO_SMALLThe size of the data buffer is too small. You can determine a sufficient buffer size by calling PSA_KEY_EXPORT_MAX_SIZE(type, bits) where type is the key type and bits is the key size in bits.
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED
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_export_public_key ( psa_key_handle_t  handle,
uint8_t *  data,
size_t  data_size,
size_t *  data_length 
)

Export a public key or the public part of a key pair in binary format.

The output of this function can be passed to psa_import_key() to create an object that is equivalent to the public key.

This specification supports a single format for each key type. Implementations may support other formats as long as the standard format is supported. Implementations that support other formats should ensure that the formats are clearly unambiguous so as to minimize the risk that an invalid input is accidentally interpreted according to a different format.

For standard key types, the output format is as follows:

  • For RSA public keys (PSA_KEY_TYPE_RSA_PUBLIC_KEY), the DER encoding of the representation defined by RFC 3279 §2.3.1 as RSAPublicKey.
    1 RSAPublicKey ::= SEQUENCE {
    2  modulus INTEGER, -- n
    3  publicExponent INTEGER } -- e
  • For elliptic curve public keys (key types for which PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format is the uncompressed representation defined by SEC1 §2.3.3 as the content of an ECPoint. Let m be the bit size associated with the curve, i.e. the bit size of q for a curve over F_q. The representation consists of:
    • The byte 0x04;
    • x_P as a ceiling(m/8)-byte string, big-endian;
    • y_P as a ceiling(m/8)-byte string, big-endian.
  • For DSA public keys (PSA_KEY_TYPE_DSA_PUBLIC_KEY), the format is the representation of the public key y = g^x mod p as a big-endian byte string. The length of the byte string is the length of the base prime p in bytes.
  • For Diffie-Hellman key exchange public keys (PSA_KEY_TYPE_DH_PUBLIC_KEY), the format is the representation of the public key y = g^x mod p as a big-endian byte string. The length of the byte string is the length of the base prime p in bytes.
Parameters
handleHandle to the key to export.
[out]dataBuffer where the key data is to be written.
data_sizeSize of the data buffer in bytes.
[out]data_lengthOn success, the number of bytes that make up the key data.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_INVALID_ARGUMENTThe key is neither a public key nor a key pair.
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_BUFFER_TOO_SMALLThe size of the data buffer is too small. You can determine a sufficient buffer size by calling PSA_KEY_EXPORT_MAX_SIZE(PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type), bits) where type is the key type and bits is the key size in bits.
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED
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_get_key_domain_parameters ( psa_key_handle_t  handle,
uint8_t *  data,
size_t  data_size,
size_t *  data_length 
)

Get domain parameters for a key.

Get the domain parameters for a key with this function, if any. The format of the domain parameters written to data is specified in the documentation for psa_set_key_domain_parameters().

Parameters
handleHandle to the key to get domain parameters from.
[out]dataOn success, the key domain parameters.
data_sizeSize of the data buffer in bytes.
[out]data_lengthOn success, the number of bytes that make up the key domain parameters data.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_EMPTY_SLOTThere is no key in the specified slot.
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED
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_get_key_information ( psa_key_handle_t  handle,
psa_key_type_t type,
size_t *  bits 
)

Get basic metadata about a key.

Parameters
handleHandle to the key slot to query.
[out]typeOn success, the key type (a PSA_KEY_TYPE_XXX value). This may be a null pointer, in which case the key type is not written.
[out]bitsOn success, the key size in bits. This may be a null pointer, in which case the key size is not written.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_EMPTY_SLOTThe handle is to a key slot which does not contain key material yet.
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED
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_import_key ( psa_key_handle_t  handle,
psa_key_type_t  type,
const uint8_t *  data,
size_t  data_length 
)

Import a key in binary format.

This function supports any output from psa_export_key(). Refer to the documentation of psa_export_public_key() for the format of public keys and to the documentation of psa_export_key() for the format for other key types.

This specification supports a single format for each key type. Implementations may support other formats as long as the standard format is supported. Implementations that support other formats should ensure that the formats are clearly unambiguous so as to minimize the risk that an invalid input is accidentally interpreted according to a different format.

Parameters
handleHandle to the slot where the key will be stored. It must have been obtained by calling psa_allocate_key() or psa_create_key() and must not contain key material yet.
typeKey type (a PSA_KEY_TYPE_XXX value). On a successful import, the key slot will contain a key of this type.
[in]dataBuffer containing the key data. The content of this buffer is interpreted according to type. It must contain the format described in the documentation of psa_export_key() or psa_export_public_key() for the chosen type.
data_lengthSize of the data buffer in bytes.
Return values
PSA_SUCCESSSuccess. If the key is persistent, the key material and the key's metadata have been saved to persistent storage.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_SUPPORTEDThe key type or key size is not supported, either by the implementation in general or in this particular slot.
PSA_ERROR_INVALID_ARGUMENTThe key slot is invalid, or the key data is not correctly formatted.
PSA_ERROR_OCCUPIED_SLOTThere is already a key in the specified slot.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED
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_set_key_domain_parameters ( psa_key_handle_t  handle,
psa_key_type_t  type,
const uint8_t *  data,
size_t  data_length 
)

Set domain parameters for a key.

Some key types require additional domain parameters to be set before import or generation of the key. The domain parameters can be set with this function or, for key generation, through the extra parameter of psa_generate_key().

The format for the required domain parameters varies by the key type.

  • For DSA public keys (PSA_KEY_TYPE_DSA_PUBLIC_KEY), the Dss-Parms format as defined by RFC 3279 §2.3.2.
    1 Dss-Parms ::= SEQUENCE {
    2  p INTEGER,
    3  q INTEGER,
    4  g INTEGER
    5 }
  • For Diffie-Hellman key exchange keys (PSA_KEY_TYPE_DH_PUBLIC_KEY), the DomainParameters format as defined by RFC 3279 §2.3.3.
    1 DomainParameters ::= SEQUENCE {
    2  p INTEGER, -- odd prime, p=jq +1
    3  g INTEGER, -- generator, g
    4  q INTEGER, -- factor of p-1
    5  j INTEGER OPTIONAL, -- subgroup factor
    6  validationParms ValidationParms OPTIONAL
    7 }
    8 ValidationParms ::= SEQUENCE {
    9  seed BIT STRING,
    10  pgenCounter INTEGER
    11 }
Parameters
handleHandle to the slot where the key will be stored. This must be a valid slot for a key of the chosen type: it must have been obtained by calling psa_allocate_key() or psa_create_key() with the correct type and with a maximum size that is compatible with data. It must not contain key material yet.
typeKey type (a PSA_KEY_TYPE_XXX value). When subsequently creating key material into handle, the type must be compatible.
[in]dataBuffer containing the key domain parameters. The content of this buffer is interpreted according to type. of psa_export_key() or psa_export_public_key() for the chosen type.
data_lengthSize of the data buffer in bytes.
Return values
PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_OCCUPIED_SLOTThere is already a key in the specified slot.
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED
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.