NVIDIA DRIVE OS Linux SDK API Reference
5.2.6 Release
For Test and Development only
Enumerations
Oem Keystore Service Constants
Trusted Execution Environment » TEE Internal API » TEE Cryptographic Constants » Commands

Detailed Description

Describes the Oem Keystore Service Constants used by clients.

Enumerations

enum  NV_TE_KeystoreServiceOperation {
  KEYSTORE_SERVICE_PING = 0x00000000,
  KEYSTORE_SERVICE_GET_KEY = 0x00000001,
  KEYSTORE_SERVICE_GET_KEY_ATTRIBUTE = 0x00000002,
  KEYSTORE_SERVICE_PKCS11_LOAD_AES_KEY = 0x00000003,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_LOAD_AES_KEY = 0x00000103,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_RELEASE_AES_KEYSLOT = 0x00000104,
  KEYSTORE_SERVICE_PKCS11_RELEASE_AES_KEYSLOT = 0x00000004,
  KEYSTORE_SERVICE_PKCS11_GET_KEY_OBJ_METADATA = 0x00000006,
  KEYSTORE_SERVICE_PKCS11_GENERATE_AES_KEY = 0x00000007,
  KEYSTORE_SERVICE_PKCS11_DELETE_KEY = 0x00000008,
  KEYSTORE_SERVICE_PKCS11_DERIVE_AES_KEY = 0x00000009,
  KEYSTORE_SERVICE_PKCS11_UNWRAP_AES_KEY = 0x0000000C,
  KEYSTORE_SERVICE_PKCS11_COPY_AES_KEY = 0x00000018,
  KEYSTORE_SERVICE_PKCS11_SET_KEY_OBJ_ID = 0x0000000E,
  KEYSTORE_SERVICE_PKCS11_SET_KEY_OBJ_LABEL = 0x0000000F,
  KEYSTORE_SERVICE_PKCS11_SECURE_STORAGE_GET_STATE = 0x00000010,
  KEYSTORE_SERVICE_PKCS11_SECURE_STORAGE_RESET_FILESYSTEM = 0x00000011,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_UNWRAP_AES_KEY = 0x00000012,
  KEYSTORE_SERVICE_PKCS11_CREATE_RSA_PUB_KEY = 0x00000020,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_LOOKUP_KEY = 0x000000013,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_GET_KEY_OBJ_METADATA = 0x00000014,
  KEYSTORE_SERVICE_PKCS11_LOOKUP_KEY = 0x00000021,
  KEYSTORE_SERVICE_PKCS11_LOAD_RSA_PUB_KEY = 0x00000022,
  KEYSTORE_SERVICE_PKCS11_RELEASE_RSA_KEYSLOT = 0x00000023,
  KEYSTORE_SERVICE_PKCS11_COPY_RSA_PUB_KEY = 0x000000024,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_LOAD_RSA_PUB_KEY = 0x00000122,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_RELEASE_RSA_KEYSLOT = 0x00000123,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_COPY_RSA_PUB_KEY = 0x000000124,
  KEYSTORE_SERVICE_PKCS11_CREATE_ECC_PUB_KEY = 0x00000030,
  KEYSTORE_SERVICE_PKCS11_LOAD_ECC_PUB_KEY = 0x00000031,
  KEYSTORE_SERVICE_PKCS11_RELEASE_ECC_KEYSLOT = 0x00000032,
  KEYSTORE_SERVICE_PKCS11_COPY_ECC_PUB_KEY = 0x000000033,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_COPY_ECC_PUB_KEY = 0x000000133,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_LOAD_ECC_PUB_KEY = 0x00000131,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_RELEASE_ECC_KEYSLOT = 0x00000132,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_GENERATE_AES_KEY = 0x000000015,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_SET_KEY_OBJ_ID = 0x00000016,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_SET_KEY_OBJ_LABEL = 0x00000017,
  KEYSTORE_SERVICE_PKCS11_INIT_KEYSTORE = 0x00000034,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_COPY_AES_KEY = 0x00000019,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_DELETE_KEY = 0x0000001A,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_REQUEST_RW_ACCESS = 0x0000001B,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_RELINQUISH_RW_ACCESS = 0x0000001C,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_REQUEST_RO_ACCESS = 0x0000001D,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_RELINQUISH_RO_ACCESS = 0x0000001E,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_UNWRAP_RSA_PUB_KEY = 0x00000127,
  KEYSTORE_SERVICE_PKCS11_UNWRAP_RSA_PUB_KEY = 0x00000027,
  KEYSTORE_SERVICE_PKCS11_PERSISTENT_UNWRAP_ECC_PUB_KEY = 0x00000128,
  KEYSTORE_SERVICE_PKCS11_UNWRAP_ECC_PUB_KEY = 0x00000028
}
 Defines TOS OEM Keystore Service trusted application commandIDs available to clients. More...
 
enum  NV_TE_KeystoreKeyAttribute {
  KEYSTORE_KEY_ATTRIBUTE_SIZE = 0x00000000,
  KEYSTORE_KEY_ATTRIBUTE_ALGO = 0x00000001,
  KEYSTORE_KEY_ATTRIBUTE_IV = 0x00000002
}
 Defines various key attribute types supported by TOS OEM Keystore Service. More...
 
enum  NV_TE_KeystoreLookupType {
  KEYSTORE_LOOKUP_TYPE_ABSOLUTE = 0x00000001,
  KEYSTORE_LOOKUP_TYPE_RELATIVE = 0x00000002,
  KEYSTORE_LOOKUP_TYPE_BY_ID = 0x00000003
}
 Defines various key lookup schemes supported by TOS OEM Keystore Service. More...
 

Enumeration Type Documentation

◆ NV_TE_KeystoreKeyAttribute

enum NV_TE_KeystoreKeyAttribute

Defines various key attribute types supported by TOS OEM Keystore Service.

For each attribute types, the key index has a different meaning.

Enumerator
KEYSTORE_KEY_ATTRIBUTE_SIZE 

Size of encrypted key material present in the key entry.

For example: If AES-128-CBC is used as encryption algorithm for key material then,
encrypted size is = key_material_size_in_bytes + (16 - (key_material_size_in_bytes % 16)) bytes.

KEYSTORE_KEY_ATTRIBUTE_ALGO 

Decryption Algorithm of encrypted key material present in the key entry.

Note
Not supported by TOS OEM Keystore Service. Option exists for backward compatiability.
KEYSTORE_KEY_ATTRIBUTE_IV 

IV to use alongwith decryption algorithm to decrypt encrypted key material present in the key entry.

Note
Not supported by TOS OEM Keystore Service. Option exists for backward compatiability.

Definition at line 3030 of file nv_te_cryptographic_constants.h.

◆ NV_TE_KeystoreLookupType

enum NV_TE_KeystoreLookupType

Defines various key lookup schemes supported by TOS OEM Keystore Service.

For each lookup scheme, the key index has a different meaning.

Enumerator
KEYSTORE_LOOKUP_TYPE_ABSOLUTE 

Absolute lookup.

Use this option when a client knows the exact key index of the key slot.

Note
KEYSTORE_LOOKUP_TYPE_ABSOLUTE will eventually be depreciated. It is therefore recommended to abstain from its usage.
KEYSTORE_LOOKUP_TYPE_RELATIVE 

Lookup relative to UUID.If there are more than one keys present for a given UUID, clients can use this lookup to get Nth key from the keyslots that they are allowed to access (UUID is an access control field).

KEYSTORE_LOOKUP_TYPE_BY_ID 

Lookup by entry ID.

Each Key is uniquely identified by (UUID, Entry ID) tuple. Client can use this lookup if it knows the exact tuple to access.

Note
Not supported by TOS OEM Keystore Service

Definition at line 3053 of file nv_te_cryptographic_constants.h.

◆ NV_TE_KeystoreServiceOperation

enum NV_TE_KeystoreServiceOperation

Defines TOS OEM Keystore Service trusted application commandIDs available to clients.

Enumerator
KEYSTORE_SERVICE_PING 

Description

Command to ping and check response from OEM Keystore Service.

To check if call is going into OEM Keystore service successfully, ie, test the reach-ability of OEM Keystore service.

Parameters
[in]params[0]NONE
[in]params[1]NONE
[in]params[2]NONE
[in]params[3]NONE
Returns
TEE_SUCCESS If successful.
TEE_ERROR_BAD_PARAMETERS If invalid parameter is passed.
TEE_ERROR_BAD_STATE If OEM Keystore service is not initialized.
KEYSTORE_SERVICE_GET_KEY 

Description

Command to return a key in plaintext format.

Get key material in plain text format in the caller provided buffer, corresponding to the requested key entry index and lookup type, after authenticating the access based on UUID of requesting TA and guest virtual machine number.

Parameters
[in]params[0].value.aIndex of the requested key entry
[in]params[0].value.bLookup type to use while searching for key entry.
KEYSTORE_LOOKUP_TYPE_ABSOLUTE means treat key entry Index as absolute index from the start of EKS payload.
KEYSTORE_LOOKUP_TYPE_RELATIVE means treat key entry Index as index within the set of key entries having same matching caller's TA UUID.
[in]params[1].value.aGuest Virtual Machine ID.
[in]params[2].memref.bufferOn success, shall contain requested key material.
[in,out]params[2].memref.sizeShall contain size of input buffer and on successfull return shall contain size of copied key material.
Returns
TEE_SUCCESS Success
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key entry access denied because of permission check failure or internal key retrieval, validation error.
TEE_ERROR_SHORT_BUFFER Caller supplied keyBufferSize is less.
KEYSTORE_SERVICE_GET_KEY_ATTRIBUTE 

Description

Command to return attribute of a key.

Gets key material attribute corresponding to the key entry index and lookup type, after authenticating the access based on UUID of requesting TA and guest virtual machine number.

Parameters
[in]params[0].value.aIndex of the requested key entry.
[in]params[0].value.bLookup type to use while searching for key entry.
KEYSTORE_LOOKUP_TYPE_ABSOLUTE means treat key entry Index as absolute index from the start of EKS payload.
KEYSTORE_LOOKUP_TYPE_RELATIVE means treat key entry Index as index within the set of key entries having same matching caller's TA UUID.
[in]params[1].value.aGuest Virtual Machine ID.
[in]params[2].value.aAttribute type requested.
KEYSTORE_KEY_ATTRIBUTE_SIZE means that request is for retrieving encrypted key material size.
[out]params[3].value.aOn success, shall contain requested attribute value.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key entry access denied because of permission check failure or internal key retrieval, validation error.
KEYSTORE_SERVICE_PKCS11_LOAD_AES_KEY 

Description

Command to Load PKCS11 symmetric object into AES Keyslot.

Gets PKCS11 Symmetric object corresponding to the key entry index based on absolute lookup type, after authenticating the access based on guest virtual machine number. Validates the key material of the symmetric object and loads into AES Keyslot.

Parameters
[in]params[0].value.aHandle of the AES key to be loaded.
[in]params[1].value.aMechanism to be used by this keyslot. Type: PKCS11_CK_MECHANISM_TYPE
[in]params[1].value.bPurpose for loading the key into keyslot. Type: KeyPurpose
[out]params[3].value.aOn success, shall contain requested keyslot handle.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval, validation error.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_NOT_SUPPORTED if provided mechanism or purpose is not supported by the key
TEE_ERROR_OVERFLOW if no keyslots allocated to guest are free.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_LOAD_AES_KEY 

Description

Command to Load Persistent PKCS11 symmetric object from the secure storage into AES Keyslot.

Gets PKCS11 Symmetric object corresponding to the key object handle and validates the key material of the symmetric object and loads into AES Keyslot.

Parameters
[in]params[0].value.aHandle of the AES key to be loaded.
[in]params[1].value.aMechanism to be used by this keyslot. Type: PKCS11_CK_MECHANISM_TYPE
[in]params[1].value.bPurpose for loading the key into keyslot. Type: KeyPurpose
[out]params[3].value.aOn success, shall contain requested keyslot handle.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval, validation error.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_NOT_SUPPORTED if provided mechanism or purpose is not supported by the key
TEE_ERROR_OVERFLOW if no keyslots allocated to guest are free.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_RELEASE_AES_KEYSLOT 

Description

Command to release AES Keyslot when a Persistent PKCS11 Symmetric object is loaded into Keyslot using KEYSTORE_SERVICE_PKCS11_PERSISTENT_LOAD_AES_KEY command.

Performs a check if the input Keyslot handle is valid and already loaded. Releases the keyslot, if true and return error if false.

Parameters
[in]params[0].value.aKeySlot Handle to be released.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ITEM_NOT_FOUND if Keyslot handle is not found.
KEYSTORE_SERVICE_PKCS11_RELEASE_AES_KEYSLOT 

Description

Command to release AES Keyslot when a PKCS11 Symmetric object is loaded into Keyslot using KEYSTORE_SERVICE_PKCS11_LOAD_AES_KEY command.

Performs a check if the input Keyslot handle is valid and already loaded. Releases the keyslot, if true and return error if false.

Parameters
[in]params[0].value.aKeySlot Handle to be released.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ITEM_NOT_FOUND if Keyslot handle is not found.
KEYSTORE_SERVICE_PKCS11_GET_KEY_OBJ_METADATA 

Description

Get PKCS11 object metadata.

Gets PKCS11 object metadata. The PKCS11 object type from the metadata indicates the type of object like a secret key object or a public key object and it must be used to interpret the returned metadata.

Parameters
[in]params[0].value.aKeyHandle of the key object returned by KEYSTORE_SERVICE_PKCS11_* APIs.
[out]params[1].memref.bufferPointer to the metadata struct.
[in]params[1].memref.sizeSize of buffer (uint32_t).
[in]params[2]NONE
[in]params[3]NONE
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval.
KEYSTORE_SERVICE_PKCS11_GENERATE_AES_KEY 

Description

Command to generate new PKCS11 Symmetric Key Objects

This command helps to generate new PKCS11 Symmetric key objects in TZRAM. These keys are ephemeral in nature because they reside in secure memory and not persistent across system boots. This command generates new key based on PKCS11 Symmetric Key template from non secure client which is provided as input parameter. The following metadata fields of template are validated before generating new secret key:

  1. Key Metdata which includes key type, key purpose and mechanisms, key sensitivity, key extractability.
  2. Object Type, Structure Version.
  3. Checks if ObjectId is unique.
Parameters
[in]params[0].memref.bufferPointer to Symmetric Key template.
[in]params[0].memref.sizeSize of Symmetric Key template.
[out]params[3].value.aOn success, shall contain Key handle to new object.
Returns
TEE_SUCCESS if Key generaion is Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function or if template validation fails.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_GENERIC if Key generation fails
TEE_ERROR_OUT_OF_MEMORY if TZRAM Symmetric key entries are full
KEYSTORE_SERVICE_PKCS11_DELETE_KEY 

Description

Command to delete ephemeral PKCS11 key objects created by key generate commands.

Performs a look up in available PKSC11 Objects in TZRAM based on input key handle and deletes the Key Entry.

Parameters
[in]params[0].value.aValid Key handle to delete. Key Handle must be from the prior successfull Key generation command
Returns
TEE_SUCCESS if Key deletion is successfull.
TEE_ERROR_BAD_PARAMETERS if Key handle is invalid.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure.
TEE_ERROR_ITEM_NOT_FOUND if object is not found.
KEYSTORE_SERVICE_PKCS11_DERIVE_AES_KEY 

Description

Command to derive AES Key based on exisiting deriving AES Key.

Finds the deriving key provided based on key handle and loads it into AES Keyslot after verifying if the key can be used for key derivation. Derives new key material by invoking NIST SP800-108 compliant derivation on the supplied label and context data. A new key is then derived using the provided Symmetric Key template as input along with derived key material. The following metadata fields of template are validated before generating new secret key:

  1. Key Metdata which includes key type, key purpose and mechanisms, key sensitivity, key extractability.
  2. Object Type, Structure Version.
  3. Checks if ObjectId is unique.
Parameters
[in]params[0].value.aHandle for the deriving Key
[out]params[0].value.bOn success, contains derived keyhandle
[in]params[1].memref.bufferPointer to PKCS symmetric key metadata template structure
[in]params[1].memref.sizeSize of symmteric obj metadata
[in]params[2].memref.bufferPointer to buffer containing label
[in]params[2].memref.sizeSize of the label string
[in]params[3].memref.bufferPointer to buffer containing context
[in]params[3].memref.sizeSize of the context string
Return values
TEE_SUCCESSSuccess.
TEE_ERROR_BAD_PARAMETERSBad parameters to the function.
TEE_ERROR_ACCESS_DENIEDKey access is denied because of permission check failure or internal key retrieval, validation error.
TEE_ERROR_BAD_STATEif PKCS11KS state cannot support the command.
TEE_ERROR_ITEM_NOT_FOUNDif deriving key is not found.
TEE_ERROR_GENERICif any generic error.
KEYSTORE_SERVICE_PKCS11_UNWRAP_AES_KEY 

Description

Command to unwrap an AES key using AES-CCM from exisiting AES key.

Unwraps an AES key from another AES key using AES-CCM. Input parameters needed for unwrapping a key are its tag length, nonce, wrapped key material and AAD(Additional Authentication Data). Below are the details:

  1. TAG Length: This is fixed as 16 and is not provided as input.
  2. NONCE: Nonce and nonce size are provided as one of the input params. Size of nonce is fixed as 12 bytes.
  3. WRAPPED KEY: Wrapped data is provided as input via 'encKeyData' field of unwrapped key template.
  4. TAG: This is also know as MAC and is length 16 bytes. Passed via 'macData' field of unwrapped key template.
  5. AAD: The entire metadata template excluding IV, Key and MAC Fields is considered as AAD(Additional Authentication Data) and is used for authenticating the key during unwrapping by the Keystore service.

Following metadata fields of unwrapped key are validated before key unwrapping:

  1. Key Metadata which includes key type, key purpose and mechanisms, key sensitivity, key extractability.
  2. Object Type, Structure Version.
  3. Checks if ObjectId is unique. NOTE: Fields of Unwrapped key Template should contain Wrapped key metadata, wrapped key material and TAG.
Parameters
[in]params[0].value.aHandle for the unwrapping key
[in]params[1].memref.bufferPointer to nonce buffer.
[in]params[1].memref.sizeSize of the nonce buffer.
[in]params[2].memref.bufferPointer to PKCS symmetric key metadata template structure
[in]params[2].memref.sizeSize of symmteric obj metadata
[out]params[3].value.aOn success, contains unwrapped keyhandle
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_ITEM_NOT_FOUND if unwrapping key is not found.
TEE_ERROR_GENERIC if any AAD authentication fails or
unwrapping fails.
KEYSTORE_SERVICE_PKCS11_COPY_AES_KEY 

Description

Command to make a copy of an existing AES key object.

Finds a source key based on the provided key handle and creates a copy of it with the provided unique object ID and label (optional). The label is set for the new copied object, only if the source object is modifiable.

Parameters
[in]params[0].value.aHandle of the source key to be copied.
[in]params[1].memref.bufferPointer to unique object ID buffer for new copy of the key.
[in]params[1].memref.sizeSize of buffer having object ID
[in]params[2].memref.bufferOptional Parameter.Pointer to buffer having label for new copy of the key.
[in]params[2].memref.sizeSize of buffer having label
[out]params[3].value.aOn success, contains copied keyhandle.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_ITEM_NOT_FOUND if source key is not found.
TEE_ERROR_GENERIC if any generic error.
TEE_ERROR_NOT_SUPPORTED if object cannot be copied.
KEYSTORE_SERVICE_PKCS11_SET_KEY_OBJ_ID 

Set PKCS11 object identifier. 

Sets a new object identifier(ID) for a key object specified by
the key handle.

\param[in] params[0].value.a: KeyHandle of the key object returned by
           KEYSTORE_SERVICE_PKCS11_* APIs.
\param[in] params[1].memref.buffer: Pointer to object Id buffer.
\param[in] params[1].memref.size: Size of buffer containing object id.
\param[in] params[2] NONE
\param[in] params[3] NONE

\return TEE_SUCCESS Success in updating object identifier.
\return TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
\return TEE_ERROR_ACCESS_DENIED Key access is denied because of
        permission check failure or internal key retrieval.
KEYSTORE_SERVICE_PKCS11_SET_KEY_OBJ_LABEL 

Description

Set PKCS11 object label.

Sets a new object label for a key object specified by the key handle.

Parameters
[in]params[0].value.aKeyHandle of the key object returned by KEYSTORE_SERVICE_PKCS11_* APIs.
[in]params[1].memref.bufferPointer to object label buffer.
[in]params[1].memref.sizeSize of buffer containing object label.
[in]params[2]NONE
[in]params[3]NONE
Returns
TEE_SUCCESS Success in updating object label.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval.
KEYSTORE_SERVICE_PKCS11_SECURE_STORAGE_GET_STATE 

Description

Get the state of secure storage.

Get the state of secure storage.If secure storage is present read object with invalid object Id to confirm if secure storage is functional as well.

Parameters
[out]params[0].value.aPKS_SECURE_STORAGE_FUNCTIONAL secure storage is functional. PKS_SECURE_STORAGE_PRESENT secure storage is present. PKS_SECURE_STORAGE_NOT_PRESENT secure storage is not. present.
[in]params[1]NONE
[in]params[2]NONE
[in]params[3]NONE
Returns
TEE_SUCCESS Success in getting the state of secure storage.
TEE_ERROR_BAD_PARAMETERS bad parameters to the function.
KEYSTORE_SERVICE_PKCS11_SECURE_STORAGE_RESET_FILESYSTEM 

Description

Resets Secure Storage FileSystem.

Resets the Secure Storage FileSystem. This command is available only on debug overlay and works on unfused devices. If secure NOR is not present this command isn't supported.

Parameters
[in]params[0].value.aWhether to do an erase of the NOR flash. Valid range: all unsigned int. zero (false) The cache is cleared in filesystem and reloads the objects from flash mimicking power reset. non-zero (true) The flash will reset to a state as if it was never used by erasing all the metadata on the flash.
[in]params[1]NONE
[in]params[2]NONE
[in]params[3]NONE
Returns
TEE_SUCCESS Success in resetting the secure storage filesystem.
TEE_ERROR_BAD_PARAMETERS bad parameters to the function
TEE_ERROR_ACCESS_DENIED access is denied because of permission check failure
TEE_ERROR_GENERIC The file system cannot be reset because of error returned from flash
TEE_ERROR_BAD_STATE if securestorage session is not established
TEE_ERROR_ITEM_NOT_FOUND if secure nor is not available
TEE_ERROR_NOT_SUPPORTED if reset fs stubbed out
KEYSTORE_SERVICE_PKCS11_PERSISTENT_UNWRAP_AES_KEY 

Command to unwrap an AES key using AES-CCM from exisiting persistent AES key and write to secure storage.

Unwraps an AES key from another AES key using AES-CCM. Input parameters needed for unwrapping a key are its tag length, nonce, wrapped key material and AAD(Additional Authentication Data). Below are the details:

  1. TAG Length: This is fixed as 16 and is not provided as input.
  2. NONCE: Nonce and nonce size are provided as one of the input params. Size of nonce is fixed as 12 bytes.
  3. WRAPPED KEY: Wrapped data is provided as input via 'encKeyData' field of unwrapped key template.
  4. TAG: This is also know as MAC and is length 16 bytes. Passed via 'macData' field of unwrapped key template.
  5. AAD: The entire metadata template excluding IV, Key and MAC Fields is considered as AAD(Additional Authentication Data) and is used for authenticating the key during unwrapping by the Keystore service.

Following metadata fields of unwrapped key are validated before key unwrapping:

  1. Key Metadata which includes key type, key purpose and mechanisms, key sensitivity, key extractability.
  2. Object Type, Structure Version.
  3. Checks if ObjectId is unique. NOTE: Fields of Unwrapped key Template should contain Wrapped key metadata, wrapped key material and TAG.
Parameters
[in]params[0].value.aHandle for the unwrapping key. Should be a persistent key handle.
[in]params[1].memref.bufferPointer to nonce buffer.
[in]params[1].memref.sizeSize of the nonce buffer.
[in]params[2].memref.bufferPointer to PKCS symmetric key metadata template structure
[in]params[2].memref.sizeSize of symmteric obj metadata
[out]params[3].value.aOn success, contains unwrapped keyhandle
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_ITEM_NOT_FOUND if unwrapping key is not found
TEE_ERROR_GENERIC if any AAD authentication fails or unwrapping fails
TEE_ERROR_NOT_IMPLEMENTED secure storage is not functional.
TEE_ERROR_BAD_FORMAT secure storage session is not established.
Return values
TEE_ERROR_STORAGE_NO_SPACEall metadata slot or unallocated object slot has reached MAX_ERASE_COUNT. In former situation, the secure NOR becomes only readable but not writable.
Returns
TEE_ERROR_COMMUNICATION if non-security related error in the NOR Flash Interface unit, including timeouts, SPI error, MX packet CRC check
TEE_ERROR_COMMUNICATION if bad block is found during write to flash.
Return values
TEE_ERROR_SECURITYif a security-related error in the NOR Flash Interface unit, including MxArmor reported error during security field command or failed CCM authentication.
TEE_ERROR_EXCESS_DATAif max number of objects in secure storage is reached.
KEYSTORE_SERVICE_PKCS11_CREATE_RSA_PUB_KEY 

Command to create a new PKCS11 RSA public Key Object. 

This command helps to generate new PKCS11 RSA public key object
in TZRAM. These keys are ephemeral in nature because it resides in
secure memory and is not persistent across system boots. This command
generates new key based on PKCS11 RSA public key template from non secure
client which is provided as input parameter. The following metadata
fields of template are validated before generating new secret key:
PURPOSE, SEN, EXT, TST, LCL, KCV, DST, VERSION, OBJTYPE, NMECH, ID,
MECHANISMS and KEYSIZE

\param[in] params[0].memref.buffer: Pointer to RSA public Key template.
\param[in] params[0].memref.size: Size of RSA public Key template.
\param[out] params[3].value.a: On success, shall contain Key handle
                               to new object.

\return TEE_SUCCESS if Key creation is Success.
\return TEE_ERROR_BAD_PARAMETERS Bad parameters to the function
                                or if template validation fails.
\return TEE_ERROR_BAD_STATE if PKCS11KS state cannot support
        the command.
\return TEE_ERROR_GENERIC if Key handle generation fails
\return TEE_ERROR_OUT_OF_MEMORY if TZRAM RSA public key entries
        are full in the current session.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_LOOKUP_KEY 

Description

Command to Look up persistent objects based on object id.

Performs a look up in available persistent objects based on input object id and returns key handle and key object type.

Parameters
[in]params[0].memref.bufferPointer to object Id buffer.
[in]params[0].memref.sizeSize of buffer containing object id.
[out]params[3].value.aOn success, shall contain requested handle to object.
[out]params[3].value.bOn success, shall conatain the key object type.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval, validation error.
TEE_ERROR_BAD_STATE persistent objects were not loaded/ authenticated so keystore supports only ephemeral keys.
TEE_ERROR_ITEM_NOT_FOUND if object is not found
TEE_ERROR_NOT_IMPLEMENTED if secure storage is not functional.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_GET_KEY_OBJ_METADATA 

Description

Get PKCS11 persistent key object metadata.

Gets PKCS11 object metadata. The PKCS11 object type from the metadata indicates the type of object like a secret key object or a public key object and it must be used to interpret the returned metadata.

Parameters
[in]params[0].value.aKeyHandle of the persistent key object returned by KEYSTORE_SERVICE_PKCS11_PERSISTENT* APIs.
[out]params[1].memref.bufferPointer to the metadata struct.
[in]params[1].memref.sizeSize of buffer (uint32_t).
[in]params[2]NONE
[in]params[3]NONE
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval.
TEE_ERROR_NOT_IMPLEMENTED secure storage is not functional.
TEE_ERROR_ITEM_NOT_FOUND if the object associated with the handle is not found.
TEE_ERROR_BAD_STATE if keystore is in a bad state and doesn't support persistent key objects.
KEYSTORE_SERVICE_PKCS11_LOOKUP_KEY 

Description

Command to Look up PKSC11 key Object based on object id

Performs a look up in available PKSC11 key Objects based on input object id and returns handle and objType to object.

Parameters
[in]params[0].memref.bufferPointer to object Id buffer.
[in]params[0].memref.sizeSize of buffer containing object id.
[out]params[3].value.aOn success, shall contain requested handle to object. params[3].value.b: On success, shall contain requested objType to object.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval, validation error.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_ITEM_NOT_FOUND if object is not found.
KEYSTORE_SERVICE_PKCS11_LOAD_RSA_PUB_KEY 

Description

Command to Load PKCS11 RSA public key object into PKA1 Keyslot.

Gets PKCS11 RSA public key object corresponding to the key object handle, Validates the key object metadata, and loads into PKA1 Keyslot.

Parameters
[in]params[0].value.aHandle of the RSA public key to be loaded.
[in]params[1].value.aMechanism to be used by this keyslot. Type: PKCS11_CK_MECHANISM_TYPE
[in]params[1].value.bPurpose for loading the key into keyslot. Type: KeyPurpose
[out]params[3].value.aOn success, shall contain requested keyslot handle.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval, validation error.
TEE_ERROR_BAD_STATE if the PKCS11KS state cannot support the command.
TEE_ERROR_NOT_SUPPORTED if provided mechanism or purpose is not supported by the key
TEE_ERROR_OVERFLOW if no keyslots allocated to guest are free.
KEYSTORE_SERVICE_PKCS11_RELEASE_RSA_KEYSLOT 

Description

Command to release RSA Keyslot which was loaded with a PKCS11 RSA key object using KEYSTORE_SERVICE_PKCS11_LOAD_RSA_PUB_KEY command.

Performs a check if the input Keyslot handle is valid and already loaded. Releases the keyslot, if true and return error if false.

Parameters
[in]params[0].value.aKeySlot Handle to be released.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_STATE if the PKCS11KS state cannot support the command.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ITEM_NOT_FOUND if Keyslot handle is not found.
KEYSTORE_SERVICE_PKCS11_COPY_RSA_PUB_KEY 

Description

Command to make a copy of an existing RSA public key object.

Finds a source key based on the provided key handle and creates a copy of it with the provided unique object ID and label (optional). The label is set for the new copied object, only if the source object is modifiable.

Parameters
[in]params[0].value.aHandle of the source key to be copied.
[in]params[1].memref.bufferPointer to unique object ID buffer for new copy of the key.
[in]params[1].memref.sizeSize of buffer having object ID
[in]params[2].memref.bufferOptional Parameter.Pointer to buffer having label for new copy of the key.
[in]params[2].memref.sizeSize of buffer having label
[out]params[3].value.aOn success, contains copied keyhandle.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval.
TEE_ERROR_BAD_STATE if CryptoSession is not established.
TEE_ERROR_ITEM_NOT_FOUND if source key is not found.
TEE_ERROR_GENERIC if any generic error.
TEE_ERROR_NOT_SUPPORTED if object cannot be copied.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_LOAD_RSA_PUB_KEY 

Description

Command to Load PKCS11 Persistent RSA public key object into PKA1 Keyslot.

Gets the persistent RSA public key object corresponding to the key object handle, validates the key object metadata, and loads into PKA1 Keyslot.

Parameters
[in]params[0].value.aHandle of the Persistent RSA public key to be loaded.
[in]params[1].value.aMechanism to be used by this keyslot. Type: PKCS11_CK_MECHANISM_TYPE
[in]params[1].value.bPurpose for loading the key into keyslot. Type: KeyPurpose
[out]params[3].value.aOn success, shall contain requested keyslot handle.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval, validation error.
TEE_ERROR_BAD_STATE if the PKCS11KS state cannot support the command.
TEE_ERROR_NOT_SUPPORTED if provided mechanism or purpose is not supported by the key
TEE_ERROR_OVERFLOW if no keyslots allocated to guest are free.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_RELEASE_RSA_KEYSLOT 

Description

Command to release a RSA Keyslot which was loaded with a PKCS11 Persistent RSA key object using KEYSTORE_SERVICE_PKCS11_PERSISTENT_LOAD_RSA_PUB_KEY command.

Performs a check if the input Keyslot handle is valid and already loaded. Releases the keyslot, if true and return error if false.

Parameters
[in]params[0].value.aKeySlot Handle to be released.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_STATE if the PKCS11KS state cannot support the command.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ITEM_NOT_FOUND if Keyslot handle is not found.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_COPY_RSA_PUB_KEY 

Command to make a copy of an existing Persistent RSA public key object.

Finds a source key based on the provided key handle and creates a persistent copy of it with the provided unique object ID and label (optional). The label is set for the new copied object, only if the source object is modifiable.

Parameters
[in]params[0].value.aHandle of the source key to be copied.
[in]params[1].memref.bufferPointer to unique object ID buffer for new copy of the key.
[in]params[1].memref.sizeSize of buffer having object ID
[in]params[2].memref.bufferOptional Parameter.Pointer to buffer having label for new copy of the key.
[in]params[2].memref.sizeSize of buffer having label
[out]params[3].value.aOn success, contains copied keyhandle.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_ITEM_NOT_FOUND if source key is not found.
TEE_ERROR_GENERIC if any generic error.
TEE_ERROR_NOT_SUPPORTED if object cannot be copied.
TEE_ERROR_EXCESS_DATA if max number of objects in secure storage is reached.
TEE_ERROR_NOT_IMPLEMENTED if secure storage is not functional or not available.
Return values
TEE_ERROR_STORAGE_NO_SPACEall metadata slot or unallocated object slot has reached MAX_ERASE_COUNT. In former situation, the secure NOR becomes only readable but not writable.
Returns
TEE_ERROR_COMMUNICATION if non-security related error in the NOR Flash Interface unit, including timeouts, SPI error, MX packet CRC check, if bad block is found during write to flash.
Return values
TEE_ERROR_SECURITYif a security-related error in the NOR Flash Interface unit, including MxArmor reported error during security field command or failed CCM authentication.
KEYSTORE_SERVICE_PKCS11_CREATE_ECC_PUB_KEY 

Command to create a new PKCS11 ECC public Key Object. 

This command helps to generate new PKCS11 ECC public key object
in TZRAM. These keys are ephemeral in nature because it resides in
secure memory and is not persistent across system boots. This command
generates new key based on PKCS11 ECC public key template from non secure
client which is provided as input parameter. The following metadata
fields of template are validated before generating new secret key:
PURPOSE, SEN, EXT, TST, LCL, KCV, DST, VERSION, OBJTYPE, NMECH, ID,
MECHANISMS, GENMECHANISM and KEYSIZE

\param[in] params[0].memref.buffer: Pointer to ECC public Key template.
\param[in] params[0].memref.size: Size of ECC public Key template.
\param[out] params[3].value.a: On success, shall contain Key handle
                               to new object.

\return TEE_SUCCESS if Key creation is Success.
\return TEE_ERROR_BAD_PARAMETERS Bad parameters to the function
                                or if template validation fails.
\return TEE_ERROR_BAD_STATE if PKCS11KS state cannot support
        the command.
\return TEE_ERROR_GENERIC if Key handle generation fails
\return TEE_ERROR_OUT_OF_MEMORY if TZRAM ECC public key entries
        are full in the current session.
KEYSTORE_SERVICE_PKCS11_LOAD_ECC_PUB_KEY 

Description

Command to Load PKCS11 ECC public key object into PKA1 Keyslot.

Gets PKCS11 ECC public key object corresponding to the key handle. Validates the key object metadata, and loads into PKA1 Keyslot.

Parameters
[in]params[0].value.aHandle of the ECC public key to be loaded.
[in]params[1].value.aMechanism to be used by this keyslot. Type: PKCS11_CK_MECHANISM_TYPE
[in]params[1].value.bPurpose for loading the key into keyslot. Type: KeyPurpose
[out]params[3].value.aOn success, shall contain requested keyslot handle.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval, validation error.
TEE_ERROR_BAD_STATE if the PKCS11KS state cannot support the command.
TEE_ERROR_NOT_SUPPORTED if provided mechanism or purpose is not supported by the key
TEE_ERROR_OVERFLOW if no keyslots allocated to guest are free.
KEYSTORE_SERVICE_PKCS11_RELEASE_ECC_KEYSLOT 

Description

Command to release ECC Keyslot which was loaded with a PKCS11 ECC key object using KEYSTORE_SERVICE_PKCS11_LOAD_ECC_PUB_KEY command.

Performs a check if the input Keyslot handle is valid and already loaded. Releases the keyslot, if true and return error if false.

Parameters
[in]params[0].value.aKeySlot Handle to be released.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_STATE if the PKCS11KS state cannot support the command.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ITEM_NOT_FOUND if Keyslot handle is not found.
KEYSTORE_SERVICE_PKCS11_COPY_ECC_PUB_KEY 

Command to make a copy of an existing ECC Public key object. 

Finds a source key based on the provided key handle and creates a copy
of it with the provided unique object ID and label (optional). The label
is set for the new copied object, only if the source object is modifiable.

\param[in]  params[0].value.a: Handle of the source key to be copied.
\param[in]  params[1].memref.buffer: Pointer to unique object ID buffer
                              for new copy of the key.
\param[in]  params[1].memref.size: Size of buffer having object ID
\param[in]  params[2].memref.buffer: Optional Parameter.Pointer to
                        buffer having label for new copy of the key.
\param[in]  params[2].memref.size: Size of buffer having label
\param[out] params[3].value.a: On success, contains copied keyhandle.

\return TEE_SUCCESS Success.
\return TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
\return TEE_ERROR_ACCESS_DENIED Key access is denied because of
        permission check failure or internal key retrieval.
\return TEE_ERROR_BAD_STATE if CryptoSession is not established.
\return TEE_ERROR_ITEM_NOT_FOUND if source key is not found.
\return TEE_ERROR_GENERIC if any generic error.
\return TEE_ERROR_NOT_SUPPORTED if object cannot be copied.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_COPY_ECC_PUB_KEY 

Command to make a copy of an existing Persistent ECC Public key object.

Finds a source key based on the provided key handle and creates a persistent copy of it with the provided unique object ID and label (optional). The label is set for the new copied object, only if the source object is modifiable.

Parameters
[in]params[0].value.aHandle of the source key to be copied.
[in]params[1].memref.bufferPointer to unique object ID buffer for new copy of the key.
[in]params[1].memref.sizeSize of buffer having object ID
[in]params[2].memref.bufferOptional Parameter.Pointer to buffer having label for new copy of the key.
[in]params[2].memref.sizeSize of buffer having label
[out]params[3].value.aOn success, contains copied keyhandle.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_ITEM_NOT_FOUND if source key is not found.
TEE_ERROR_GENERIC if any generic error.
TEE_ERROR_NOT_SUPPORTED if object cannot be copied.
TEE_ERROR_EXCESS_DATA if max number of objects in secure storage is reached.
TEE_ERROR_NOT_IMPLEMENTED if secure storage is not functional or not available.
Return values
TEE_ERROR_STORAGE_NO_SPACEall metadata slot or unallocated object slot has reached MAX_ERASE_COUNT. In former situation, the secure NOR becomes only readable but not writable.
Returns
TEE_ERROR_COMMUNICATION if non-security related error in the NOR Flash Interface unit, including timeouts, SPI error, MX packet CRC check, if bad block is found during write to flash.
Return values
TEE_ERROR_SECURITYif a security-related error in the NOR Flash Interface unit, including MxArmor reported error during security field command or failed CCM authentication.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_LOAD_ECC_PUB_KEY 

Description

Command to Load PKCS11 Persistent ECC public key object into PKA1 Keyslot.

Gets the persistent ECC public key object corresponding to the key object handle, validates the key object metadata, and loads into PKA1 Keyslot.

Parameters
[in]params[0].value.aHandle of the Persistent ECC public key to be loaded.
[in]params[1].value.aMechanism to be used by this keyslot. Type: PKCS11_CK_MECHANISM_TYPE
[in]params[1].value.bPurpose for loading the key into keyslot. Type: KeyPurpose
[out]params[3].value.aOn success, shall contain requested keyslot handle.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval, validation error.
TEE_ERROR_BAD_STATE if the PKCS11KS state cannot support the command.
TEE_ERROR_NOT_SUPPORTED if provided mechanism or purpose is not supported by the key
TEE_ERROR_OVERFLOW if no keyslots allocated to guest are free.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_RELEASE_ECC_KEYSLOT 

Description

Command to release a ECC Keyslot which was loaded with a PKCS11 Persistent ECC key object using KEYSTORE_SERVICE_PKCS11_PERSISTENT_LOAD_ECC_PUB_KEY command.

Performs a check if the input Keyslot handle is valid and already loaded. Releases the keyslot, if true and return error if false.

Parameters
[in]params[0].value.aKeySlot Handle to be released.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_STATE if the PKCS11KS state cannot support the command.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ITEM_NOT_FOUND if Keyslot handle is not found.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_GENERATE_AES_KEY 

Description

Command to generate new PKCS11 Symmetric Key Objects and store them in secure storage.

This command helps to generate new PKCS11 Symmetric key objects in the secure storage. These keys are persistent across system reboots. This command generates a new key based on PKCS11 Symmetric Key metadata provided by a non secure client as the input to the command. The following fields of metadata are validated before generating a new symmetric key:

  1. Key Metadata which includes key type, key purpose and mechanisms, key sensitivity, key extractability.
  2. Object Type, Structure Version.
  3. Checks if ObjectId is unique in the current session of ephemeral and persistent key objects. Upon successfull generation of symmetric key, the key object is stored in secure storage.
Parameters
[in]params[0].memref.bufferPointer to Symmetric Key metadata buffer.
[in]params[0].memref.sizeSize of Symmetric Key metadata.
[out]params[3].value.aOn success, shall contain handle to new key object.
Returns
TEE_SUCCESS if Key generaion is Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function or if key object metadata validation fails.
TEE_ERROR_BAD_STATE if PKCS11KS state is in a bad state so only persistent commands are not supported.
TEE_ERROR_GENERIC if crypto operation fails.
TEE_ERROR_OUT_OF_MEMORY if max key count has reached.
TEE_ERROR_EXCESS_DATA if max number of objects in secure storage is reached.
TEE_ERROR_NOT_IMPLEMENTED if secure storage is not functional or not available.
Return values
TEE_ERROR_STORAGE_NO_SPACEall metadata slot or unallocated object slot has reached MAX_ERASE_COUNT. In former situation, the secure NOR becomes only readable but not writable.
Returns
TEE_ERROR_COMMUNICATION if non-security related error in the NOR Flash Interface unit, including timeouts, SPI error, MX packet CRC check, if bad block is found during write to flash.
Return values
TEE_ERROR_SECURITYif a security-related error in the NOR Flash Interface unit, including MxArmor reported error during security field command or failed CCM authentication.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_SET_KEY_OBJ_ID 

Set PKCS11 persistent object identifier. 

Sets a new object identifier(ID) for a persistent key object specified
by the key handle.

\param[in] params[0].value.a: KeyHandle of the key object returned by
           KEYSTORE_SERVICE_PKCS11_PERSISTENT* APIs.
\param[in] params[1].memref.buffer: Pointer to object Id buffer.
\param[in] params[1].memref.size: Size of buffer containing object id.
\param[in] params[2] NONE
\param[in] params[3] NONE

\return TEE_SUCCESS Success in updating object identifier.
\return TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
\return TEE_ERROR_ACCESS_DENIED Key access is denied because of
        permission check failure or internal key retrieval.
\return TEE_ERROR_ITEM_NOT_FOUND if key based on key handle isn't found.
\return TEE_ERROR_GENERIC if MAC computation failed.
\return TEE_ERROR_NOT_IMPLEMENTED secure storage is not functional.
\retval TEE_ERROR_STORAGE_NO_SPACE all metadata slot or unallocated
        object slot has reached MAX_ERASE_COUNT. In former situation,
        the secure NOR becomes only readable but not writable.
\return TEE_ERROR_COMMUNICATION if non-security related error in the
        NOR Flash Interface unit, including timeouts, SPI error,
        MX packet CRC check
\return TEE_ERROR_COMMUNICATION if bad block is found during write
        to flash.
\retval TEE_ERROR_SECURITY if a security-related error in the NOR
        Flash Interface unit, including MxArmor reported error during
        security field command or failed CCM authentication.
\retval TEE_ERROR_NO_DATA if there is no secure storage object id
        associated with key handle.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_SET_KEY_OBJ_LABEL 

Set PKCS11 persistent object label. 

Sets a new object label for a persistent key object specified
by the key handle.

\param[in] params[0].value.a: KeyHandle of the key object returned by
           KEYSTORE_SERVICE_PKCS11_PERSISTENT* APIs.
\param[in] params[1].memref.buffer: Pointer to object label buffer.
\param[in] params[1].memref.size: Size of buffer containing
                                  object label.
\param[in] params[2] NONE
\param[in] params[3] NONE

\return TEE_SUCCESS Success in updating object label.
\return TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
\return TEE_ERROR_ACCESS_DENIED Key access is denied because of
        permission check failure or internal key retrieval.
\return TEE_ERROR_ITEM_NOT_FOUND if key based on key handle isn't found.
\return TEE_ERROR_GENERIC if MAC computation failed.
\return TEE_ERROR_NOT_IMPLEMENTED secure storage is not functional.
\retval TEE_ERROR_STORAGE_NO_SPACE all metadata slot or unallocated
        object slot has reached MAX_ERASE_COUNT. In former situation,
        the secure NOR becomes only readable but not writable.
\return TEE_ERROR_COMMUNICATION if non-security related error in the
        NOR Flash Interface unit, including timeouts, SPI error,
        MX packet CRC check
\return TEE_ERROR_COMMUNICATION if bad block is found during write
        to flash.
\retval TEE_ERROR_SECURITY if a security-related error in the NOR
        Flash Interface unit, including MxArmor reported error during
        security field command or failed CCM authentication.
\retval TEE_ERROR_NO_DATA if there is no secure storage object id
        associated with key handle.
KEYSTORE_SERVICE_PKCS11_INIT_KEYSTORE 

Command to initialize the keystore.

This command must be invoked before invoking any other PKCS11 command. API Group: Initialization

This command triggers authentication of all the persistent key objects and reports a success or failure code based on the result.

Parameters
[in]params[0]NONE
[in]params[1]NONE
[in]params[2]NONE
[in]params[3]NONE
Return values
TEE_SUCCESSIndicates that the keystore is authenticated and ready to be used.
TEE_ERROR_BAD_PARAMETERSBad parameters to the function. The command must be invoked again with correct parameters.
TEE_ERROR_BAD_STATEIndicates that there is a problem with the keystore and none of the persistent key object functionality will be available to the application. Epheremal objects shall continue to work as expected.
TEE_ERROR_NOT_IMPLEMENETEDIndicates the secure storage isn't functional on the platform.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_COPY_AES_KEY 

Description

Command to make a copy of an existing persistent AES key object.

Finds a source key based on the provided key handle and creates a copy of it with the provided unique object ID and label (optional). The label is set for the new copied object, only if the source object is modifiable.

Parameters
[in]params[0].value.aHandle of the source key to be copied.
[in]params[1].memref.bufferPointer to unique object ID buffer for new copy of the key.
[in]params[1].memref.sizeSize of buffer having object ID
[in]params[2].memref.bufferOptional Parameter.Pointer to buffer having label for new copy of the key.
[in]params[2].memref.sizeSize of buffer having label
[out]params[3].value.aOn success, contains copied keyhandle.
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function, source key not copyable/modifiable, object Id is not unique.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_ITEM_NOT_FOUND if source key is not found.
TEE_ERROR_GENERIC if crypto operation failed.
TEE_ERROR_EXCESS_DATA if max number of objects in secure storage is reached.
TEE_ERROR_NOT_IMPLEMENTED if secure storage is not functional or not available.
Return values
TEE_ERROR_STORAGE_NO_SPACEall metadata slot or unallocated object slot has reached MAX_ERASE_COUNT. In former situation, the secure NOR becomes only readable but not writable.
Returns
TEE_ERROR_COMMUNICATION if non-security related error in the NOR Flash Interface unit, including timeouts, SPI error, MX packet CRC check, if bad block is found during write to flash.
Return values
TEE_ERROR_SECURITYif a security-related error in the NOR Flash Interface unit, including MxArmor reported error during security field command or failed CCM authentication.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_DELETE_KEY 

Description

Command to delete persistent PKCS11 key objects created by key generate/unwrap commands.

Performs a look up in the available persistent PKSC11 Objects based on the input key handle and deletes the key object from the PKCS11 keystore and the the secure store.

Parameters
[in]params[0].value.aValid Key handle to delete. Key Handle must be from the prior successful Key generation/unwrap command
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_ITEM_NOT_FOUND if unwrapping key is not found
TEE_ERROR_GENERIC if any AAD authentication fails or unwrapping fails
TEE_ERROR_NOT_IMPLEMENTED secure storage is not functional.
TEE_ERROR_BAD_FORMAT secure storage session is not established.
Return values
TEE_ERROR_STORAGE_NO_SPACEall metadata slot or unallocated object slot has reached MAX_ERASE_COUNT. In former situation, the secure NOR becomes only readable but not writable.
Returns
TEE_ERROR_COMMUNICATION if non-security related error in the NOR Flash Interface unit, including timeouts, SPI error, MX packet CRC check
TEE_ERROR_COMMUNICATION if bad block is found during write to flash.
Return values
TEE_ERROR_SECURITYif a security-related error in the NOR Flash Interface unit, including MxArmor reported error during security field command or failed CCM authentication.
TEE_ERROR_EXCESS_DATAif max number of objects in secure storage is reached.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_REQUEST_RW_ACCESS 

Description

Command to request persistent key permission PersistentKeyPerm::PKCS_PST_KEY_PERM_READ_WRITE

Parameters
None
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_ACCESS_DENIED if requesting is not from the privileged VM or other session requests already any persistent key permission.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_RELINQUISH_RW_ACCESS 

Description

Command to relinquish persistent key permission PersistentKeyPerm::PKCS_PST_KEY_PERM_READ_WRITE

Parameters
None
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_REQUEST_RO_ACCESS 

Description

Command to request persistent key permission PersistentKeyPerm::PKCS_PST_KEY_PERM_READ_ONLY

Parameters
None
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_ACCESS_DENIED if a session requests already permission PersistentKeyPerm::PKCS_PST_KEY_PERM_READ_WRITE.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_RELINQUISH_RO_ACCESS 

Description

Command to relinquish persistent key permission PersistentKeyPerm::PKCS_PST_KEY_PERM_READ_ONLY

Parameters
None
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
KEYSTORE_SERVICE_PKCS11_PERSISTENT_UNWRAP_RSA_PUB_KEY 

Command to unwrap an persistent RSA key and write to secure storage.

Unwraps and verifies RSA key object using AES-CCM. Input parameters needed are tag length, wrapped RSA key object metadata and keytag containing key information such as keysize, exponent, modulus and MAC Below are the details:

  1. TAG Length: This is fixed as 16 and is not provided as input.
  2. NONCE: Nonce and nonce size are provided as one of the input params. Size of nonce is fixed as 12 bytes.
  3. WRAPPED KEY: Wrapped data is provided as input.
  4. TAG: This is also know as MAC and is length 16 bytes. Passed via 'macData' field of unwrapped key template.
  5. AAD: The entire metadata template excluding keysize, exponent, modulus and MAC fields is considered as AAD (Additional Authentication Data) and is used for authenticating the key during unwrapping by the Keystore service.

Following metadata fields of unwrapped key are validated before key unwrapping:

  1. Key Metadata which includes key type, key purpose and mechanisms, key sensitivity, key extractability.
  2. Object Type, Structure Version.
  3. Checks if ObjectId is unique. NOTE: Fields of Unwrapped key Template should contain Wrapped key metadata, wrapped key material and TAG.
Parameters
[in]params[0].value.aHandle for the unwrapping key.
[in]params[1].memref.bufferPointer to nonce buffer.
[in]params[1].memref.sizeSize of the nonce buffer.
[in]params[2].memref.bufferPointer to PKCS RSA key metadata structure
[in]params[2].memref.sizeSize of RSA key obj metadata
[out]params[3].value.aOn success, contains unwrapped keyhandle
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_ITEM_NOT_FOUND if unwrapping key is not found
TEE_ERROR_GENERIC if any AAD authentication fails or unwrapping fails
TEE_ERROR_NOT_IMPLEMENTED secure storage is not functional.
TEE_ERROR_BAD_FORMAT secure storage session is not established.
Return values
TEE_ERROR_STORAGE_NO_SPACEall metadata slot or unallocated object slot has reached MAX_ERASE_COUNT. In former situation, the secure NOR becomes only readable but not writable.
Returns
TEE_ERROR_COMMUNICATION if non-security related error in the NOR Flash Interface unit, including timeouts, SPI error, MX packet CRC check
TEE_ERROR_COMMUNICATION if bad block is found during write to flash.
Return values
TEE_ERROR_SECURITYif a security-related error in the NOR Flash Interface unit, including MxArmor reported error during security field command or failed CCM authentication.
TEE_ERROR_EXCESS_DATAif max number of objects in secure storage is reached.
KEYSTORE_SERVICE_PKCS11_UNWRAP_RSA_PUB_KEY 

Command to unwrap an ephemeral RSA key and write to TZDRAM. 

Unwraps and verifies RSA key object using AES-CCM. Input parameters
needed are tag length, wrapped RSA key object metadata and keytag
containing key information such as keysize, exponent, modulus and MAC
Below are the details:
 1. TAG Length: This is fixed as 16 and is not provided as input.
 2. NONCE: Nonce and nonce size are provided as one of the input params.
           Size of nonce is fixed as 12 bytes.
 3. WRAPPED KEY: Wrapped data is provided as input.
 4. TAG: This is also know as MAC and is length 16 bytes.
         Passed via 'macData' field of unwrapped key template.
 5. AAD: The entire metadata template excluding keysize, exponent,
         modulus and MAC fields is considered as AAD (Additional
         Authentication Data) and is used for authenticating the
         key during unwrapping by the Keystore service.

Following metadata fields of unwrapped key are validated before
key unwrapping:
1. Key Metadata which includes key type, key purpose and mechanisms, key
   sensitivity, key extractability.
2. Object Type, Structure Version.
3. Checks if ObjectId is unique.
NOTE: Fields of Unwrapped key Template should contain Wrapped key metadata,
      wrapped key material and TAG.

\param[in]  params[0].value.a: Handle for the unwrapping key.
\param[in]  params[1].memref.buffer: Pointer to nonce buffer.
\param[in]  params[1].memref.size: Size of the nonce buffer.
\param[in]  params[2].memref.buffer: Pointer to PKCS RSA key
            metadata structure
\param[in]  params[2].memref.size: Size of RSA key obj metadata
\param[out] params[3].value.a: On success, contains unwrapped keyhandle

\return TEE_SUCCESS Success.
\return TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
\return TEE_ERROR_ACCESS_DENIED Key access is denied because of
        permission check failure or internal key retrieval.
\return TEE_ERROR_BAD_STATE if PKCS11KS state cannot support
        the command.
\return TEE_ERROR_ITEM_NOT_FOUND if unwrapping key is not found
\return TEE_ERROR_GENERIC if any AAD authentication fails or
        unwrapping fails
KEYSTORE_SERVICE_PKCS11_PERSISTENT_UNWRAP_ECC_PUB_KEY 

Command to unwrap a persistent ECC key and write to secure storage.

Unwraps and verifies ECC key using AES-CCM. Input parameters needed are tag length, wrapped ECC key object metadata and keytag containing key information such as x-coordinate, y-coordinate and MAC Below are the details:

  1. TAG Length: This is fixed as 16 and is not provided as input.
  2. NONCE: Nonce and nonce size are provided as one of the input params. Size of nonce is fixed as 12 bytes.
  3. WRAPPED KEY: Wrapped data is provided as input.
  4. TAG: This is also know as MAC and is length 16 bytes. Passed via 'macData' field of unwrapped key template.
  5. AAD: The entire metadata template excluding x-coordinate, y-coordinate and MAC fields is considered as AAD (Additional Authentication Data) and is used for authenticating the key during unwrapping by the Keystore service.

Following metadata fields of unwrapped key are validated before key unwrapping:

  1. Key Metadata which includes key type, key purpose and mechanisms, key sensitivity, key extractability.
  2. Object Type, Structure Version.
  3. Checks if ObjectId is unique. NOTE: Fields of Unwrapped key Template should contain Wrapped key metadata, wrapped key material and TAG.
Parameters
[in]params[0].value.aHandle for the unwrapping key.
[in]params[1].memref.bufferPointer to nonce buffer.
[in]params[1].memref.sizeSize of the nonce buffer.
[in]params[2].memref.bufferPointer to PKCS ECC key metadata structure
[in]params[2].memref.sizeSize of RSA key obj metadata
[out]params[3].value.aOn success, contains unwrapped keyhandle
Returns
TEE_SUCCESS Success.
TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
TEE_ERROR_ACCESS_DENIED Key access is denied because of permission check failure or internal key retrieval.
TEE_ERROR_BAD_STATE if PKCS11KS state cannot support the command.
TEE_ERROR_ITEM_NOT_FOUND if unwrapping key is not found
TEE_ERROR_GENERIC if any AAD authentication fails or unwrapping fails
TEE_ERROR_NOT_IMPLEMENTED secure storage is not functional.
Return values
TEE_ERROR_STORAGE_NO_SPACEall metadata slot or unallocated object slot has reached MAX_ERASE_COUNT. In former situation, the secure NOR becomes only readable but not writable.
Returns
TEE_ERROR_COMMUNICATION if non-security related error in the NOR Flash Interface unit, including timeouts, SPI error, MX packet CRC check, if bad block is found during write to flash.
Return values
TEE_ERROR_SECURITYif a security-related error in the NOR Flash Interface unit, including MxArmor reported error during security field command or failed CCM authentication.
TEE_ERROR_EXCESS_DATAif max number of objects in secure storage is reached.
KEYSTORE_SERVICE_PKCS11_UNWRAP_ECC_PUB_KEY 

Command to unwrap an ephemeral ECC key and write to TZDRAM. 

Unwrap and verify ECC key using AES-CCM. Input parameters
needed are tag length, wrapped RSA key object metadata and tag
containing key information such as x-coordinate, y-coordinate and MAC
Below are the details:
 1. TAG Length: This is fixed as 16 and is not provided as input.
 2. NONCE: Nonce and nonce size are provided as one of the input params.
           Size of nonce is fixed as 12 bytes.
 3. WRAPPED KEY: Wrapped data is provided as input.
 4. TAG: This is also know as MAC and is length 16 bytes.
         Passed via 'macData' field of unwrapped key template.
 5. AAD: The entire metadata template excluding x-coordinate,
         y-coordinate and MAC fields is considered as AAD (Additional
         Authentication Data) and is used for authenticating the
         key during unwrapping by the Keystore service.

Following metadata fields of unwrapped key are validated before
key unwrapping:
1. Key Metadata which includes key type, key purpose and mechanisms, key
   sensitivity, key extractability.
2. Object Type, Structure Version.
3. Checks if ObjectId is unique.
NOTE: Fields of Unwrapped key Template should contain Wrapped key metadata,
      wrapped key material and TAG.

\param[in]  params[0].value.a: Handle for the unwrapping key.
\param[in]  params[1].memref.buffer: Pointer to nonce buffer.
\param[in]  params[1].memref.size: Size of the nonce buffer.
\param[in]  params[2].memref.buffer: Pointer to PKCS ECC key
            metadata template structure
\param[in]  params[2].memref.size: Size of RSA key obj metadata
\param[out] params[3].value.a: On success, contains unwrapped keyhandle

\return TEE_SUCCESS Success.
\return TEE_ERROR_BAD_PARAMETERS Bad parameters to the function.
\return TEE_ERROR_ACCESS_DENIED Key access is denied because of
        permission check failure or internal key retrieval.
\return TEE_ERROR_BAD_STATE if PKCS11KS state cannot support
        the command.
\return TEE_ERROR_ITEM_NOT_FOUND if unwrapping key is not found
\return TEE_ERROR_GENERIC if any AAD authentication fails or
        unwrapping fails

Definition at line 1565 of file nv_te_cryptographic_constants.h.