le_iks API Reference

Files

file  le_iks_common.h
 
file  le_iks_interface.h
 

Macros

#define LE_IKS_MAX_KEY_SIZE   512
 
#define LE_IKS_MAX_DIGEST_SIZE   64
 
#define LE_IKS_MAX_ASN1_VAL_BUF_SIZE   3000
 
#define LE_IKS_CHALLENGE_SIZE   32
 
#define LE_IKS_AES_BLOCK_SIZE   16
 
#define LE_IKS_MAX_KEY_ID_SIZE   255
 
#define LE_IKS_MAX_KEY_ID_BYTES   256
 
#define LE_IKS_MAX_DIGEST_ID_SIZE   255
 
#define LE_IKS_MAX_DIGEST_ID_BYTES   256
 
#define LE_IKS_MAX_AUTH_CMD_SIZE   4096
 
#define LE_IKS_MAX_PROV_PACKAGE_SIZE   4096
 
#define LE_IKS_MAX_PACKET_SIZE   4096
 
#define LE_IKS_MAX_MODULE_ID_SIZE   50
 
#define LE_IKS_MAX_MODULE_ID_BYTES   51
 

Typedefs

typedef void(* le_iks_DisconnectHandler_t) (void *)
 

Enumerations

enum  le_iks_KeyUsage_t {
  LE_IKS_KEY_USE_ENCRYPT = 0, LE_IKS_KEY_USE_ASYMM_ENCRYPT = 1, LE_IKS_KEY_USE_ASYMM_DECRYPT = 2, LE_IKS_KEY_USE_SIG_GENERATION = 3,
  LE_IKS_KEY_USE_SIG_VERIFICATION = 4, LE_IKS_KEY_USE_KEY_UPDATE = 5
}
 
enum  le_iks_KeyType_t {
  LE_IKS_KEY_TYPE_AES_GCM = 1, LE_IKS_KEY_TYPE_AES_CBC = 2, LE_IKS_KEY_TYPE_AES_CMAC = 3, LE_IKS_KEY_TYPE_AES_MILENAGE_K = 4,
  LE_IKS_KEY_TYPE_AES_MILENAGE_OPC = 5, LE_IKS_KEY_TYPE_HMAC_SHA512 = 81, LE_IKS_KEY_TYPE_HMAC_SHA384 = 82, LE_IKS_KEY_TYPE_HMAC_SHA256 = 83,
  LE_IKS_KEY_TYPE_PRIV_RSAES_OAEP_SHA512 = 100, LE_IKS_KEY_TYPE_PUB_RSAES_OAEP_SHA512 = 101, LE_IKS_KEY_TYPE_PRIV_RSAES_OAEP_SHA384 = 102, LE_IKS_KEY_TYPE_PUB_RSAES_OAEP_SHA384 = 103,
  LE_IKS_KEY_TYPE_PRIV_RSAES_OAEP_SHA512_256 = 104, LE_IKS_KEY_TYPE_PUB_RSAES_OAEP_SHA512_256 = 105, LE_IKS_KEY_TYPE_PRIV_RSAES_OAEP_SHA256 = 106, LE_IKS_KEY_TYPE_PUB_RSAES_OAEP_SHA256 = 107,
  LE_IKS_KEY_TYPE_PRIV_RSAES_OAEP_SHA512_224 = 108, LE_IKS_KEY_TYPE_PUB_RSAES_OAEP_SHA512_224 = 109, LE_IKS_KEY_TYPE_PRIV_RSAES_OAEP_SHA224 = 110, LE_IKS_KEY_TYPE_PUB_RSAES_OAEP_SHA224 = 111,
  LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA512 = 125, LE_IKS_KEY_TYPE_PUB_RSASSA_PSS_SHA512 = 126, LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA384 = 127, LE_IKS_KEY_TYPE_PUB_RSASSA_PSS_SHA384 = 128,
  LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA512_256 = 129, LE_IKS_KEY_TYPE_PUB_RSASSA_PSS_SHA512_256 = 130, LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA256 = 131, LE_IKS_KEY_TYPE_PUB_RSASSA_PSS_SHA256 = 132,
  LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA512_224 = 133, LE_IKS_KEY_TYPE_PUB_RSASSA_PSS_SHA512_224 = 134, LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA224 = 135, LE_IKS_KEY_TYPE_PUB_RSASSA_PSS_SHA224 = 136,
  LE_IKS_KEY_TYPE_UPDATE_RSASSA_PSS_SHA512 = 150, LE_IKS_KEY_TYPE_UPDATE_RSASSA_PSS_SHA384 = 151, LE_IKS_KEY_TYPE_UPDATE_RSASSA_PSS_SHA512_256 = 152, LE_IKS_KEY_TYPE_UPDATE_RSASSA_PSS_SHA256 = 153,
  LE_IKS_KEY_TYPE_UPDATE_RSASSA_PSS_SHA512_224 = 154, LE_IKS_KEY_TYPE_UPDATE_RSASSA_PSS_SHA224 = 155, LE_IKS_KEY_TYPE_PRIV_ECDH = 200, LE_IKS_KEY_TYPE_PUB_ECDH = 201,
  LE_IKS_KEY_TYPE_PRIV_ECDSA = 220, LE_IKS_KEY_TYPE_PUB_ECDSA = 221, LE_IKS_KEY_TYPE_UPDATE_ECDSA = 240, LE_IKS_KEY_TYPE_PRIV_ECIES_HKDF_SHA512_GCM256 = 260,
  LE_IKS_KEY_TYPE_PUB_ECIES_HKDF_SHA512_GCM256 = 261, LE_IKS_KEY_TYPE_PRIV_ECIES_HKDF_SHA256_GCM128 = 262, LE_IKS_KEY_TYPE_PUB_ECIES_HKDF_SHA256_GCM128 = 263
}
 
enum  le_iks_HashFunc_t {
  LE_IKS_HASH_SHA512 = 0, LE_IKS_HASH_SHA384 = 1, LE_IKS_HASH_SHA512_256 = 2, LE_IKS_HASH_SHA256 = 3,
  LE_IKS_HASH_SHA512_224 = 4, LE_IKS_HASH_SHA224 = 5
}
 

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)
 
le_result_t le_iks_GetKey (const char *LE_NONNULL keyId, uint64_t *keyRefPtr)
 
le_result_t le_iks_CreateKey (const char *LE_NONNULL keyId, le_iks_KeyUsage_t keyUsage, uint64_t *keyRefPtr)
 
le_result_t le_iks_CreateKeyByType (const char *LE_NONNULL keyId, le_iks_KeyType_t keyType, uint32_t keySize, uint64_t *keyRefPtr)
 
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)
 
le_result_t le_iks_GetDigest (const char *LE_NONNULL digestId, uint64_t *digestRefPtr)
 
le_result_t le_iks_CreateDigest (const char *LE_NONNULL digestId, uint32_t digestSize, uint64_t *digestRefPtr)
 
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)
 
le_result_t le_iks_CreateSession (uint64_t keyRef, uint64_t *sessionRefPtr)
 
le_result_t le_iks_DeleteSession (uint64_t sessionRef)
 

Detailed Description

Macro Definition Documentation

◆ LE_IKS_AES_BLOCK_SIZE

#define LE_IKS_AES_BLOCK_SIZE   16

AES block size in bytes.

◆ LE_IKS_CHALLENGE_SIZE

#define LE_IKS_CHALLENGE_SIZE   32

Authenticated challenge size in bytes.

◆ LE_IKS_MAX_ASN1_VAL_BUF_SIZE

#define LE_IKS_MAX_ASN1_VAL_BUF_SIZE   3000

Maximum buffer size, in bytes, for ASN1 structured, DER encoded keys/digests.

◆ LE_IKS_MAX_AUTH_CMD_SIZE

#define LE_IKS_MAX_AUTH_CMD_SIZE   4096

Maximum size of the authentication command

◆ LE_IKS_MAX_DIGEST_ID_SIZE

#define LE_IKS_MAX_DIGEST_ID_SIZE   255

Maximum size of the Digest ID

◆ LE_IKS_MAX_DIGEST_SIZE

#define LE_IKS_MAX_DIGEST_SIZE   64

Maximum digest size in bytes.

◆ LE_IKS_MAX_KEY_ID_SIZE

#define LE_IKS_MAX_KEY_ID_SIZE   255

Maximum size of the Key ID

◆ LE_IKS_MAX_KEY_SIZE

#define LE_IKS_MAX_KEY_SIZE   512

Maximum possible key buffer size.

◆ LE_IKS_MAX_MODULE_ID_SIZE

#define LE_IKS_MAX_MODULE_ID_SIZE   50

Maximum size, in bytes, of the module identifier.

◆ LE_IKS_MAX_PACKET_SIZE

#define LE_IKS_MAX_PACKET_SIZE   4096

Maximum packet size.

◆ LE_IKS_MAX_PROV_PACKAGE_SIZE

#define LE_IKS_MAX_PROV_PACKAGE_SIZE   4096

Maximum size of the provisioning package

Typedef Documentation

◆ le_iks_DisconnectHandler_t

typedef void(* le_iks_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

Enumeration Type Documentation

◆ le_iks_HashFunc_t

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.

◆ le_iks_KeyType_t

Key types

Enumerator
LE_IKS_KEY_TYPE_AES_GCM 

AES GCM.

LE_IKS_KEY_TYPE_AES_CBC 

AES CBC.

LE_IKS_KEY_TYPE_AES_CMAC 

AES CMAC.

LE_IKS_KEY_TYPE_AES_MILENAGE_K 

AES Milenage K.

LE_IKS_KEY_TYPE_AES_MILENAGE_OPC 

AES Milenage OPc.

LE_IKS_KEY_TYPE_PRIV_ECIES_HKDF_SHA512_GCM256 

Uses HKDF with SHA512 and AES GCM 256.

LE_IKS_KEY_TYPE_PUB_ECIES_HKDF_SHA512_GCM256 

Uses HKDF with SHA512 and AES GCM 256.

LE_IKS_KEY_TYPE_PRIV_ECIES_HKDF_SHA256_GCM128 

Uses HKDF with SHA256 and AES GCM 128.

LE_IKS_KEY_TYPE_PUB_ECIES_HKDF_SHA256_GCM128 

Uses HKDF with SHA256 and AES GCM 128.

◆ le_iks_KeyUsage_t

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.

Enumerator
LE_IKS_KEY_USE_ENCRYPT 

Symmetric encryption/decryption.

LE_IKS_KEY_USE_ASYMM_ENCRYPT 

Public key encryption.

LE_IKS_KEY_USE_ASYMM_DECRYPT 

Private key decryption.

LE_IKS_KEY_USE_SIG_GENERATION 

Signature generation.

LE_IKS_KEY_USE_SIG_VERIFICATION 

Signature verification.

LE_IKS_KEY_USE_KEY_UPDATE 

Key Store key updates.

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()

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

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
LE_OK if successful. LE_BAD_PARAMETER if the digestId is invalid or if digestRef is NULL. LE_DUPLICATE if the digestId is already being used. LE_OUT_OF_RANGE if the digest size is invalid. LE_NO_MEMORY if there is not enough memory to create the digest. LE_FAULT if there was an internal error.
Parameters
[in]digestIdIdentifier string.
[in]digestSizeDigest size. Must be <= MAX_DIGEST_SIZE.
[out]digestRefPtrDigest reference.

◆ le_iks_CreateKey()

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

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
LE_OK if successful. LE_BAD_PARAMETER if the keyId or keyUsage is invalid or if keyRef is NULL. LE_DUPLICATE if the keyId is already being used. LE_NO_MEMORY if there is not enough memory to create the key. LE_FAULT if there was an internal error.
Parameters
[in]keyIdIdentifier string.
[in]keyUsageKey usage.
[out]keyRefPtrKey reference.

◆ le_iks_CreateKeyByType()

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

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
LE_OK if successful. LE_BAD_PARAMETER if the keyId or keyType is invalid or if keyRef is NULL. LE_DUPLICATE if the keyId is already being used. LE_OUT_OF_RANGE if the key size is invalid. LE_NO_MEMORY if there is not enough memory to create the key. LE_FAULT if there was an internal error.
Parameters
[in]keyIdIdentifier string.
[in]keyTypeKey type.
[in]keySizeKey size in bytes.
[out]keyRefPtrKey reference.

◆ le_iks_CreateSession()

le_result_t le_iks_CreateSession ( uint64_t  keyRef,
uint64_t *  sessionRefPtr 
)

Create a session.

Returns
LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid or if the key does not contain a key value or sessionRef is NULL. LE_NO_MEMORY if there is not enough memory to create the session. LE_FAULT if there was an internal error.
Parameters
[in]keyRefKey to use for this session.
[out]sessionRefPtrSession reference.

◆ 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()

le_result_t le_iks_GetDigest ( const char *LE_NONNULL  digestId,
uint64_t *  digestRefPtr 
)

Gets a reference to a digest.

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

Returns
LE_OK if successful. LE_BAD_PARAMETER if the digestId is invalid or if digestRef is NULL. LE_NOT_FOUND if the digest does not exist. LE_NO_MEMORY if there is not enough memory to retrieve the digest. LE_FAULT if there was an internal error.
Parameters
[in]digestIdIdentifier string.
[out]digestRefPtrDigest reference.

◆ 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()

le_result_t le_iks_GetKey ( const char *LE_NONNULL  keyId,
uint64_t *  keyRefPtr 
)

Gets a reference to a key.

Returns
LE_OK if successful. LE_BAD_PARAMETER if the keyId is invalid or keyRef is NULL. LE_NOT_FOUND if the key does not exist. LE_NO_MEMORY if there is not enough memory to retrieve the key. LE_FAULT if there was an internal error.
Parameters
[in]keyIdIdentifier string.
[out]keyRefPtrKey reference.

◆ 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.