Function esp_idf_sys::psa_export_key

source ·

pub unsafe extern "C" fn psa_export_key(
    key: mbedtls_svc_key_id_t,
    data: *mut u8,
    data_size: usize,
    data_length: *mut usize
) -> psa_status_t

Expand description

\brief 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
}

For elliptic curve key pairs (key types for which #PSA_KEY_TYPE_IS_ECC_KEY_PAIR 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_FAMILY_CURVEXXX), and in big-endian order for Weierstrass curves (curve types PSA_ECC_FAMILY_SECTXXX, PSA_ECC_FAMILY_SECPXXX and PSA_ECC_FAMILY_BRAINPOOL_PXXX). For Weierstrass curves, this is the content of the privateKey field of the ECPrivateKey format defined by RFC 5915. For Montgomery curves, the format is defined by RFC 7748, and output is masked according to §5. For twisted Edwards curves, the private key is as defined by RFC 8032 (a 32-byte string for Edwards25519, a 57-byte string for Edwards448).
For Diffie-Hellman key exchange key pairs (key types for which #PSA_KEY_TYPE_IS_DH_KEY_PAIR is true), 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().

The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set.

\param key Identifier of the key to export. It must allow the usage #PSA_KEY_USAGE_EXPORT, unless it is a public key. \param[out] data Buffer where the key data is to be written. \param data_size Size of the \p data buffer in bytes. \param[out] data_length On success, the number of bytes that make up the key data.

\retval #PSA_SUCCESS \emptydescription \retval #PSA_ERROR_INVALID_HANDLE \emptydescription \retval #PSA_ERROR_NOT_PERMITTED The key does not have the #PSA_KEY_USAGE_EXPORT flag. \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription \retval #PSA_ERROR_BUFFER_TOO_SMALL The size of the \p data buffer is too small. You can determine a sufficient buffer size by calling #PSA_EXPORT_KEY_OUTPUT_SIZE(\c type, \c bits) where \c type is the key type and \c bits is the key size in bits. \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription \retval #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.