le_iks_aesGcm API Reference

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]sessionSession reference.
[in]ciphertextChunkPtrCiphertext chunk. NULL if not used.
[in]ciphertextChunkSize
[out]plaintextChunkPtrBuffer 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]keyRefKey reference.
[in]noncePtrNonce used to encrypt the packet. Assumed to be NONCE_SIZE bytes.
[in]nonceSize
[in]aadPtrAdditional authenticated data (AAD). NULL if not used.
[in]aadSize
[in]ciphertextPtrCiphertext. NULL if not used.
[in]ciphertextSize
[out]plaintextPtrBuffer to hold the plaintext.
[in,out]plaintextSizePtr
[in]tagPtrBuffer 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]sessionSession reference.
[in]tagPtrBuffer 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]sessionSession reference.
[out]tagPtrBuffer 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]sessionSession reference.
[in]plaintextChunkPtrPlaintext.
[in]plaintextChunkSize
[out]ciphertextChunkPtrBuffer 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]keyRefKey reference.
[out]noncePtrBuffer to hold the nonce. Assumed to be NONCE_SIZE bytes.
[in,out]nonceSizePtr
[in]aadPtrAdditional authenticated data (AAD). NULL if not used.
[in]aadSize
[in]plaintextPtrPlaintext. NULL if not used.
[in]plaintextSize
[out]ciphertextPtrBuffer to hold the ciphertext.
[in,out]ciphertextSizePtr
[out]tagPtrBuffer 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]sessionSession reference.
[in]aadPtrAdditional 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]sessionSession reference.
[in]noncePtrNonce 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]sessionSession reference.
[out]noncePtrBuffer 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.