Key import and export

General Description

Typedefs
typedef uint16_t	cy_p64_psa_key_handle_t
	This type represents open handles to keys. More...
typedef uint32_t	cy_p64_key_slot_t
	Key ID / slot number. More...

Functions
cy_p64_psa_status_t	cy_p64_psa_destroy_key (cy_p64_psa_key_handle_t handle)
	Destroys a key. More...
cy_p64_psa_status_t	cy_p64_psa_generate_key (cy_p64_psa_key_handle_t *handle, const cy_p64_psa_key_attributes_t *attributes)
	Generates a key or key pair. More...
cy_p64_psa_status_t	cy_p64_psa_import_key (const cy_p64_psa_key_attributes_t *attributes, const uint8_t *data, size_t data_length, cy_p64_psa_key_handle_t *handle)
	Imports a key in binary format. More...
cy_p64_psa_status_t	cy_p64_psa_get_key_attributes (cy_p64_psa_key_handle_t handle, cy_p64_psa_key_attributes_t *attributes)
	Retrieves the attributes of a key. More...
cy_p64_psa_status_t	cy_p64_psa_export_key (cy_p64_psa_key_handle_t handle, uint8_t *data, size_t data_size, size_t *data_length)
	Exports a key in binary format. More...
cy_p64_psa_status_t	cy_p64_psa_export_public_key (cy_p64_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...
cy_p64_psa_status_t	cy_p64_keys_load_key_handle (cy_p64_key_slot_t key_id, cy_p64_psa_key_handle_t *handle)
	This function loads key handle from the Secure FlashBoot key storage. More...
cy_p64_psa_status_t	cy_p64_keys_store_key (cy_p64_key_slot_t key_id, cy_p64_psa_key_handle_t handle)
	This function stores a new key handle for the key slot. More...
cy_p64_psa_status_t	cy_p64_keys_close_key (cy_p64_key_slot_t key_id)
	This function destroys the key handle stored in key_id slot and clears handle from Secure FlashBoot key storage. More...
uint32_t	cy_p64_keys_get_count (void)
	This function returns the maximum amount of keys supported by Secure FlashBoot. More...

Typedef Documentation

cy_p64_psa_key_handle_t

typedef uint16_t cy_p64_psa_key_handle_t

This type represents open handles to keys.

0 is not a valid key handle. How other handle values are assigned is implementation-dependent.

cy_p64_key_slot_t

typedef uint32_t cy_p64_key_slot_t

Key ID / slot number.

This type represents key slot in Secure FlashBoot. Each slot(1 to CY_P64_KEY_SLOT_STATIC_MAX) stores key handle which is initialized during boot by SFB.

Function Documentation

cy_p64_psa_destroy_key()

cy_p64_psa_status_t cy_p64_psa_destroy_key

(

cy_p64_psa_key_handle_t

handle

)

Destroys a key.

This function destroys a key from both volatile memory and, if applicable, non-volatile storage. Implementations shall make a best effort to ensure that that the key material cannot be recovered.

This function also erases any metadata such as policies and frees resources associated with the key. To free all resources associated with the key, all handles to the key must be closed or destroyed.

Destroying the key makes the handle invalid, and the key handle must not be used again by the application. Using other open handles to the destroyed key in a cryptographic operation will result in an error.

If a key is currently in use in a multipart operation, destroying the key will cause the multipart operation to fail.

Parameters

handle

Handle to the key to erase. If this is 0, do nothing and return CY_P64_PSA_SUCCESS.

Return values

CY_P64_PSA_SUCCESS	handle was a valid handle and the key material that it referred to has been erased. Alternatively, handle is 0.
CY_P64_PSA_ERROR_NOT_PERMITTED	The key cannot be erased because it is read-only, either due to a policy or due to physical restrictions.
CY_P64_PSA_ERROR_INVALID_HANDLE	handle is not a valid handle nor 0.
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE	There was a failure in communication with the cryptoprocessor. The key material may still be present in the cryptoprocessor.
CY_P64_PSA_ERROR_STORAGE_FAILURE	The storage is corrupted. Implementations shall make a best effort to erase the 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.
CY_P64_PSA_ERROR_CORRUPTION_DETECTED	An unexpected condition, which is not a storage corruption or a communication failure. The cryptoprocessor may have been compromised.
CY_P64_PSA_ERROR_BAD_STATE	It is implementation-dependent whether initialize results fails in this error code

cy_p64_psa_generate_key()

cy_p64_psa_status_t cy_p64_psa_generate_key	(	cy_p64_psa_key_handle_t *	handle,
		const cy_p64_psa_key_attributes_t *	attributes
	)

Generates a key or key pair.

The key is generated randomly. Its location, usage policy, type and size are taken from attributes.

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

The following type-specific considerations apply:

• For RSA keys (CY_P64_PSA_KEY_TYPE_RSA_KEY_PAIR), the public exponent is 65537. The modulus is a product of two probabilistic primes between 2^{n-1} and 2^n where n is the bit size specified in the attributes.

Parameters

[in]	attributes	The attributes for the new key.
[out]	handle	On success, a handle to the newly created key. 0 on failure.

Return values

CY_P64_PSA_SUCCESS	Success. If the key is persistent, the key material and the key's metadata have been saved to persistent storage.
CY_P64_PSA_ERROR_ALREADY_EXISTS	This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
CY_P64_PSA_ERROR_NOT_SUPPORTED
CY_P64_PSA_ERROR_INVALID_ARGUMENT
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_INSUFFICIENT_ENTROPY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_INSUFFICIENT_STORAGE
CY_P64_PSA_ERROR_STORAGE_FAILURE
CY_P64_PSA_ERROR_BAD_STATE	It is implementation-dependent whether initialize results fails in this error code

cy_p64_psa_import_key()

cy_p64_psa_status_t cy_p64_psa_import_key	(	const cy_p64_psa_key_attributes_t *	attributes,
		const uint8_t *	data,
		size_t	data_length,
		cy_p64_psa_key_handle_t *	handle
	)

Imports a key in binary format.

This function supports any output from cy_p64_psa_export_key(). Refer to the documentation of cy_p64_psa_export_public_key() for the format of public keys and to the documentation of cy_p64_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; 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]	attributes	The 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]	handle	On success, a handle to the newly created key. 0 on failure.
[in]	data	The buffer that contains 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 cy_p64_psa_export_key() or cy_p64_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_length	Size of the data buffer in bytes.

Return values

CY_P64_PSA_SUCCESS	Success. If the key is persistent, the key material and the key's metadata have been saved to persistent storage.
CY_P64_PSA_ERROR_ALREADY_EXISTS	This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
CY_P64_PSA_ERROR_NOT_SUPPORTED	The key type or key size is not supported, either by the implementation in general or in this particular persistent location.
CY_P64_PSA_ERROR_INVALID_ARGUMENT	The key attributes, as a whole, are invalid.
CY_P64_PSA_ERROR_INVALID_ARGUMENT	The key data is not correctly formatted.
CY_P64_PSA_ERROR_INVALID_ARGUMENT	The size in attributes is nonzero and does not match the size of the key data.
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_INSUFFICIENT_STORAGE
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_STORAGE_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_BAD_STATE	It is implementation-dependent whether initialize results fails in this error code

cy_p64_psa_get_key_attributes()

cy_p64_psa_status_t cy_p64_psa_get_key_attributes	(	cy_p64_psa_key_handle_t	handle,
		cy_p64_psa_key_attributes_t *	attributes
	)

Retrieves the attributes of a key.

This function first resets the attribute structure as with cy_p64_psa_reset_key_attributes(). It then copies the attributes of the given key into the given attribute structure.

Note

This function may allocate memory or other resources. Once you have called this function on an attribute structure, you must call cy_p64_psa_reset_key_attributes() to free these resources.

Parameters

[in]	handle	The handle to the key to query.
[in,out]	attributes	On success, the attributes of the key. On failure, equivalent to a freshly-initialized structure.

Return values

CY_P64_PSA_SUCCESS
CY_P64_PSA_ERROR_INVALID_HANDLE
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_STORAGE_FAILURE
CY_P64_PSA_ERROR_BAD_STATE	It is implementation-dependent whether initialize results fails in this error code

cy_p64_psa_export_key()

cy_p64_psa_status_t cy_p64_psa_export_key	(	cy_p64_psa_key_handle_t	handle,
		uint8_t *	data,
		size_t	data_size,
		size_t *	data_length
	)

Exports a key in binary format.

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

If the implementation of cy_p64_psa_import_key() supports other formats beyond the format specified here, the output from cy_p64_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 (CY_P64_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 CY_P64_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 sect.5.
• For Diffie-Hellman key exchange key pairs (key types for which CY_P64_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 CY_P64_PSA_KEY_TYPE_IS_PUBLIC_KEY is true), the format is the same as for cy_p64_psa_export_public_key().

The policy on the key must have the usage flag CY_P64_PSA_KEY_USAGE_EXPORT set.

Parameters

	handle	The handle to the key to export.
[out]	data	The buffer to write the key data in.
	data_size	The size of the data buffer in bytes.
[out]	data_length	On success, the number of bytes that make up the key data.

Return values

CY_P64_PSA_SUCCESS
CY_P64_PSA_ERROR_INVALID_HANDLE
CY_P64_PSA_ERROR_NOT_PERMITTED	The key does not have the CY_P64_PSA_KEY_USAGE_EXPORT flag.
CY_P64_PSA_ERROR_NOT_SUPPORTED
CY_P64_PSA_ERROR_BUFFER_TOO_SMALL	The size of the data buffer is too small. You can determine a sufficient buffer size by calling CY_P64_PSA_KEY_EXPORT_MAX_SIZE(type, bits) where type is the key type and bits is the key size in bits.
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_STORAGE_FAILURE
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_BAD_STATE	It is implementation-dependent whether initialize results fails in this error code

cy_p64_psa_export_public_key()

cy_p64_psa_status_t cy_p64_psa_export_public_key	(	cy_p64_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 cy_p64_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 (CY_P64_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

• For elliptic curve public keys (key types for which CY_P64_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 Diffie-Hellman key exchange public keys (key types for which CY_P64_PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true), 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.

Exporting a public key object or the public part of a key pair is always permitted, regardless of the key's usage flags.

Parameters

	handle	The handle to the key to export.
[out]	data	The buffer to write the key data in.
	data_size	The size of the data buffer in bytes.
[out]	data_length	On success, the number of bytes that make up the key data.

Return values

CY_P64_PSA_SUCCESS
CY_P64_PSA_ERROR_INVALID_HANDLE
CY_P64_PSA_ERROR_INVALID_ARGUMENT	The key is neither a public key nor a key pair.
CY_P64_PSA_ERROR_NOT_SUPPORTED
CY_P64_PSA_ERROR_BUFFER_TOO_SMALL	The size of the data buffer is too small. You can determine a sufficient buffer size by calling CY_P64_PSA_KEY_EXPORT_MAX_SIZE(CY_P64_PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type), bits) where type is the key type and bits is the key size in bits.
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_STORAGE_FAILURE
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_BAD_STATE	It is implementation-dependent whether initialize results fails in this error code

cy_p64_keys_load_key_handle()

cy_p64_psa_status_t cy_p64_keys_load_key_handle	(	cy_p64_key_slot_t	key_id,
		cy_p64_psa_key_handle_t *	handle
	)

This function loads key handle from the Secure FlashBoot key storage.

Keys in slot range from 1 to CY_P64_KEY_SLOT_STATIC_MAX are initialized during boot by SFB. They are protected from modification by SFB.

Parameters

[in]	key_id	The slot number in SFB key storage. Reserved keys are defined by CY_P64_KEY_SLOT_XXX define. Maximum value - cy_p64_keys_get_count()
[out]	handle	Returned key handle.

Return values

CY_P64_PSA_SUCCESS	Success.
CY_P64_PSA_ERROR_DOES_NOT_EXIST
CY_P64_PSA_ERROR_INVALID_ARGUMENT
CY_P64_INVALID_ADDR_PROTECTED

cy_p64_keys_store_key()

cy_p64_psa_status_t cy_p64_keys_store_key	(	cy_p64_key_slot_t	key_id,
		cy_p64_psa_key_handle_t	handle
	)

This function stores a new key handle for the key slot.

If the slot was not empty the function first destroys existing key. Keys in slot range from 1 to CY_P64_KEY_SLOT_STATIC_MAX are initialized during boot by SFB. They are protected from modification by SFB.

Parameters

[in]	key_id	The slot number in SFB key storage. Minimum value - CY_P64_KEY_SLOT_STATIC_MAX + 1. Maximum value - cy_p64_keys_get_count()
[out]	handle	Key handle to store.

Return values

CY_P64_PSA_SUCCESS	Success.
CY_P64_PSA_ERROR_DOES_NOT_EXIST
CY_P64_PSA_ERROR_INVALID_ARGUMENT

cy_p64_keys_close_key()

cy_p64_psa_status_t cy_p64_keys_close_key

(

cy_p64_key_slot_t

key_id

)

This function destroys the key handle stored in key_id slot and clears handle from Secure FlashBoot key storage.

Parameters

[in]

key_id

The slot number in SFB key storage. Minimum value - CY_P64_KEY_SLOT_STATIC_MAX + 1. Maximum value - cy_p64_keys_get_count()

Return values

CY_P64_PSA_SUCCESS	Success.
CY_P64_PSA_ERROR_DOES_NOT_EXIST
CY_P64_PSA_ERROR_INVALID_ARGUMENT

cy_p64_keys_get_count()

uint32_t cy_p64_keys_get_count

(

void

)

This function returns the maximum amount of keys supported by Secure FlashBoot.

Return values

Maximum

key count.