le_iks_ecc API Reference

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 *aadPtr, size_t aadSize, const uint8_t *plaintextPtr, size_t plaintextSize, uint8_t *ciphertextPtr, size_t *ciphertextSizePtr, uint8_t *ephemKeyPtr, size_t *ephemKeySizePtr, uint8_t *saltPtr, size_t *saltSizePtr, 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 *aadPtr, size_t aadSize, const uint8_t *ephemKeyPtr, size_t ephemKeySize, const uint8_t *saltPtr, size_t saltSize, 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, uint8_t *saltPtr, size_t *saltSizePtr)
 
le_result_t le_iks_ecc_Ecies_ProcessAad (uint64_t session, const uint8_t *aadChunkPtr, size_t aadChunkSize)
 
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, const uint8_t *saltPtr, size_t saltSize)
 
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]privKeyRefPrivate key reference.
[in]pubKeyRefPublid Key reference.
[out]secretPtrBuffer 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]keyRefKey reference.
[in]digestPtrDigest to sign.
[in]digestSize
[out]signaturePtrBuffer 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]keyRefKey reference.
[in]digestPtrDigest of the message.
[in]digestSize
[in]signaturePtrSignature 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 too big. LE_FAULT if a decryption process has not started.
Parameters
[in]sessionSession reference.
[in]ciphertextChunkPtrCiphertext chunk.
[in]ciphertextChunkSize
[out]plaintextChunkPtrBuffer 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 *  aadPtr,
size_t  aadSize,
const uint8_t *  ephemKeyPtr,
size_t  ephemKeySize,
const uint8_t *  saltPtr,
size_t  saltSize,
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, saltPtr, aadPtr, plaintextPtr, ciphertextChunkPtr, tagPtr is NULL when they shouldn't be. LE_OUT_OF_RANGE if the labelSize, aadSize, textSize, tagSize is invalid. LE_OVERFLOW if plaintextPtr buffer is too small. LE_FAULT if there was an internal error.
Parameters
[in]keyRefKey reference.
[in]labelPtrLabel. NULL if not used.
[in]labelSize
[in]aadPtrAAD chunk. NULL if not used.
[in]aadSize
[in]ephemKeyPtrSerialized ephemeral public key.
[in]ephemKeySize
[in]saltPtrSalt.
[in]saltSize
[in]ciphertextPtrCiphertext chunk.
[in]ciphertextSize
[out]plaintextPtrBuffer to hold the plaintext chunk.
[in,out]plaintextSizePtr
[in]tagPtrAuthentication 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_FAULT if a decryption process has not started or no data (AAD and ciphertext) has been processed or the integrity check failed.
Parameters
[in]sessionSession reference.
[in]tagPtrAuthentication 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_OVERFLOW if the tagPtr buffer is too small. LE_FAULT if an encryption process has not started or no data (AAD and plaintext) has been processed.
Parameters
[in]sessionSession reference.
[out]tagPtrBuffer 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]sessionSession reference.
[in]plaintextChunkPtrPlaintext chunk. NULL if not used.
[in]plaintextChunkSize
[out]ciphertextChunkPtrBuffer 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 *  aadPtr,
size_t  aadSize,
const uint8_t *  plaintextPtr,
size_t  plaintextSize,
uint8_t *  ciphertextPtr,
size_t *  ciphertextSizePtr,
uint8_t *  ephemKeyPtr,
size_t *  ephemKeySizePtr,
uint8_t *  saltPtr,
size_t *  saltSizePtr,
uint8_t *  tagPtr,
size_t *  tagSizePtr 
)

Encrypts and integrity protects 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.

Either plaintextPtr or aadPtr can be NULL but not both.

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, aadPtr, plaintextPtr, ciphertextPtr, ephemKeyPtr, ephemKeySizePtr, saltPtr, saltSizePtr, tagPtr is NULL when they shouldn't be. LE_OUT_OF_RANGE if the labelSize, aadSize, textSize is invalid. LE_OVERFLOW if either the ciphertextPtr, ephemKeyPtr, saltSizePtr buffer is too small. LE_FAULT if there was an internal error.
Parameters
[in]keyRefKey reference.
[in]labelPtrLabel. NULL if not used.
[in]labelSize
[in]aadPtrAAD chunk. NULL if not used.
[in]aadSize
[in]plaintextPtrPlaintext chunk. NULL if not used.
[in]plaintextSize
[out]ciphertextPtrBuffer to hold the ciphertext chunk.
[in,out]ciphertextSizePtr
[out]ephemKeyPtrSerialized ephemeral public key.
[in,out]ephemKeySizePtr
[out]saltPtrBuffer to hold the salt.
[in,out]saltSizePtr
[out]tagPtrBuffer to hold the authentication tag.
[in,out]tagSizePtr

◆ le_iks_ecc_Ecies_ProcessAad()

le_result_t le_iks_ecc_Ecies_ProcessAad ( uint64_t  session,
const uint8_t *  aadChunkPtr,
size_t  aadChunkSize 
)

Process a chunk of AAD (Additional Authenticated Data). Either Ecies_StartEncrypt() or Ecies_StartDecrypt() must have been previously called to start either an encryption or 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 aadChunkPtr is NULL. LE_OUT_OF_RANGE if aadChunkSize is too big. LE_FAULT if an encryption or decryption process was not started or plaintext/ciphertext processing has already started.
Parameters
[in]sessionSession reference.
[in]aadChunkPtrAAD chunk.
[in]aadChunkSize

◆ 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,
const uint8_t *  saltPtr,
size_t  saltSize 
)

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_ProcessAad() // Call zero or more times until all AAD data is processed. 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, ephemeral public key and salt 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 either the ephemKeyPtr or saltPtr is NULL. LE_OUT_OF_RANGE if either the labelSize is too big or the saltSize or ephemKeySize is incorrect. LE_FAULT if there was an internal error.
Parameters
[in]sessionSession reference.
[in]labelPtrLabel. NULL if not used.
[in]labelSize
[in]ephemKeyPtrSerialized ephemeral public key.
[in]ephemKeySize
[in]saltPtrSalt.
[in]saltSize

◆ 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,
uint8_t *  saltPtr,
size_t *  saltSizePtr 
)

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_ProcessAad() // Call zero or more times until all AAD data is processed. 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.

The AAD and plaintext are optional but they cannot both be omitted. All AAD must be processed before plaintext processing begins.

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.

A random salt is used during the encryption process only if the KDF requires it. Currently, only HKDF requires a salt. If present the salt will be the same size as the hash function output size. If no salt is used saltPtr is set to NULL.

Returns
LE_OK if successful. LE_BAD_PARAMETER if the session reference is invalid or if the key type is invalid or if either the ephemKeyPtr, ephemKeySizePtr, saltPtr or saltSizePtr is NULL. LE_OUT_OF_RANGE if the labelSize is too big. LE_OVERFLOW if any of the output buffers are too small. LE_FAULT if there was an internal error.
Parameters
[in]sessionSession reference.
[in]labelPtrLabel. NULL if not used.
[in]labelSize
[out]ephemKeyPtrSerialized ephemeral public key.
[in,out]ephemKeySizePtr
[out]saltPtrBuffer to hold the salt.
[in,out]saltSizePtr

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