|
Platform Security Architecture — cryptography and keystore interface
beta 2 — 2019-02-22
|
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) |
| 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 effect of this function on implementation-defined metadata is implementation-defined.
| source_handle | The key to copy. It must be a handle to an occupied slot. | |
| target_handle | A handle to the target slot. It must not contain key material yet. | |
| [in] | constraint | An 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. |
| PSA_SUCCESS | |
| PSA_ERROR_INVALID_HANDLE | |
| PSA_ERROR_OCCUPIED_SLOT | target already contains key material. |
| PSA_ERROR_EMPTY_SLOT | source does not contain key material. |
| PSA_ERROR_INVALID_ARGUMENT | The policy constraints on the source, on the target and constraints are incompatible. |
| PSA_ERROR_NOT_PERMITTED | The 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.
| handle | Handle to the key slot to erase. |
| PSA_SUCCESS | The slot's content, if any, has been erased. |
| PSA_ERROR_NOT_PERMITTED | The 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_FAILURE | There was an failure in communication with the cryptoprocessor. The key material may still be present in the cryptoprocessor. |
| PSA_ERROR_STORAGE_FAILURE | The 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_DETECTED | An unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor may have been compromised. |
| 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_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:
RSAPrivateKey, version 0. 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).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.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).| handle | Handle to the key to export. | |
| [out] | data | Buffer where the key data is to be written. |
| data_size | Size of the data buffer in bytes. | |
| [out] | data_length | On success, the number of bytes that make up the key data. |
| PSA_SUCCESS | |
| PSA_ERROR_INVALID_HANDLE | |
| PSA_ERROR_EMPTY_SLOT | |
| PSA_ERROR_NOT_PERMITTED | |
| PSA_ERROR_NOT_SUPPORTED | |
| PSA_ERROR_BUFFER_TOO_SMALL | The 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_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_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:
RSAPublicKey. 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:x_P as a ceiling(m/8)-byte string, big-endian;y_P as a ceiling(m/8)-byte string, big-endian.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.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.| handle | Handle to the key to export. | |
| [out] | data | Buffer where the key data is to be written. |
| data_size | Size of the data buffer in bytes. | |
| [out] | data_length | On success, the number of bytes that make up the key data. |
| PSA_SUCCESS | |
| PSA_ERROR_INVALID_HANDLE | |
| PSA_ERROR_EMPTY_SLOT | |
| PSA_ERROR_INVALID_ARGUMENT | The key is neither a public key nor a key pair. |
| PSA_ERROR_NOT_SUPPORTED | |
| PSA_ERROR_BUFFER_TOO_SMALL | The 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_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_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().
| handle | Handle to the key to get domain parameters from. | |
| [out] | data | On success, the key domain parameters. |
| data_size | Size of the data buffer in bytes. | |
| [out] | data_length | On success, the number of bytes that make up the key domain parameters data. |
| PSA_SUCCESS | |
| PSA_ERROR_INVALID_HANDLE | |
| PSA_ERROR_EMPTY_SLOT | There 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_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_get_key_information | ( | psa_key_handle_t | handle, |
| psa_key_type_t * | type, | ||
| size_t * | bits | ||
| ) |
Get basic metadata about a key.
| handle | Handle to the key slot to query. | |
| [out] | type | On 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] | bits | On success, the key size in bits. This may be a null pointer, in which case the key size is not written. |
| PSA_SUCCESS | |
| PSA_ERROR_INVALID_HANDLE | |
| PSA_ERROR_EMPTY_SLOT | The 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_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_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.
| handle | Handle 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. | |
| type | Key type (a PSA_KEY_TYPE_XXX value). On a successful import, the key slot will contain a key of this type. | |
| [in] | data | Buffer 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_length | Size of the data buffer in bytes. |
| PSA_SUCCESS | Success. 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_SUPPORTED | The key type or key size is not supported, either by the implementation in general or in this particular slot. |
| PSA_ERROR_INVALID_ARGUMENT | The key slot is invalid, or the key data is not correctly formatted. |
| PSA_ERROR_OCCUPIED_SLOT | There 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_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_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.
Dss-Parms format as defined by RFC 3279 §2.3.2. DomainParameters format as defined by RFC 3279 §2.3.3. | handle | Handle 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. | |
| type | Key type (a PSA_KEY_TYPE_XXX value). When subsequently creating key material into handle, the type must be compatible. | |
| [in] | data | Buffer 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_length | Size of the data buffer in bytes. |
| PSA_SUCCESS | |
| PSA_ERROR_INVALID_HANDLE | |
| PSA_ERROR_OCCUPIED_SLOT | There 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_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. |
1.8.11