Files
file	le_iks_ecc_common.h

file	le_iks_ecc_interface.h

Macros
#define	LE_IKS_ECC_MAX_SERIAL_KEY_SIZE 1025

#define	LE_IKS_ECC_MAX_SIGNATURE_SIZE 1024

#define	LE_IKS_ECC_MAX_TAG_SIZE 64

Typedefs
typedef void(*	le_iks_ecc_DisconnectHandler_t) (void *)

Functions
void	le_iks_ecc_ConnectService (void)

le_result_t	le_iks_ecc_TryConnectService (void)

LE_FULL_API void	le_iks_ecc_SetServerDisconnectHandler (le_iks_ecc_DisconnectHandler_t disconnectHandler, void *contextPtr)

void	le_iks_ecc_DisconnectService (void)

le_result_t	le_iks_ecc_Ecdh_GetSharedSecret (uint64_t privKeyRef, uint64_t pubKeyRef, uint8_t secretPtr, size_t secretSizePtr)

le_result_t	le_iks_ecc_Ecdsa_GenSig (uint64_t keyRef, const uint8_t digestPtr, size_t digestSize, uint8_t signaturePtr, size_t *signatureSizePtr)

le_result_t	le_iks_ecc_Ecdsa_VerifySig (uint64_t keyRef, const uint8_t digestPtr, size_t digestSize, const uint8_t signaturePtr, size_t signatureSize)

le_result_t	le_iks_ecc_Ecies_EncryptPacket (uint64_t keyRef, const uint8_t labelPtr, size_t labelSize, const uint8_t plaintextPtr, size_t plaintextSize, uint8_t ciphertextPtr, size_t ciphertextSizePtr, uint8_t ephemKeyPtr, size_t ephemKeySizePtr, uint8_t tagPtr, size_t tagSizePtr)

le_result_t	le_iks_ecc_Ecies_DecryptPacket (uint64_t keyRef, const uint8_t labelPtr, size_t labelSize, const uint8_t ephemKeyPtr, size_t ephemKeySize, const uint8_t ciphertextPtr, size_t ciphertextSize, uint8_t plaintextPtr, size_t plaintextSizePtr, const uint8_t tagPtr, size_t tagSize)

le_result_t	le_iks_ecc_Ecies_StartEncrypt (uint64_t session, const uint8_t labelPtr, size_t labelSize, uint8_t ephemKeyPtr, size_t *ephemKeySizePtr)

le_result_t	le_iks_ecc_Ecies_Encrypt (uint64_t session, const uint8_t plaintextChunkPtr, size_t plaintextChunkSize, uint8_t ciphertextChunkPtr, size_t *ciphertextChunkSizePtr)

le_result_t	le_iks_ecc_Ecies_DoneEncrypt (uint64_t session, uint8_t tagPtr, size_t tagSizePtr)

le_result_t	le_iks_ecc_Ecies_StartDecrypt (uint64_t session, const uint8_t labelPtr, size_t labelSize, const uint8_t ephemKeyPtr, size_t ephemKeySize)

le_result_t	le_iks_ecc_Ecies_Decrypt (uint64_t session, const uint8_t ciphertextChunkPtr, size_t ciphertextChunkSize, uint8_t plaintextChunkPtr, size_t *plaintextChunkSizePtr)

le_result_t	le_iks_ecc_Ecies_DoneDecrypt (uint64_t session, const uint8_t *tagPtr, size_t tagSize)

Detailed Description

Macro Definition Documentation

◆ LE_IKS_ECC_MAX_SERIAL_KEY_SIZE

#define LE_IKS_ECC_MAX_SERIAL_KEY_SIZE 1025

Maximum serialized ECC key size.

◆ LE_IKS_ECC_MAX_SIGNATURE_SIZE

#define LE_IKS_ECC_MAX_SIGNATURE_SIZE 1024

Maximum signature size.

◆ LE_IKS_ECC_MAX_TAG_SIZE

#define LE_IKS_ECC_MAX_TAG_SIZE 64

Maximum tag size.

Typedef Documentation

◆ le_iks_ecc_DisconnectHandler_t

typedef void(* le_iks_ecc_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

Function Documentation

◆ le_iks_ecc_ConnectService()

void le_iks_ecc_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_ecc_DisconnectService()

void le_iks_ecc_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_ecc_Ecdh_GetSharedSecret()

le_result_t le_iks_ecc_Ecdh_GetSharedSecret	(	uint64_t	privKeyRef,
		uint64_t	pubKeyRef,
		uint8_t *	secretPtr,
		size_t *	secretSizePtr
	)

Generate a shared secret between an ECC private key and an ECC public key.

The private key must be of type LE_IKS_KEY_TYPE_PRIV_ECDH and the public must be of type LE_IKS_KEY_TYPE_PUB_ECDH or LE_IKS_KEY_TYPE_PRIV_ECDH.

This function may be used as part of a key exchange protocol. The shared secret is unpredictable (assuming the private portions of both keys are kept secret) but not uniformly distributed and should not be used directly as a cryptographic key.

The shared secret is in the format specified by SEC 1, that is the x component of the shared point converted to an octet string.

If the buffer is too small to hold the shared secret the shared secret will be truncated to fit.

Returns: LE_OK if successful. LE_BAD_PARAMETER if either key reference is invalid or if either key type is invalid or if two key sizes do not match or if the secretPtr or secretSizePtr is NULL. LE_FAULT if there was an internal error.

Parameters

[in]	privKeyRef	Private key reference.
[in]	pubKeyRef	Publid Key reference.
[out]	secretPtr	Buffer to hold the shared secret.
[in,out]	secretSizePtr

◆ le_iks_ecc_Ecdsa_GenSig()

le_result_t le_iks_ecc_Ecdsa_GenSig	(	uint64_t	keyRef,
		const uint8_t *	digestPtr,
		size_t	digestSize,
		uint8_t *	signaturePtr,
		size_t *	signatureSizePtr
	)

Generate an ECDSA signature on the hash digest of a message.

The key must be a LE_IKS_KEY_TYPE_PRIV_ECDSA key.

The signature is the concatenation of the r and s values (r||s). The size of the signature is twice the key size. For example if the key is 256 bits in size then the signature will be 64 bytes. Note that when the key size is 521 bits, zero-valued high-order padding bits are added to the signature values r and s resulting in a signature of 132 bytes.

The hash function used to generate the message digest should be chosen to match the security strength of the signing key. For example, if the key size is 256 bits then SHA256 (or its equivalent) should be used.

Returns: LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid or if the key type is invalid or if digestPtr, signaturePtr or signatureSizePtr are NULL LE_OVERFLOW if the signature buffer is too small. LE_FAULT if there was an internal error.

Parameters

[in]	keyRef	Key reference.
[in]	digestPtr	Digest to sign.
[in]	digestSize
[out]	signaturePtr	Buffer to hold the signature.
[in,out]	signatureSizePtr

◆ le_iks_ecc_Ecdsa_VerifySig()

le_result_t le_iks_ecc_Ecdsa_VerifySig	(	uint64_t	keyRef,
		const uint8_t *	digestPtr,
		size_t	digestSize,
		const uint8_t *	signaturePtr,
		size_t	signatureSize
	)

Verifies a signature of the hash digest of a message with ECDSA.

The key must be either a LE_IKS_KEY_TYPE_PUB_ECDSA or LE_IKS_KEY_TYPE_PRIV_ECDSA key.

The signature is the concatenation of the r and s values (r||s). The size of the signature is twice the key size. For example if the key is 256 bits in size then the signature will be 64 bytes. Note that when the key size is 521 bits, zero-valued high-order padding bits are added to the signature values r and s resulting in a signature of 132 bytes.

Returns: LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid or if the key type is invalid or if either digestPtr or signaturePtr are NULL. LE_FORMAT_ERROR if signatureSize is incorrect. LE_FAULT if the signature is not valid.

Parameters

[in]	keyRef	Key reference.
[in]	digestPtr	Digest of the message.
[in]	digestSize
[in]	signaturePtr	Signature of the message.
[in]	signatureSize

◆ le_iks_ecc_Ecies_Decrypt()

le_result_t le_iks_ecc_Ecies_Decrypt	(	uint64_t	session,
		const uint8_t *	ciphertextChunkPtr,
		size_t	ciphertextChunkSize,
		uint8_t *	plaintextChunkPtr,
		size_t *	plaintextChunkSizePtr
	)

Decrypt a chunk of ciphertext. Ecies_StartDecrypt() must have been previously called to start a decryption process.

Returns: LE_OK if successful. LE_BAD_PARAMETER if the session reference is invalid or if the key type is invalid or if plaintextChunkPtr or ciphertextChunkPtr is NULL. LE_OUT_OF_RANGE if textSize is invalid. LE_FAULT if a decryption process has not started.

Parameters

[in]	session	Session reference.
[in]	ciphertextChunkPtr	Ciphertext chunk.
[in]	ciphertextChunkSize
[out]	plaintextChunkPtr	Buffer to hold the plaintext chunk.
[in,out]	plaintextChunkSizePtr

◆ le_iks_ecc_Ecies_DecryptPacket()

le_result_t le_iks_ecc_Ecies_DecryptPacket	(	uint64_t	keyRef,
		const uint8_t *	labelPtr,
		size_t	labelSize,
		const uint8_t *	ephemKeyPtr,
		size_t	ephemKeySize,
		const uint8_t *	ciphertextPtr,
		size_t	ciphertextSize,
		uint8_t *	plaintextPtr,
		size_t *	plaintextSizePtr,
		const uint8_t *	tagPtr,
		size_t	tagSize
	)

Decrypts and checks the integrity of a short message with ECIES (Elliptic Curve Integrated Encryption System).

Hybrid encryption combines an asymmetric encryption system with a symmetric encryption system to encrypt messages that can only be decrypted with the holder of the private key. Hybrid encryption is usually accomplished by using a symmetric encryption system to bulk encrypt the message and then using the asymmetric encryption system to encrypt the symmetric key.

ECIES provides hybrid encryption through a method that is more efficient than manually performing the two step process described above. Broadly speaking, ECIES performs a key agreement to generate a shared secret, the shared secret is then used to generate a symmetric key using a KDF (Key Derivation Function). The symmetric key is then used to bulk encrypt the message.

This implementation of ECIES generally follows the SEC 1 standard but supports modernized algorithms for the KDF and bulk encryption.

Returns: LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid or if the key reference is invalid or if either the ephemKeyPtr, plaintextPtr, ciphertextPtr, tagPtr is NULL. LE_OUT_OF_RANGE if the labelSize, textSize, tagSize is invalid. LE_OVERFLOW if plaintextPtr buffer is too small. LE_FAULT if there was an internal error.

Parameters

[in]	keyRef	Key reference.
[in]	labelPtr	Label. NULL if not used.
[in]	labelSize
[in]	ephemKeyPtr	Serialized ephemeral public key.
[in]	ephemKeySize
[in]	ciphertextPtr	Ciphertext chunk.
[in]	ciphertextSize
[out]	plaintextPtr	Buffer to hold the plaintext chunk.
[in,out]	plaintextSizePtr
[in]	tagPtr	Authentication tag.
[in]	tagSize

◆ le_iks_ecc_Ecies_DoneDecrypt()

le_result_t le_iks_ecc_Ecies_DoneDecrypt	(	uint64_t	session,
		const uint8_t *	tagPtr,
		size_t	tagSize
	)

Complete decryption and verify the integrity.

Returns: LE_OK if successful. LE_BAD_PARAMETER if the session reference is invalid or if the key type is invalid or if tagPtr is NULL. LE_OUT_OF_RANGE if tagSize is invalid. LE_FAULT if a decryption process has not started or no data has been processed or the integrity check failed.

Parameters

[in]	session	Session reference.
[in]	tagPtr	Authentication tag.
[in]	tagSize

◆ le_iks_ecc_Ecies_DoneEncrypt()

le_result_t le_iks_ecc_Ecies_DoneEncrypt	(	uint64_t	session,
		uint8_t *	tagPtr,
		size_t *	tagSizePtr
	)

Complete encryption and calculate the authentication tag.

The maximum tag size depends on the symmetric algorithm used. If the supplied buffer is larger than or equal to the maximum authentication tag size then the full authentication tag is copied to the buffer and the rest of the buffer is left unmodified. If the supplied buffer is smaller than the maximum tag size then the tag will be truncated. However, all tags produced using the same key must use the same tag size. It is up to the caller to ensure this.

Returns: LE_OK if successful. LE_BAD_PARAMETER if the session reference is invalid or if the key type is invalid or if tagPtr is NULL. LE_OUT_OF_RANGE if tagSize if invalud. LE_OVERFLOW if the tagPtr buffer is too small. LE_FAULT if an encryption process has not started or no data has been processed.

Parameters

[in]	session	Session reference.
[out]	tagPtr	Buffer to hold the authentication tag.
[in,out]	tagSizePtr

◆ le_iks_ecc_Ecies_Encrypt()

le_result_t le_iks_ecc_Ecies_Encrypt	(	uint64_t	session,
		const uint8_t *	plaintextChunkPtr,
		size_t	plaintextChunkSize,
		uint8_t *	ciphertextChunkPtr,
		size_t *	ciphertextChunkSizePtr
	)

Encrypt a chunk of plaintext. Ecies_StartEncrypt() must have been previously called to start an encryption process.

Returns: LE_OK if successful. LE_BAD_PARAMETER if the session reference is invalid or if the key type is invalid or if plaintextChunkPtr or ciphertextChunkPtr is NULL. LE_OUT_OF_RANGE if textSize is too big. LE_FAULT if an encryption process has not started.

Parameters

[in]	session	Session reference.
[in]	plaintextChunkPtr	Plaintext chunk. NULL if not used.
[in]	plaintextChunkSize
[out]	ciphertextChunkPtr	Buffer to hold the ciphertext chunk.
[in,out]	ciphertextChunkSizePtr

◆ le_iks_ecc_Ecies_EncryptPacket()

le_result_t le_iks_ecc_Ecies_EncryptPacket	(	uint64_t	keyRef,
		const uint8_t *	labelPtr,
		size_t	labelSize,
		const uint8_t *	plaintextPtr,
		size_t	plaintextSize,
		uint8_t *	ciphertextPtr,
		size_t *	ciphertextSizePtr,
		uint8_t *	ephemKeyPtr,
		size_t *	ephemKeySizePtr,
		uint8_t *	tagPtr,
		size_t *	tagSizePtr
	)

Encrypts and integrity protects a short message with ECIES (Elliptic Curve Integrated Encryption System).

Hybrid encryption combines an asymmetric encryption system with a symmetric encryption system to encrypt messages that can only be decrypted with the holder of the private key. Hybrid encryption is usually accomplished by using a symmetric encryption system to bulk encrypt the message and then using the asymmetric encryption system to encrypt the symmetric key.

ECIES provides hybrid encryption through a method that is more efficient than manually performing the two step process described above. Broadly speaking, ECIES performs a key agreement to generate a shared secret, the shared secret is then used to generate a symmetric key using a KDF (Key Derivation Function). The symmetric key is then used to bulk encrypt the message.

This implementation of ECIES generally follows the SEC 1 standard but supports modernized algorithms for the KDF and bulk encryption.

Returns: LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid or if the key type is invalid. or if either labelPtr, plaintextPtr, ciphertextPtr, ephemKeyPtr, ephemKeySizePtr, tagPtr is NULL when they shouldn't be. LE_OUT_OF_RANGE if the labelSize, textSize, tagSize is invalid. LE_OVERFLOW if the ephemKeyPtr buffer is too small. LE_FAULT if there was an internal error.

Parameters

[in]	keyRef	Key reference.
[in]	labelPtr	Label. NULL if not used.
[in]	labelSize
[in]	plaintextPtr	Plaintext chunk. NULL if not used.
[in]	plaintextSize
[out]	ciphertextPtr	Buffer to hold the ciphertext chunk.
[in,out]	ciphertextSizePtr
[out]	ephemKeyPtr	Serialized ephemeral public key.
[in,out]	ephemKeySizePtr
[out]	tagPtr	Buffer to hold the authentication tag.
[in,out]	tagSizePtr

◆ le_iks_ecc_Ecies_StartDecrypt()

le_result_t le_iks_ecc_Ecies_StartDecrypt	(	uint64_t	session,
		const uint8_t *	labelPtr,
		size_t	labelSize,
		const uint8_t *	ephemKeyPtr,
		size_t	ephemKeySize
	)

Starts a process to decrypt and check the integrity of a message with ECIES (Elliptic Curve Integrated Encryption System).

Hybrid encryption combines an asymmetric encryption system with a symmetric encryption system to encrypt (possibly long) messages that can only be decrypted with the holder of the private key. Hybrid encryption is usually accomplished by using a symmetric encryption system to bulk encrypt the message and then using the asymmetric encryption system to encrypt the symmetric key.

ECIES provides hybrid encryption through a method that is more efficient than manually performing the two step process described above. Broadly speaking, ECIES performs a key agreement to generate a shared secret, the shared secret is then used to generate a symmetric key using a KDF (Key Derivation Function). The symmetric key is then used to bulk encrypt the message.

This implementation of ECIES generally follows the SEC 1 standard but supports modernized algorithms for the KDF and bulk encryption.

To decrypt a long packet the following sequence should be used:

Ecies_StartDecrypt() // Start the decryption process. Ecies_Decrypt() // Call zero or more times until all ciphertext is decrypted. Ecies_DoneDecrypt() // Complete the process and check the authentication tag.

Calling this function will cancel any previously started process using the same session.

The same label and ephemeral public key used for encryption must be provided.

Warning: While decrypting long packets in this 'streaming' fashion plaintext chunks are released to the caller before they are verified for integrity. Ie. the caller will not know the plaintext is correct until DoneDecrypt() is called. The caller therefore must not release or make use of any plaintext chunks until after DoneDecrypt() returns with LE_OK.

Returns: LE_OK if successful. LE_BAD_PARAMETER if the session reference is invalid or if the session key type or ephemeral key is invalid or if the ephemKeyPtr is NULL. LE_OUT_OF_RANGE if either the labelSize or ephemKeySize is invalid. LE_FAULT if there was an internal error.

Parameters

[in]	session	Session reference.
[in]	labelPtr	Label. NULL if not used.
[in]	labelSize
[in]	ephemKeyPtr	Serialized ephemeral public key.
[in]	ephemKeySize

◆ le_iks_ecc_Ecies_StartEncrypt()

le_result_t le_iks_ecc_Ecies_StartEncrypt	(	uint64_t	session,
		const uint8_t *	labelPtr,
		size_t	labelSize,
		uint8_t *	ephemKeyPtr,
		size_t *	ephemKeySizePtr
	)

Starts a process to encrypt and integrity protect a message with ECIES (Elliptic Curve Integrated Encryption System).

Hybrid encryption combines an asymmetric encryption system with a symmetric encryption system to encrypt messages that can only be decrypted with the holder of the private key. Hybrid encryption is usually accomplished by using a symmetric encryption system to bulk encrypt the message and then using the asymmetric encryption system to encrypt the symmetric key.

This implementation of ECIES generally follows the SEC 1 standard but supports modernized algorithms for the KDF and bulk encryption.

To encrypt a long packet the following sequence should be used:

Ecies_StartEncrypt() // Start the encryption process. Ecies_Encrypt() // Call zero or more times until all plaintext is encrypted. Ecies_DoneEncrypt() // Complete the process and obtain the authentication tag.

Calling this function will cancel any previously started process using the same session.

The session must have been created with the public key used for encryption.

An optional label associated with the message can be added.

The public portion of the ephemeral key used during the encrytion process is stored in the ephemKeyPtr buffer. It is encoded as an ECPoint as described in RFC5480.

Returns: LE_OK if successful. LE_BAD_PARAMETER if the session reference is invalid or if the key type is invalid or if either labelPtr, ephemKeyPtr, ephemKeySizePtr is NULL when they shouldn't be. LE_OUT_OF_RANGE if the labelSize is invalid. LE_OVERFLOW if any of the output buffers are too small. LE_FAULT if there was an internal error.

Parameters

[in]	session	Session reference.
[in]	labelPtr	Label. NULL if not used.
[in]	labelSize
[out]	ephemKeyPtr	Serialized ephemeral public key.
[in,out]	ephemKeySizePtr

◆ le_iks_ecc_SetServerDisconnectHandler()

LE_FULL_API void le_iks_ecc_SetServerDisconnectHandler	(	le_iks_ecc_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_ecc_TryConnectService()

le_result_t le_iks_ecc_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.

/ Build Apps

le_iks_ecc API Reference

Files

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ LE_IKS_ECC_MAX_SERIAL_KEY_SIZE

◆ LE_IKS_ECC_MAX_SIGNATURE_SIZE

◆ LE_IKS_ECC_MAX_TAG_SIZE

Typedef Documentation

◆ le_iks_ecc_DisconnectHandler_t

Function Documentation

◆ le_iks_ecc_ConnectService()

◆ le_iks_ecc_DisconnectService()

◆ le_iks_ecc_Ecdh_GetSharedSecret()

◆ le_iks_ecc_Ecdsa_GenSig()

◆ le_iks_ecc_Ecdsa_VerifySig()

◆ le_iks_ecc_Ecies_Decrypt()

◆ le_iks_ecc_Ecies_DecryptPacket()

◆ le_iks_ecc_Ecies_DoneDecrypt()

◆ le_iks_ecc_Ecies_DoneEncrypt()

◆ le_iks_ecc_Ecies_Encrypt()

◆ le_iks_ecc_Ecies_EncryptPacket()

◆ le_iks_ecc_Ecies_StartDecrypt()

◆ le_iks_ecc_Ecies_StartEncrypt()

◆ le_iks_ecc_SetServerDisconnectHandler()

◆ le_iks_ecc_TryConnectService()