le_iks_interface.h File Reference

#include "legato.h"
#include "le_iks_common.h"

Go to the source code of this file.

Typedefs

typedef void(* le_iks_DisconnectHandler_t) (void *)
 

Functions

void le_iks_ConnectService (void)
 
le_result_t le_iks_TryConnectService (void)
 
LE_FULL_API void le_iks_SetServerDisconnectHandler (le_iks_DisconnectHandler_t disconnectHandler, void *contextPtr)
 
void le_iks_DisconnectService (void)
 
le_result_t le_iks_SetModuleId (const char *LE_NONNULL idPtr, uint64_t keyRef)
 
le_result_t le_iks_GetModuleId (char *idPtr, size_t idPtrSize)
 
le_result_t le_iks_DeleteModuleId (const uint8_t *authCmdPtr, size_t authCmdSize)
 
uint64_t le_iks_GetKey (const char *LE_NONNULL keyId)
 
uint64_t le_iks_CreateKey (const char *LE_NONNULL keyId, le_iks_KeyUsage_t keyUsage)
 
uint64_t le_iks_CreateKeyByType (const char *LE_NONNULL keyId, le_iks_KeyType_t keyType, uint32_t keySize)
 
le_result_t le_iks_GetKeyType (uint64_t keyRef, le_iks_KeyType_t *keyTypePtr)
 
le_result_t le_iks_GetKeySize (uint64_t keyRef, uint32_t *keySizePtr)
 
le_result_t le_iks_IsKeySizeValid (le_iks_KeyType_t keyType, uint32_t keySize)
 
le_result_t le_iks_HasKeyValue (uint64_t keyRef)
 
le_result_t le_iks_SetKeyUpdateKey (uint64_t keyRef, uint64_t updateKeyRef)
 
le_result_t le_iks_GenKeyValue (uint64_t keyRef, const uint8_t *authCmdPtr, size_t authCmdSize)
 
le_result_t le_iks_ProvisionKeyValue (uint64_t keyRef, const uint8_t *provPackagePtr, size_t provPackageSize)
 
le_result_t le_iks_SaveKey (uint64_t keyRef)
 
le_result_t le_iks_DeleteKey (uint64_t keyRef, const uint8_t *authCmdPtr, size_t authCmdSize)
 
le_result_t le_iks_GetPubKeyValue (uint64_t keyRef, uint8_t *bufPtr, size_t *bufSizePtr)
 
uint64_t le_iks_GetDigest (const char *LE_NONNULL digestId)
 
uint64_t le_iks_CreateDigest (const char *LE_NONNULL digestId, uint32_t digestSize)
 
le_result_t le_iks_GetDigestSize (uint64_t digestRef, uint32_t *digestSizePtr)
 
le_result_t le_iks_SetDigestUpdateKey (uint64_t digestRef, uint64_t updateKeyRef)
 
le_result_t le_iks_ProvisionDigest (uint64_t digestRef, const uint8_t *provPackagePtr, size_t provPackageSize)
 
le_result_t le_iks_SaveDigest (uint64_t digestRef)
 
le_result_t le_iks_DeleteDigest (uint64_t digestRef, const uint8_t *authCmdPtr, size_t authCmdSize)
 
le_result_t le_iks_GetDigestValue (uint64_t digestRef, uint8_t *bufPtr, size_t *bufSizePtr)
 
le_result_t le_iks_GetUpdateAuthChallenge (uint64_t keyRef, uint8_t *bufPtr, size_t *bufSizePtr)
 
le_result_t le_iks_GetProvisionKey (uint8_t *bufPtr, size_t *bufSizePtr)
 
uint64_t le_iks_CreateSession (uint64_t keyRef)
 
le_result_t le_iks_DeleteSession (uint64_t sessionRef)
 

Detailed Description

Legato IoT Keystore Key Management API API

Typedef Documentation

◆ le_iks_DisconnectHandler_t

typedef void(* le_iks_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

Function Documentation

◆ le_iks_ConnectService()

void le_iks_ConnectService ( void  )

Connect the current client thread to the service providing this API. Block until the service is available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

◆ le_iks_CreateDigest()

uint64_t le_iks_CreateDigest ( const char *LE_NONNULL  digestId,
uint32_t  digestSize 
)

Creates a new digest.

New digests initially have no value. Digest values can be set using le_iks_ProvisionDigest().

Created digests initially only exist in non-persistent memory, call le_iks_SaveDigest() to save to persistent storage.

Digest IDs may only consist of alphanumeric characters, the underscore '_' and hyphen '-'.

Returns
Reference to the digest if successful. 0 if there was an error.
Parameters
[in]digestIdIdentifier string.
[in]digestSizeDigest size. Must be <= MAX_DIGEST_SIZE.

◆ le_iks_CreateKey()

uint64_t le_iks_CreateKey ( const char *LE_NONNULL  keyId,
le_iks_KeyUsage_t  keyUsage 
)

Creates a new key.

This is a convenient way to create a key for a specific usage. This function will choose a default key type to satisfy the specified usage.

New keys initially have no value and cannot be used. Key values can be set using either le_iks_GenKeyValue() or le_iks_ProvisionKeyValue().

Created keys initially only exist in non-persistent memory, call le_iks_SaveKey() to save the key to persistent memory.

Returns
Reference to the key if successful. 0 if the keyId is already being used or is invalid or the keyUsage is invalid.
Parameters
[in]keyIdIdentifier string.
[in]keyUsageKey usage.

◆ le_iks_CreateKeyByType()

uint64_t le_iks_CreateKeyByType ( const char *LE_NONNULL  keyId,
le_iks_KeyType_t  keyType,
uint32_t  keySize 
)

Creates a new key of a specific type.

New keys initially have no value and cannot be used. Key values can be set using either le_iks_GenKeyValue() or le_iks_ProvisionKeyValue().

Created keys initially only exist in non-persistent memory, call le_iks_SaveKey() to save the key to persistent memory.

Returns
Reference to the key if successful. 0 if the keyId is already being used or if there was some other error.
Parameters
[in]keyIdIdentifier string.
[in]keyTypeKey type.
[in]keySizeKey size in bytes.

◆ le_iks_CreateSession()

uint64_t le_iks_CreateSession ( uint64_t  keyRef)

Create a session.

Returns
A session reference if successful. 0 if the key reference is invalid or does not contain a key value.
Parameters
[in]keyRefKey to use for this session.

◆ le_iks_DeleteDigest()

le_result_t le_iks_DeleteDigest ( uint64_t  digestRef,
const uint8_t *  authCmdPtr,
size_t  authCmdSize 
)

Delete a digest.

If the specified digest has an assigned update key then the authCmdPtr must contain a delete digest command and a valid authentication challenge, obtained by le_iks_GetUpdateAuthChallenge() and is signed with the update private key. If the command is valid and authentic then the digest will be deleted.

If the specified digest does not have an assigned update key then then authCmdPtr is ignored.

Note
See the comment block at the top of this page for the authenticated command format.
Returns
LE_OK if successful. LE_BAD_PARAMETER if the digest reference is invalid LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if the digest has an update key and the authCmdPtr is not valid.
Parameters
[in]digestRefDigest reference.
[in]authCmdPtrAuthenticated command buffer.
[in]authCmdSize

◆ le_iks_DeleteKey()

le_result_t le_iks_DeleteKey ( uint64_t  keyRef,
const uint8_t *  authCmdPtr,
size_t  authCmdSize 
)

Delete key.

If the specified key has an assigned update key then the authCmdPtr must contain a delete key command and a valid authentication challenge, obtained by le_iks_GetUpdateAuthChallenge(), and is signed with the update private key. If the command is valid and authentic then the key will be deleted.

If the specified key does not have an assigned update key then then authCmdPtr is ignored.

Warning
When deleting an update key, it is a good idea to delete all keys that depend on the update key first. Otherwise the dependent keys will be left non-updatable.
Note
See the comment block at the top of this page for the authenticated command format.
Returns
LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if the key has an update key and the authCmdPtr is not valid.
Parameters
[in]keyRefKey reference.
[in]authCmdPtrAuthenticated command buffer.
[in]authCmdSize

◆ le_iks_DeleteModuleId()

le_result_t le_iks_DeleteModuleId ( const uint8_t *  authCmdPtr,
size_t  authCmdSize 
)

Deletes the module ID.

This function is only possible if an update key was set when the module ID was set. The authCmdPtr must contain a valid delete module ID command. If the command is valid and authentic then the module ID is deleted. Once the module ID is deleted a new module ID may be set.

Note
See the comment block at the top of this page for the authenticated command format.
Returns
LE_OK if successful. LE_NOT_FOUND if the module ID has not been set. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if there is no assigned update key or the authCmdPtr is not valid or if there was an internal error.
Parameters
[in]authCmdPtrAuthenticated command buffer.
[in]authCmdSize

◆ le_iks_DeleteSession()

le_result_t le_iks_DeleteSession ( uint64_t  sessionRef)

Delete a session.

Returns
LE_OK if successful. LE_BAD_PARAMETER if the session reference is invalid. LE_UNSUPPORTED if underlying resource does not support this operation.
Parameters
[in]sessionRefSession reference.

◆ le_iks_DisconnectService()

void le_iks_DisconnectService ( void  )

Disconnect the current client thread from the service providing this API.

Normally, this function doesn't need to be called. After this function is called, there's no longer a connection to the service, and the functions in this API can't be used. For details, see Client-specific Functions.

This function is created automatically.

◆ le_iks_GenKeyValue()

le_result_t le_iks_GenKeyValue ( uint64_t  keyRef,
const uint8_t *  authCmdPtr,
size_t  authCmdSize 
)

Generate a key value.

If the specified key has an assigned update key then the authCmdPtr must contain a generate key command and a valid authentication challenge, obtained by le_iks_GetUpdateAuthChallenge(), and is signed with the update private key. If the command is valid and authentic then a new key value is generated replacing the old value.

If the specified key does not have an update key then the authCmdPtr is ignored.

Public keys cannot be generated using this function. They must be provisioned using le_iks_ProvisionKeyValue().

Note
See the comment block at the top of this page for the authenticated command format.
Returns
LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid or if the key is a public key. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if there is an update key set and the authCmdPtr does not contain a valid authenticated command, or if there was an internal error.
Parameters
[in]keyRefKey reference.
[in]authCmdPtrAuthenticated command buffer.
[in]authCmdSize

◆ le_iks_GetDigest()

uint64_t le_iks_GetDigest ( const char *LE_NONNULL  digestId)

Gets a reference to a digest.

Digest IDs may only consist of alphanumeric characters, the underscore '_' and hyphen '-'.

Returns
Reference to the digest. 0 if the digest could not be found.
Parameters
[in]digestIdIdentifier string.

◆ le_iks_GetDigestSize()

le_result_t le_iks_GetDigestSize ( uint64_t  digestRef,
uint32_t *  digestSizePtr 
)

Gets the digest size in bytes.

Returns
LE_OK if successful. LE_BAD_PARAMETER if the digest reference is invalid. LE_UNSUPPORTED if underlying resource does not support this operation.
Parameters
[in]digestRefDigest reference.
[out]digestSizePtrDigest size.

◆ le_iks_GetDigestValue()

le_result_t le_iks_GetDigestValue ( uint64_t  digestRef,
uint8_t *  bufPtr,
size_t *  bufSizePtr 
)

Get the digest value.

Returns
LE_OK if successful. LE_BAD_PARAMETER if the digest reference is invalid. LE_NOT_FOUND if the digest reference does not have a value. LE_OVERFLOW if the supplied buffer is too small to hold the digest value. LE_UNSUPPORTED if underlying resource does not support this operation.
Parameters
[in]digestRefDigest reference.
[out]bufPtrBuffer to hold the digest value.
[in,out]bufSizePtr

◆ le_iks_GetKey()

uint64_t le_iks_GetKey ( const char *LE_NONNULL  keyId)

Gets a reference to a key.

Returns
Reference to the key. 0 if the key could not be found.
Parameters
[in]keyIdIdentifier string.

◆ le_iks_GetKeySize()

le_result_t le_iks_GetKeySize ( uint64_t  keyRef,
uint32_t *  keySizePtr 
)

Gets the key size in bytes.

Returns
LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid LE_UNSUPPORTED if underlying resource does not support this operation.
Parameters
[in]keyRefKey reference.
[out]keySizePtrKey size.

◆ le_iks_GetKeyType()

le_result_t le_iks_GetKeyType ( uint64_t  keyRef,
le_iks_KeyType_t *  keyTypePtr 
)

Get the key type.

Returns
LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid LE_UNSUPPORTED if underlying resource does not support this operation.
Parameters
[in]keyRefKey reference.
[out]keyTypePtrKey type.

◆ le_iks_GetModuleId()

le_result_t le_iks_GetModuleId ( char *  idPtr,
size_t  idPtrSize 
)

Gets the module ID.

Returns
LE_OK if successful. LE_NOT_FOUND if the module ID has not been set. LE_BAD_PARAMETER if bufPtr is NULL. LE_OVERFLOW if the buffer is too small to hold the entire module ID. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if there was an internal error.
Parameters
[out]idPtrModule ID.
[in]idPtrSize

◆ le_iks_GetProvisionKey()

le_result_t le_iks_GetProvisionKey ( uint8_t *  bufPtr,
size_t *  bufSizePtr 
)

Get the provisioning key. This is a public key that is internally generated by the IOT Key Store and used to encrypt symmetric and private keys for provisioning into the IOT Key Store. This key can only be used for this purpose.

Note
The key is provided in ASN.1 structured DER encoded format. Refer to the comment at the top of this file for details of the file format.
Returns
LE_OK if successful. LE_OVERFLOW if the supplied buffer is too small. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if there is an internal error.
Parameters
[out]bufPtrBuffer to hold the provisioning key.
[in,out]bufSizePtr

◆ le_iks_GetPubKeyValue()

le_result_t le_iks_GetPubKeyValue ( uint64_t  keyRef,
uint8_t *  bufPtr,
size_t *  bufSizePtr 
)

Get the public portion of an asymmetric key.

The output will be in:

  • PKCS #1 format (DER encoded) for RSA keys.
  • ECPoint format defined in RFC5480 for ECC keys.
Returns
LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid or if the key is not an asymmetric key. LE_NOT_FOUND if the key reference does not have a value. LE_UNSUPPORTED if underlying resource does not support this operation. LE_OVERFLOW if the supplied buffer is too small to hold the key value.
Parameters
[in]keyRefKey reference.
[out]bufPtrBuffer to hold key value.
[in,out]bufSizePtr

◆ le_iks_GetUpdateAuthChallenge()

le_result_t le_iks_GetUpdateAuthChallenge ( uint64_t  keyRef,
uint8_t *  bufPtr,
size_t *  bufSizePtr 
)

Get update authentication challenge.

This challenge code must be included in any update commands created using the specified update key.

Returns
LE_OK if successful. LE_BAD_PARAMETER if the update key reference is invalid. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if there is an internal error.
Parameters
[in]keyRefKey reference.
[out]bufPtrBuffer to hold the authentication challenge. Assumed to be CHALLENGE_SIZE bytes.
[in,out]bufSizePtr

◆ le_iks_HasKeyValue()

le_result_t le_iks_HasKeyValue ( uint64_t  keyRef)

Checks if the key has a value.

Returns
LE_OK if the key has a value. LE_BAD_PARAMETER if the key reference is invalid. LE_NOT_FOUND if the key has no value. LE_UNSUPPORTED if underlying resource does not support this operation.
Parameters
[in]keyRefKey reference.

◆ le_iks_IsKeySizeValid()

le_result_t le_iks_IsKeySizeValid ( le_iks_KeyType_t  keyType,
uint32_t  keySize 
)

Checks if the key size is valid.

Returns
LE_OK if the key size is valid. LE_OUT_OF_RANGE if the key size is invalid. LE_UNSUPPORTED if underlying resource does not support this operation.
Parameters
[in]keyTypeKey type.
[in]keySizeKey size.

◆ le_iks_ProvisionDigest()

le_result_t le_iks_ProvisionDigest ( uint64_t  digestRef,
const uint8_t *  provPackagePtr,
size_t  provPackageSize 
)

Provision a digest value.

The provisioning package, provPackagePtr, must contain the digest value to provision.

If the specified digest does not have an assigned update key then the provPackagePtr is treated as a buffer containing the digest value.

If the specified digest has an assigned update key then the provPackagePtr must also contain a valid authentication challenge and be signed with the assigned update key.

Note
See the comment block at the top of this page for the provisioning package format.
Returns
LE_OK if successful. LE_BAD_PARAMETER if the digest reference is invalid or if the digest value is too long. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if the provPackagePtr does not have a valid signature or if there was an internal error.
Parameters
[in]digestRefDigest reference.
[in]provPackagePtrProvisioning package.
[in]provPackageSize

◆ le_iks_ProvisionKeyValue()

le_result_t le_iks_ProvisionKeyValue ( uint64_t  keyRef,
const uint8_t *  provPackagePtr,
size_t  provPackageSize 
)

Provision a key value.

The provisioning package, provPackagePtr, must contain the key value to provision.

Private key provisioning is not currently supported.

If the key is a symmetric then the key value must be encrypted with the provisioning key. If the key is a public key the key value must be provided in plaintext.

If the specified key does not have an assigned update key then the provPackagePtr is treated as a buffer containing the key value.

If the specified key has an assigned update key then the provPackagePtr must also contain a valid authentication challenge and be signed with the assigned update key.

Note
See the comment block at the top of this page for the provisioning package format.
Returns
LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if the provPackagePtr is not validly encrypted and/or signed or if there was an internal error.
Parameters
[in]keyRefKey reference.
[in]provPackagePtrProvisioning package.
[in]provPackageSize

◆ le_iks_SaveDigest()

le_result_t le_iks_SaveDigest ( uint64_t  digestRef)

Saves a digest to persistent storage.

Note
Previously saved digests that have been updated do not need to be re-saved.
Returns
LE_OK if successful. LE_BAD_PARAMETER if the digest reference is invalid LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if the digest is already in persistent storage or if there was an internal error.
Parameters
[in]digestRefDigest reference.

◆ le_iks_SaveKey()

le_result_t le_iks_SaveKey ( uint64_t  keyRef)

Saves a key to persistent storage.

Note
Previously saved keys that have been updated do not need to be re-saved.
Returns
LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if the key is already in persistent storage or if there was an internal error.
Parameters
[in]keyRefKey reference.

◆ le_iks_SetDigestUpdateKey()

le_result_t le_iks_SetDigestUpdateKey ( uint64_t  digestRef,
uint64_t  updateKeyRef 
)

Set an update key for the specified digest. The update key must be of type KEY_TYPE_KEY_UPDATE. The update key can be used at a later time to perform authenticated updates of the specified digest. The same update key may be used for multiple keys and digests.

Note
Once an update key is assigned the digest parameters can no longer be modified except through an authenticated update process.
Warning
It is strongly recommended to save the update key before assigning it to other keys/digests. Otherwise a sudden power loss could leave the update key reference pointing to a non-existing update key allowing a new update key to be created with the same ID but a different (unintended) value.
Returns
LE_OK if successful. LE_BAD_PARAMETER if the digest reference is invalid or if the update key reference is invalid or does not have a value. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if an update key has already been set or if there was an internal error.
Parameters
[in]digestRefDigest reference.
[in]updateKeyRefReference to an update key.

◆ le_iks_SetKeyUpdateKey()

le_result_t le_iks_SetKeyUpdateKey ( uint64_t  keyRef,
uint64_t  updateKeyRef 
)

Set an update key for the specified key. The update key must be of type KEY_TYPE_KEY_UPDATE. The update key can be used at a later time to perform authenticated updates of the specified key. The same update key may be used for multiple keys and digests.

Note
Once an update key is assigned the key parameters can no longer be modified except through an authenticated update process.

Update keys can be assigned to themselves or other update keys.

Warning
It is strongly recommended to save the update key before assigning it to other keys/digests. Otherwise a sudden power loss could leave the update key reference pointing to a non-existing update key allowing a new update key to be created with the same ID but a different (unintended) value.
Returns
LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid or if the update key reference is invalid or does not have a value. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if an update key has already been set or if there was an internal error.
Parameters
[in]keyRefKey reference.
[in]updateKeyRefReference to an update key.

◆ le_iks_SetModuleId()

le_result_t le_iks_SetModuleId ( const char *LE_NONNULL  idPtr,
uint64_t  keyRef 
)

Key usage. This type can be used to conveniently create keys for different usages. IOT Key Store will select a default key type for the specified usage. Key types Hash function identifiers.

Warning
The values in this enum must not be changed. The list may be amended but binary compatibility requires that the actual values never change. Sets the module ID. This module ID may be used to uniquely identify the module, device or chip that this instance of the IOT Key Store is running in. The module ID is not secret and should generally not change for the life of the module.

An update key can be set to delete the module ID. If the update key is not set then the module ID may be viewed as OTP (one-time programmable).

Returns
LE_OK if successful. LE_BAD_PARAMETER if the update key reference is invalid or if idPtr NULL or is invalid. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if the module ID has already been set or if there was an internal error.
Parameters
[in]idPtrModule ID.
[in]keyRefKey reference. NULL if not used.

◆ le_iks_SetServerDisconnectHandler()

LE_FULL_API void le_iks_SetServerDisconnectHandler ( le_iks_DisconnectHandler_t  disconnectHandler,
void *  contextPtr 
)

Set handler called when server disconnection is detected.

When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants to continue without exiting, it should call longjmp() from inside the handler.

◆ le_iks_TryConnectService()

le_result_t le_iks_TryConnectService ( void  )

Try to connect the current client thread to the service providing this API. Return with an error if the service is not available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

Returns
  • LE_OK if the client connected successfully to the service.
  • LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  • LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  • LE_COMM_ERROR if the Service Directory cannot be reached.