#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
Copyright (C) Sierra Wireless Inc.
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] digestId Identifier string. [in] digestSize Digest 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] keyId Identifier string. [in] keyUsage Key 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] keyId Identifier string. [in] keyType Key type. [in] keySize Key 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] keyRef Key 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] digestRef Digest reference. [in] authCmdPtr Authenticated 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] keyRef Key reference. [in] authCmdPtr Authenticated 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] authCmdPtr Authenticated 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] sessionRef Session 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] keyRef Key reference. [in] authCmdPtr Authenticated 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] digestId Identifier 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] digestRef Digest reference. [out] digestSizePtr Digest 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] digestRef Digest reference. [out] bufPtr Buffer 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] keyId Identifier 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] keyRef Key reference. [out] keySizePtr Key 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] keyRef Key reference. [out] keyTypePtr Key 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] idPtr Module 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] bufPtr Buffer 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] keyRef Key reference. [out] bufPtr Buffer 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] keyRef Key reference. [out] bufPtr Buffer 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] keyRef Key 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] keyType Key type. [in] keySize Key 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] digestRef Digest reference. [in] provPackagePtr Provisioning 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] keyRef Key reference. [in] provPackagePtr Provisioning 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] digestRef Digest 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] keyRef Key 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] digestRef Digest reference. [in] updateKeyRef Reference 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] keyRef Key reference. [in] updateKeyRef Reference 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] idPtr Module ID. [in] keyRef Key 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.