mbed TLS v2.26.0
Functions
Key import and export

Functions

psa_status_t psa_import_key (const psa_key_attributes_t *attributes, const uint8_t *data, size_t data_length, mbedtls_svc_key_id_t *key)
 Import a key in binary format. More...
 
psa_status_t psa_export_key (mbedtls_svc_key_id_t key, 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 (mbedtls_svc_key_id_t key, 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...
 

Detailed Description

Function Documentation

psa_status_t psa_export_key ( mbedtls_svc_key_id_t  key,
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_KEY_PAIR), the format is the non-encrypted DER encoding of the representation defined by PKCS#1 (RFC 8017) as RSAPrivateKey, version 0.

``` RSAPrivateKey ::= SEQUENCE { version INTEGER, – must be 0 modulus INTEGER, – n publicExponent INTEGER, – e privateExponent INTEGER, – d prime1 INTEGER, – p prime2 INTEGER, – q exponent1 INTEGER, – d mod (p-1) exponent2 INTEGER, – d mod (q-1) coefficient INTEGER, – (inverse of q) mod p }

psa_status_t psa_export_public_key ( mbedtls_svc_key_id_t  key,
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.

``` RSAPublicKey ::= SEQUENCE { modulus INTEGER, – n publicExponent INTEGER } – e

psa_status_t psa_import_key ( const psa_key_attributes_t attributes,
const uint8_t *  data,
size_t  data_length,
mbedtls_svc_key_id_t key 
)

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.

The key data determines the key size. The attributes may optionally specify a key size; in this case it must match the size determined from the key data. A key size of 0 in attributes indicates that the key size is solely determined by the key data.

Implementations must reject an attempt to import a key of size 0.

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
[in]attributesThe attributes for the new key. The key size is always determined from the data buffer. If the key size in attributes is nonzero, it must be equal to the size from data.
[out]keyOn success, an identifier to the newly created key. For persistent keys, this is the key identifier defined in attributes. 0 on failure.
[in]dataBuffer containing the key data. The content of this buffer is interpreted according to the type declared in attributes. All implementations must support at least the format described in the documentation of psa_export_key() or psa_export_public_key() for the chosen type. Implementations may allow other formats, but should be conservative: implementations should err on the side of rejecting content if it may be erroneous (e.g. wrong type or truncated data).
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_ALREADY_EXISTSThis is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_NOT_SUPPORTEDThe key type or key size is not supported, either by the implementation in general or in this particular persistent location.
PSA_ERROR_INVALID_ARGUMENTThe key attributes, as a whole, are invalid.
PSA_ERROR_INVALID_ARGUMENTThe key data is not correctly formatted.
PSA_ERROR_INVALID_ARGUMENTThe size in attributes is nonzero and does not match the size of the key data.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_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.