MCUX CLNS
MCUX Crypto Library Normal Secure
mcuxClPsaDriver_Oracle.h File Reference

API definition of the PSA driver Oracle. More...

#include <crypto.h>
#include <mcuxClKey.h>
#include <mcuxClConfig.h>

Go to the source code of this file.

Functions

psa_status_t mcuxClPsaDriver_Oracle_ExportPublicKey (mcuxClKey_Descriptor_t *pKey, uint8_t *data, size_t data_size, size_t *data_length, bool internal_representation)
 Oracle function for exporting of the public key created in ELS during KEY_GEN command. More...
 
psa_status_t mcuxClPsaDriver_Oracle_LoadKey (mcuxClKey_Descriptor_t *pKey)
 Oracle function for loading a key. More...
 
psa_status_t mcuxClPsaDriver_Oracle_SuspendKey (mcuxClKey_Descriptor_t *pKey)
 Oracle function for 'suspending' a key. More...
 
psa_status_t mcuxClPsaDriver_Oracle_ResumeKey (mcuxClKey_Descriptor_t *pKey)
 Oracle function for 'resuming' a previously 'suspended' key. More...
 
psa_status_t mcuxClPsaDriver_Oracle_UnloadKey (mcuxClKey_Descriptor_t *pKey)
 Oracle function for 'unloading' a previously loaded key. More...
 
psa_status_t mcuxClPsaDriver_Oracle_ReserveKey (mcuxClKey_Descriptor_t *pKey)
 Oracle function for allocating storage for a key that will be created by the psa driver. More...
 
psa_status_t mcuxClPsaDriver_Oracle_StoreKey (mcuxClKey_Descriptor_t *pKey)
 Oracle function for saving a key. More...
 
psa_status_t mcuxClPsaDriver_Oracle_ImportKey (mcuxClKey_Descriptor_t *pKey, const uint8_t *data, size_t data_length, size_t *key_buffer_length, size_t *bits)
 Oracle function for executing S50 specific activities when the import of key is done the PSA library will proceed with storing the key. More...
 
psa_status_t mcuxClPsaDriver_Oracle_GetKeyBufferSizeFromKeyData (const psa_key_attributes_t *attributes, const uint8_t *data, size_t data_length, size_t *key_buffer_length)
 Oracle function for determine the size required for a key buffer from the data supplied when importing a key. More...
 
psa_status_t mcuxClPsaDriver_Oracle_GetBuiltinKeyBufferSize (mbedtls_svc_key_id_t key_id, size_t *key_buffer_size)
 Oracle function for making keys that are installed upon boot in S50 and keys derived from those (built-in) available to be used with PSA API. More...
 
psa_status_t mcuxClPsaDriver_Oracle_GetBuiltinKeyBuffer (psa_key_attributes_t *attributes, uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length)
 Oracle function for making keys that are installed upon boot in S50 and keys derived from those (built-in) available to be used with PSA API. More...
 

Detailed Description

API definition of the PSA driver Oracle.

Function Documentation

◆ mcuxClPsaDriver_Oracle_ExportPublicKey()

psa_status_t mcuxClPsaDriver_Oracle_ExportPublicKey ( mcuxClKey_Descriptor_t pKey,
uint8_t *  data,
size_t  data_size,
size_t *  data_length,
bool  internal_representation 
)

Oracle function for exporting of the public key created in ELS during KEY_GEN command.

Parameters
[in]pKeyis the reference to the key descriptor of the ELS
[out]datais the buffer including the exported public key
[in]data_sizeis the size of the allocated memory for the data buffer
[out]data_lengthis the lenght of the exported key
[in]internal_representationis the flag to indicate internal representation
Return values
PSA_SUCCESSThe operation was succesful
PSA_ERROR_DOES_NOT_EXISTNo key with the associated key_id found in ELS

◆ mcuxClPsaDriver_Oracle_LoadKey()

psa_status_t mcuxClPsaDriver_Oracle_LoadKey ( mcuxClKey_Descriptor_t pKey)

Oracle function for loading a key.

This function loads an encoded or internal key to memory or the S50 key store.

PRECONDITION: The fields of pKey are initialized as follows:

  • container.pData : points to the psa key buffer (key_buffer)
  • container.length : set to the length of the psa key buffer (key_buffer_size)
  • container.used : set to the length of the psa key buffer (key_buffer_size)
  • container.pAuxData : points to the psa attributes (attributes) All other fields can be uninitialized

POSTCONDITION: In case the key is loaded into memory the fields of pKey are initialized as follows:

  • location.pData : points to the memory location where the key is loaded, this memory is allocated by the Oracle
  • location.length : the length of the key that was loaded to memory; i.e. the buffer length
  • location.slot : does not matter, suggest using 0xFFFFFFu
  • location.status : MCUXCLKEY_LOADSTATUS_MEMORY In case the key is loaded into an S50 key slot the fields of pKey are initialized as follows:
  • location.pData : does not matter, suggest NULL
  • location.length : the length of the key that was loaded to the S50 key slot
  • location.slot : the S50 key slot to which the key was loaded
  • location.status : MCUXCLKEY_LOADSTATUS_COPRO

OPERATION: Depending on the location attribute in the psa attributes, the Oracle allocates a memory location or free key slot in the S50 (the Oracle is responsible for the memory management) and loads the key there. How the location attributes map to endoding or derivation methods is entirely up to the design of the Oracle; e.g. a key could be decrypted from a blob or derived from a master key.

Return values
PSA_SUCCESSThe operation was succesful
PSA_ERROR_NOT_SUPPORTEDThe Oracle shall never return this error code
PSA_ERROR_GENERIC_ERRORThe operation failed (other error codes can be used as well if more specific)

◆ mcuxClPsaDriver_Oracle_SuspendKey()

psa_status_t mcuxClPsaDriver_Oracle_SuspendKey ( mcuxClKey_Descriptor_t pKey)

Oracle function for 'suspending' a key.

This function indicates to the Oracle that the key will temporarily not be used by the psa driver. This allows the Oracle to perform memory management operations on this key.

Return values
PSA_SUCCESSThe operation was succesful
PSA_ERROR_NOT_SUPPORTEDThe Oracle shall never return this error code
PSA_ERROR_GENERIC_ERRORThe operation failed (other error codes can be used as well if more specific)

◆ mcuxClPsaDriver_Oracle_ResumeKey()

psa_status_t mcuxClPsaDriver_Oracle_ResumeKey ( mcuxClKey_Descriptor_t pKey)

Oracle function for 'resuming' a previously 'suspended' key.

This function indicates to the Oracle that the key will be used agian by the psa driver. The Oracle should assure it is available again and may therefore need to re-allocate, re-load the key and update the key fields.

Return values
PSA_SUCCESSThe operation was succesful
PSA_ERROR_NOT_SUPPORTEDThe Oracle shall never return this error code
PSA_ERROR_GENERIC_ERRORThe operation failed (other error codes can be used as well if more specific)

◆ mcuxClPsaDriver_Oracle_UnloadKey()

psa_status_t mcuxClPsaDriver_Oracle_UnloadKey ( mcuxClKey_Descriptor_t pKey)

Oracle function for 'unloading' a previously loaded key.

This function indicates to the Oracle that the key will not be used any more by the psa driver. This allows the Oracle to free the allocated storage for this key.

Return values
PSA_SUCCESSThe operation was succesful
PSA_ERROR_NOT_SUPPORTEDThe Oracle shall never return this error code
PSA_ERROR_GENERIC_ERRORThe operation failed (other error codes can be used as well if more specific)

◆ mcuxClPsaDriver_Oracle_ReserveKey()

psa_status_t mcuxClPsaDriver_Oracle_ReserveKey ( mcuxClKey_Descriptor_t pKey)

Oracle function for allocating storage for a key that will be created by the psa driver.

This function requests storage space from the Oracle for a key that will be created by the psa driver. The Oracle shall allocate memory space or a key slot capable of holding the to be generated key.

Return values
PSA_SUCCESSThe operation was succesful
PSA_ERROR_NOT_SUPPORTEDThe Oracle shall never return this error code
PSA_ERROR_GENERIC_ERRORThe operation failed (other error codes can be used as well if more specific)

◆ mcuxClPsaDriver_Oracle_StoreKey()

psa_status_t mcuxClPsaDriver_Oracle_StoreKey ( mcuxClKey_Descriptor_t pKey)

Oracle function for saving a key.

This function saves a key from memory or the S50 key store to an encoded format (blob).

Return values
PSA_SUCCESSThe operation was succesful
PSA_ERROR_NOT_SUPPORTEDThe Oracle shall never return this error code
PSA_ERROR_GENERIC_ERRORThe operation failed (other error codes can be used as well if more specific)

◆ mcuxClPsaDriver_Oracle_ImportKey()

psa_status_t mcuxClPsaDriver_Oracle_ImportKey ( mcuxClKey_Descriptor_t pKey,
const uint8_t *  data,
size_t  data_length,
size_t *  key_buffer_length,
size_t *  bits 
)

Oracle function for executing S50 specific activities when the import of key is done the PSA library will proceed with storing the key.

After the evaluation the function will generate the buffer which will be stored in the memory by the PSA

Parameters
[in]attributesdefines the attributes associated with the input buffer PRECONDITION: The fields of pKey are initialized as follows:
  • container.pData : points to the psa key buffer (key_buffer)
  • container.length : set to the length of the psa key buffer (key_buffer_size)
  • container.used : set to the length of the psa key buffer (key_buffer_size)
  • container.pAuxData : points to the psa attributes (attributes) All other fields shall be initialized
[in]pKeyis the reference to the key descriptor of the ELS
[in]datais the buffer including public key for import
[in]data_lengthis the length of data
[out]key_buffer_lengthis the effective number of data filled in the key_buffer returned by the function
[out]bitsis the number of bits representing the key (e.g. 256 for the NISTP 256 key)
Return values
PSA_SUCCESSThe operation was succesful
PSA_ERROR_NOT_SUPPORTEDThe lifetime is not supported, meaning that fallback functions will be executed by Oracle
PSA_ERROR_INSUFFICIENT_MEMORYThe key_buffer size is not enough to include data to be stored

◆ mcuxClPsaDriver_Oracle_GetKeyBufferSizeFromKeyData()

psa_status_t mcuxClPsaDriver_Oracle_GetKeyBufferSizeFromKeyData ( const psa_key_attributes_t *  attributes,
const uint8_t *  data,
size_t  data_length,
size_t *  key_buffer_length 
)

Oracle function for determine the size required for a key buffer from the data supplied when importing a key.

The size of the data required to store a key is not necessarily the same as the size of the date supplied when importing a key. In particular for key recipes, the recipe gets parsed upon import and stored in an internal representation which consumes a different amount of space.

Parameters
[in]attributesdefines the attributes associated with the input buffer
[in]dataincludes the input buffer as passed to the psa import function
[in]data_lengthis the length of data
[out]key_bufferis the buffer which will be stored by PSA in the memory
[out]key_buffer_lengthis the required number of bytes required as key_buffer
Return values
PSA_SUCCESSThe operation was succesful
PSA_ERROR_NOT_SUPPORTEDThe lifetime is not supported, meaning that fallback functions will be executed by Oracle
PSA_ERROR_INSUFFICIENT_MEMORYThe key_buffer size is not enough to include data to be stored

◆ mcuxClPsaDriver_Oracle_GetBuiltinKeyBufferSize()

psa_status_t mcuxClPsaDriver_Oracle_GetBuiltinKeyBufferSize ( mbedtls_svc_key_id_t  key_id,
size_t *  key_buffer_size 
)

Oracle function for making keys that are installed upon boot in S50 and keys derived from those (built-in) available to be used with PSA API.

PSA does store information about such keys (either the S50 slot number or a derivation recipe). Therefore it needs to know the size to reserve for a particular key.

Parameters
[in]key_idthe PSA key id of a built-in key
[out]key_buffer_sizethe required size of the buffer to store a built-in key

◆ mcuxClPsaDriver_Oracle_GetBuiltinKeyBuffer()

psa_status_t mcuxClPsaDriver_Oracle_GetBuiltinKeyBuffer ( psa_key_attributes_t *  attributes,
uint8_t *  key_buffer,
size_t  key_buffer_size,
size_t *  key_buffer_length 
)

Oracle function for making keys that are installed upon boot in S50 and keys derived from those (built-in) available to be used with PSA API.

PSA does store information about such keys (either the S50 slot number or a derivation recipe). This function fills the PSA owned buffer with the required information to use the key.

Parameters
[in]attributesdefines the attributes associated with the input buffer
[out]key_bufferis the buffer which will be stored by PSA in the memory
[in]key_buffer_sizeis the size of the allocated
[out]key_buffer_lengthis the effective number of data filled in the key_buffer by the function