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

enum 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

enum 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

enum 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]	digestId	Identifier string.
[in]	digestSize	Digest size. Must be <= MAX_DIGEST_SIZE.
[out]	digestRefPtr	Digest 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]	keyId	Identifier string.
[in]	keyUsage	Key usage.
[out]	keyRefPtr	Key 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]	keyId	Identifier string.
[in]	keyType	Key type.
[in]	keySize	Key size in bytes.
[out]	keyRefPtr	Key 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]	keyRef	Key to use for this session.
[out]	sessionRefPtr	Session 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]	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()

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]	digestId	Identifier string.
[out]	digestRefPtr	Digest 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]	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()

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]	keyId	Identifier string.
[out]	keyRefPtr	Key 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]	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.

le_iks API Reference

Files

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ LE_IKS_AES_BLOCK_SIZE

◆ LE_IKS_CHALLENGE_SIZE

◆ LE_IKS_MAX_ASN1_VAL_BUF_SIZE

◆ LE_IKS_MAX_AUTH_CMD_SIZE

◆ LE_IKS_MAX_DIGEST_ID_SIZE

◆ LE_IKS_MAX_DIGEST_SIZE

◆ LE_IKS_MAX_KEY_ID_SIZE

◆ LE_IKS_MAX_KEY_SIZE

◆ LE_IKS_MAX_MODULE_ID_SIZE

◆ LE_IKS_MAX_PACKET_SIZE

◆ LE_IKS_MAX_PROV_PACKAGE_SIZE

Typedef Documentation

◆ le_iks_DisconnectHandler_t

Enumeration Type Documentation

◆ le_iks_HashFunc_t

◆ le_iks_KeyType_t

◆ le_iks_KeyUsage_t

Function Documentation

◆ le_iks_ConnectService()

◆ le_iks_CreateDigest()

◆ le_iks_CreateKey()

◆ le_iks_CreateKeyByType()

◆ le_iks_CreateSession()

◆ le_iks_DeleteDigest()

◆ le_iks_DeleteKey()

◆ le_iks_DeleteModuleId()

◆ le_iks_DeleteSession()

◆ le_iks_DisconnectService()

◆ le_iks_GenKeyValue()

◆ le_iks_GetDigest()

◆ le_iks_GetDigestSize()

◆ le_iks_GetDigestValue()

◆ le_iks_GetKey()

◆ le_iks_GetKeySize()

◆ le_iks_GetKeyType()

◆ le_iks_GetModuleId()

◆ le_iks_GetProvisionKey()

◆ le_iks_GetPubKeyValue()

◆ le_iks_GetUpdateAuthChallenge()

◆ le_iks_HasKeyValue()

◆ le_iks_IsKeySizeValid()

◆ le_iks_ProvisionDigest()

◆ le_iks_ProvisionKeyValue()

◆ le_iks_SaveDigest()

◆ le_iks_SaveKey()

◆ le_iks_SetDigestUpdateKey()

◆ le_iks_SetKeyUpdateKey()

◆ le_iks_SetModuleId()

◆ le_iks_SetServerDisconnectHandler()

◆ le_iks_TryConnectService()