Files
file	le_iks_aesGcm_common.h

file	le_iks_aesGcm_interface.h

Macros
#define	LE_IKS_AESGCM_NONCE_SIZE 12

#define	LE_IKS_AESGCM_TAG_SIZE 16

Typedefs
typedef void(*	le_iks_aesGcm_DisconnectHandler_t) (void *)

Functions
void	le_iks_aesGcm_ConnectService (void)

le_result_t	le_iks_aesGcm_TryConnectService (void)

LE_FULL_API void	le_iks_aesGcm_SetServerDisconnectHandler (le_iks_aesGcm_DisconnectHandler_t disconnectHandler, void *contextPtr)

void	le_iks_aesGcm_DisconnectService (void)

le_result_t	le_iks_aesGcm_EncryptPacket (uint64_t keyRef, uint8_t noncePtr, size_t nonceSizePtr, const uint8_t aadPtr, size_t aadSize, const uint8_t plaintextPtr, size_t plaintextSize, uint8_t ciphertextPtr, size_t ciphertextSizePtr, uint8_t tagPtr, size_t tagSizePtr)

le_result_t	le_iks_aesGcm_DecryptPacket (uint64_t keyRef, const uint8_t noncePtr, size_t nonceSize, const uint8_t aadPtr, size_t aadSize, 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_aesGcm_StartEncrypt (uint64_t session, uint8_t noncePtr, size_t nonceSizePtr)

le_result_t	le_iks_aesGcm_ProcessAad (uint64_t session, const uint8_t *aadPtr, size_t aadSize)

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

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

le_result_t	le_iks_aesGcm_StartDecrypt (uint64_t session, const uint8_t *noncePtr, size_t nonceSize)

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

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

Detailed Description

Macro Definition Documentation

◆ LE_IKS_AESGCM_NONCE_SIZE

#define LE_IKS_AESGCM_NONCE_SIZE 12

Nonce sizes in bytes.

◆ LE_IKS_AESGCM_TAG_SIZE

#define LE_IKS_AESGCM_TAG_SIZE 16

Tag sizes in bytes.

Typedef Documentation

◆ le_iks_aesGcm_DisconnectHandler_t

typedef void(* le_iks_aesGcm_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

Function Documentation

◆ le_iks_aesGcm_ConnectService()

void le_iks_aesGcm_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_aesGcm_Decrypt()

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

Decrypt a chunk of ciphertext. le_iks_aesGcm_StartDecrypt() must have been previously called to start either 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_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if a decryption process has not started.

Parameters

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

◆ le_iks_aesGcm_DecryptPacket()

le_result_t le_iks_aesGcm_DecryptPacket	(	uint64_t	keyRef,
		const uint8_t *	noncePtr,
		size_t	nonceSize,
		const uint8_t *	aadPtr,
		size_t	aadSize,
		const uint8_t *	ciphertextPtr,
		size_t	ciphertextSize,
		uint8_t *	plaintextPtr,
		size_t *	plaintextSizePtr,
		const uint8_t *	tagPtr,
		size_t	tagSize
	)

Decrypt and verify the integrity of a packet with AES in GCM mode.

This function performs an integrity check of the AAD and the ciphertext and if the integrity passes provides the decrypted plaintext.

The plaintext size is the same as the ciphertext size and it is assumed that the plaintextPtr buffer is at least ciphertextSize bytes long.

The nonce, AAD, ciphertext and tag must be the values produced during encryption.

| nonce, AAD, ciphertext, tag |

| V

| plaintext |

Returns: LE_OK if successful. LE_OUT_OF_RANGE if either the aadSize or ciphertextSize is too large. LE_BAD_PARAMETER if the key reference is invalid or if the key type is invalid or if either noncePtr, tagPtr, plaintextPtr or ciphertextPtr is NULL when they shouldn't be. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if the integrity check failed.

Parameters

[in]	keyRef	Key reference.
[in]	noncePtr	Nonce used to encrypt the packet. Assumed to be NONCE_SIZE bytes.
[in]	nonceSize
[in]	aadPtr	Additional authenticated data (AAD). NULL if not used.
[in]	aadSize
[in]	ciphertextPtr	Ciphertext. NULL if not used.
[in]	ciphertextSize
[out]	plaintextPtr	Buffer to hold the plaintext.
[in,out]	plaintextSizePtr
[in]	tagPtr	Buffer to hold the authentication tag. Assumed to be TAG_SIZE.
[in]	tagSize

◆ le_iks_aesGcm_DisconnectService()

void le_iks_aesGcm_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_aesGcm_DoneDecrypt()

le_result_t le_iks_aesGcm_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_UNSUPPORTED if underlying resource does not support this operation. 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]	session	Session reference.
[in]	tagPtr	Buffer to hold the authentication tag. Assumed to be TAG_SIZE.
[in]	tagSize

◆ le_iks_aesGcm_DoneEncrypt()

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

Complete encryption and calculate the authentication tag.

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_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if an encryption process has not started or no data (AAD and plaintext) has been processed.

Parameters

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

◆ le_iks_aesGcm_Encrypt()

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

Encrypt a chunk of plaintext. le_iks_aesGcm_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_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if an encryption process has not started.

Parameters

[in]	session	Session reference.
[in]	plaintextChunkPtr	Plaintext.
[in]	plaintextChunkSize
[out]	ciphertextChunkPtr	Buffer to hold the ciphertext.
[in,out]	ciphertextChunkSizePtr

◆ le_iks_aesGcm_EncryptPacket()

le_result_t le_iks_aesGcm_EncryptPacket	(	uint64_t	keyRef,
		uint8_t *	noncePtr,
		size_t *	nonceSizePtr,
		const uint8_t *	aadPtr,
		size_t	aadSize,
		const uint8_t *	plaintextPtr,
		size_t	plaintextSize,
		uint8_t *	ciphertextPtr,
		size_t *	ciphertextSizePtr,
		uint8_t *	tagPtr,
		size_t *	tagSizePtr
	)

Encrypt and integrity protect a packet with AES in GCM mode.

GCM is an AEAD (Authenticated Encryption with Associated Data) which means that it provides both confidentiality and integrity protection for plaintext data and provides integrity protection for associated data. The associated data, also referred to as Additional Authenticated Data (AAD), is not encrypted but is integrity protected. The output of the encryption is a randomly chosen nonce, the ciphertext corresponding to the plaintext and an authentication tag. The authentication tag integrity protects the nonce, AAD and the ciphertext.

| AAD, plaintext |

| V

| nonce, ciphertext, tag |

This is especially useful in communication protocols where a packet's payload needs to be secret but the packet's header must be readable. In this case the packet's header is the AAD.

The AAD and plaintext are optional but they cannot both be omitted. If the AAD is omitted then confidentiality and integrity is provided for just the plaintext. If the plaintext is omitted then integrity protection is provided for just the AAD.

The ciphertext size is the same as the plaintext size and it is assumed that the ciphertextPtr buffer is at least plaintextSize bytes long.

The tag size is always LE_IKS_AES_GCM_TAG_SIZE bytes and it is assumed that the tagPtr buffer is large enough to hold the tag.

A random nonce is chosen for each invocation of this function. The nonce is passed out to the caller via noncePtr and is assumed to always be LE_IKS_AES_GCM_NONCE_SIZE bytes. The nonce does not need to be kept secret and can be passed in the clear.

Nonce values must be unique for each invocation for the lifetime of the key. In other words a (key, nonce) pair must be unique for every invocation for all time and for all users in the world. This is a critical security requirement but can be difficult to satisfy that is why keys should be rotated frequently.

Repeated nonces in GCM are particularly problematic as they can be used to recover the integrity key.

Returns: LE_OK if successful. LE_OUT_OF_RANGE if either the aadSize or plaintextSize is the wrong size. LE_BAD_PARAMETER if the key reference is invalid or if the key type is invalid or if either noncePtr, tagPtr, plaintextPtr or ciphertextPtr is NULL when they shouldn't be. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if there was an internal error.

Parameters

[in]	keyRef	Key reference.
[out]	noncePtr	Buffer to hold the nonce. Assumed to be NONCE_SIZE bytes.
[in,out]	nonceSizePtr
[in]	aadPtr	Additional authenticated data (AAD). NULL if not used.
[in]	aadSize
[in]	plaintextPtr	Plaintext. NULL if not used.
[in]	plaintextSize
[out]	ciphertextPtr	Buffer to hold the ciphertext.
[in,out]	ciphertextSizePtr
[out]	tagPtr	Buffer to hold the authentication tag. Assumed to be TAG_SIZE.
[in,out]	tagSizePtr

◆ le_iks_aesGcm_ProcessAad()

le_result_t le_iks_aesGcm_ProcessAad	(	uint64_t	session,
		const uint8_t *	aadPtr,
		size_t	aadSize
	)

Process a chunk of AAD (Additional Authenticated Data). Either le_iks_aesGcm_StartEncrypt() or le_iks_aesGcm_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_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if an encryption or decryption process was not started or plaintext/ciphertext processing has already started.

Parameters

[in]	session	Session reference.
[in]	aadPtr	Additional authenticated data (AAD). NULL if not used.
[in]	aadSize

◆ le_iks_aesGcm_SetServerDisconnectHandler()

LE_FULL_API void le_iks_aesGcm_SetServerDisconnectHandler	(	le_iks_aesGcm_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_aesGcm_StartDecrypt()

le_result_t le_iks_aesGcm_StartDecrypt	(	uint64_t	session,
		const uint8_t *	noncePtr,
		size_t	nonceSize
	)

Starts a process to decrypt and verify the integrity of a long packet with AES in GCM mode. This function is useful for decrypting and verifying packets that are larger than MAX_PACKET_SIZE. Calling this function will cancel any previously started process using the same session.

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

le_iks_aesGcm_StartDecrypt() // Start the decryption process. le_iks_aesGcm_ProcessAad() // Call zero or more times until all AAD data is processed. le_iks_aesGcm_Decrypt() // Call zero or more times until all ciphertext is decrypted. le_iks_aesGcm_DoneDecrypt() // Complete decryption process.

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 le_iks_aesGcm_DoneDecrypt() is called. The caller therefore must not release or make use of any plaintext chunks until after le_iks_aesGcm_DoneDecrypt() returns with LE_OK.

Returns: LE_OK if successful. LE_BAD_PARAMETER if the session reference is invalid or if the key type is not valid or if noncePtr is NULL. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if there was an internal error.

Parameters

[in]	session	Session reference.
[in]	noncePtr	Nonce used to encrypt the packet. Assumed to be NONCE_SIZE bytes.
[in]	nonceSize

◆ le_iks_aesGcm_StartEncrypt()

le_result_t le_iks_aesGcm_StartEncrypt	(	uint64_t	session,
		uint8_t *	noncePtr,
		size_t *	nonceSizePtr
	)

Starts a process to encrypt and integrity protect a long packet with AES in GCM mode. This function is useful for encrypting and integrity protecting packets that are larger than MAX_PACKET_SIZE. Calling this function will cancel any previously started process using the same session.

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

le_iks_aesGcm_StartEncrypt() // Start the encryption process. le_iks_aesGcm_ProcessAad() // Call zero or more times until all AAD data is processed. le_iks_aesGcm_Encrypt() // Call zero or more times until all plaintext is encrypted. le_iks_aesGcm_DoneEncrypt() // Complete process and obtain authentication tag.

All AAD must be processed before plaintext processing begins.

A random nonce is chosen for each invocation of this function. The nonce is passed out to the caller via noncePtr and is assumed to always be AES_GCM_NONCE_SIZE bytes. The nonce does not need to be kept secret and can be passed in the clear.

Nonce values must be unique for each invocation for the lifetime of the key. In other words a (key, nonce) pair must be unique for every invocation for all time and for all users in the world. This is a critical security requirement but can be difficult to satisfy. Therefore keys should be rotated frequently.

Returns: LE_OK if successful. LE_BAD_PARAMETER if the session reference is invalid or if the key type is invalid or if noncePtr is NULL. LE_UNSUPPORTED if underlying resource does not support this operation. LE_FAULT if there was an internal error.

Parameters

[in]	session	Session reference.
[out]	noncePtr	Buffer to hold the nonce. Assumed to be NONCE_SIZE bytes.
[in,out]	nonceSizePtr

◆ le_iks_aesGcm_TryConnectService()

le_result_t le_iks_aesGcm_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_aesGcm API Reference

Files

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ LE_IKS_AESGCM_NONCE_SIZE

◆ LE_IKS_AESGCM_TAG_SIZE

Typedef Documentation

◆ le_iks_aesGcm_DisconnectHandler_t

Function Documentation

◆ le_iks_aesGcm_ConnectService()

◆ le_iks_aesGcm_Decrypt()

◆ le_iks_aesGcm_DecryptPacket()

| nonce, AAD, ciphertext, tag |

| plaintext |

◆ le_iks_aesGcm_DisconnectService()

◆ le_iks_aesGcm_DoneDecrypt()

◆ le_iks_aesGcm_DoneEncrypt()

◆ le_iks_aesGcm_Encrypt()

◆ le_iks_aesGcm_EncryptPacket()

| AAD, plaintext |

| nonce, ciphertext, tag |

◆ le_iks_aesGcm_ProcessAad()

◆ le_iks_aesGcm_SetServerDisconnectHandler()

◆ le_iks_aesGcm_StartDecrypt()

◆ le_iks_aesGcm_StartEncrypt()

◆ le_iks_aesGcm_TryConnectService()