Helper class for doing CCM encryption-with-authentication using the CC32xx's hardware AES engine. More...

#include <CC32xxAes.hxx>

Classes
class	DecryptorStream

Public Member Functions
void	decrypt_init (const std::string &aes_key, const std::string &nonce, const std::string &auth_data, unsigned data_len, uint8_t tag_len)
	Initializes streaming decryption.

void	data_process (const std::string &payload, std::string *payload_out)
	Process streaming encryption data.

void	data_finalize (std::string payload_out, std::string tag_out)
	Completes the streaming operation.

Static Public Member Functions
static void	decrypt (const std::string &aes_key, const std::string &nonce, const std::string &auth_data, const std::string &cipher, std::string plain, std::string tag)
	Performs authenticated decryption using CCM in one call.

static void	encrypt (const std::string &aes_key, const std::string &nonce, const std::string &auth_data, const std::string &plain, unsigned tag_len, std::string cipher, std::string tag)
	Performs authenticated encryption using CCM in one call.

static void	static_decrypt_init (const std::string &aes_key, const std::string &nonce, const std::string &auth_data, unsigned data_len, uint8_t tag_len)

static void	static_encrypt_init (const std::string &aes_key, const std::string &nonce, const std::string &auth_data, unsigned data_len, uint8_t tag_len)

static SyncStream *	create_decryptor_stream (const std::string &aes_key, const std::string &nonce, const std::string &auth_data, unsigned data_len, uint8_t tag_len, SyncStream consumer, std::string tag_out, const std::string *expected_tag)
	Creates a stream for on-the-fly receiving encrypted data and passing on decrypted data to a consumer stream.

Static Private Member Functions
static void	reset ()
	Resets / turns on the AES engine.

static uint32_t	interpret_key_size (unsigned key_len)
	Computes the internal constant used for the configuration of the key size.

static int	nonce_length_to_l (unsigned nonce_len)
	Compute the size of the L parameter in bytes from the nonce length.

static unsigned	get_mode (unsigned key_len, unsigned nonce_len, unsigned tag_len)
	Computes mode bits for the AES engine.

static void	process_block (const uint8_t din, uint8_t dout)
	Performs encryption (or decryption) on a single block of data.

static void	read_tag (std::string *tag_out)
	Finalizes encyrption/decryption and reads out the checksum tag.

Private Attributes
std::unique_ptr< SyncStream >	decryptorStream_
	Implementation object.

StringAppendStream *	outputStream_
	Stream that catches the decrypted output in the user-provided strings.

std::string	tagOut_
	Variable that will receive the output tag.

Detailed Description

Helper class for doing CCM encryption-with-authentication using the CC32xx's hardware AES engine.

Definition at line 54 of file CC32xxAes.hxx.

Member Function Documentation

◆ create_decryptor_stream()

static SyncStream * CCMHelper::create_decryptor_stream	(	const std::string &	aes_key,
		const std::string &	nonce,
		const std::string &	auth_data,
		unsigned	data_len,
		uint8_t	tag_len,
		SyncStream *	consumer,
		std::string *	tag_out,
		const std::string *	expected_tag
	)

inlinestatic

Creates a stream for on-the-fly receiving encrypted data and passing on decrypted data to a consumer stream.

Parameters

aes_key	is the secret key, has to be 16, 24 or 32 bytes long for AES-128, 192 and 256.
nonce	is the public part of the initialization vector that came with the message.
auth_data	is the cleartext header whose signature needs to be verified.
data_len	is the length of the ciphertext. You must send exactly this many bytes to the stream.
tag_len	is the length of the signature in bytes; even number from 4 to 16 (recommended 16).
consumer	is the stream that will receive the decrypted bytes. Takes ownership of it.
tag_out	will be set to the authentication tag after the stream is finalized.
expected_tag	if not null, will be compared to the actual tag in case of mismatch a finalization error will be generated.

Returns: a stream to which the encrypted bytes need to be written. The caller owns this stream and is required to finalize() it in order to read the tag bytes.

Definition at line 267 of file CC32xxAes.hxx.

◆ data_finalize()

void CCMHelper::data_finalize	(	std::string *	payload_out,
		std::string *	tag_out
	)

inline

Completes the streaming operation.

Parameters

payload_out	will be the remaining output data (that came from the buffer). Could be zero to 15 bytes.
tag_out	will be filled with the authentication tag.

Definition at line 237 of file CC32xxAes.hxx.

◆ data_process()

void CCMHelper::data_process	(	const std::string &	payload,
		std::string *	payload_out
	)

inline

Process streaming encryption data.

Parameters

payload	input data (ciphertext for decryption). Can be arbitrary length (will be buffered internally if needed).
payload_out	output data (cleartext for decryption). Length can be both shorter or longer than payload by a block size.

Definition at line 224 of file CC32xxAes.hxx.

◆ decrypt()

static void CCMHelper::decrypt	(	const std::string &	aes_key,
		const std::string &	nonce,
		const std::string &	auth_data,
		const std::string &	cipher,
		std::string *	plain,
		std::string *	tag
	)

inlinestatic

Performs authenticated decryption using CCM in one call.

Use this when all of the ciphertext is available.

Parameters

aes_key	is the secret key. 16, 24 or 32 bytes long.
nonce	is the use-once initialization that came in cleartext with the encrypted data.
auth_data	is cleartext data (usually packet headers) that need to be checked for authenticity.
cipher	is the encrypted data.
plain	will hold the decrypted data.
tag	will hold the authentication checksum. Make sure to resize this to the appropriate number of bytes before calling (suggested 16 bytes).

Definition at line 70 of file CC32xxAes.hxx.

◆ decrypt_init()

void CCMHelper::decrypt_init	(	const std::string &	aes_key,
		const std::string &	nonce,
		const std::string &	auth_data,
		unsigned	data_len,
		uint8_t	tag_len
	)

inline

Initializes streaming decryption.

Sets up the module for decryption and installs the keys and configuration. Processes the cleartext pre-auth data. After this call zero or more data_process calls need to be made, then a single data_finalize.

Parameters

aes_key	is the secret key, has to be 16, 24 or 32 bytes long for AES-128, 192 and 256.
nonce	is the public part of the initialization vector that came with the message.
auth_data	is the cleartext header whose signature needs to be verified.
data_len	is the length of the ciphertext.
tag_len	is the length of the signature in bytes; even number from 4 to 16 (recommended 16).

Definition at line 141 of file CC32xxAes.hxx.

◆ encrypt()

static void CCMHelper::encrypt	(	const std::string &	aes_key,
		const std::string &	nonce,
		const std::string &	auth_data,
		const std::string &	plain,
		unsigned	tag_len,
		std::string *	cipher,
		std::string *	tag
	)

inlinestatic

Performs authenticated encryption using CCM in one call.

Use this when all the plaintext is available and both cipher and plaintext fits into memory.

Parameters

aes_key	is the secret key. 16, 24 or 32 bytes long.
nonce	is the use-once initialization. Must be 13, 11 or 7 bytes long.
auth_data	is cleartext data (usually packet headers) that need to be checked for authenticity.
plain	is the plain text data.
tag_len	is the desired length of the authentication tag. Recommend 16.
cipher	will hold the encrypted data.
tag	will hold the authentication checksum. Will be resized to tag_len.

Definition at line 100 of file CC32xxAes.hxx.

◆ get_mode()

static unsigned CCMHelper::get_mode	(	unsigned	key_len,
		unsigned	nonce_len,
		unsigned	tag_len
	)

inlinestaticprivate

Computes mode bits for the AES engine.

Parameters

key_len	length of the key in bytes
nonce_len	length of the nonce in bytes
tag_len	length of the authentication checksum in bytes

Definition at line 376 of file CC32xxAes.hxx.

◆ interpret_key_size()

static uint32_t CCMHelper::interpret_key_size ( unsigned key_len )

inlinestaticprivate

Computes the internal constant used for the configuration of the key size.

Parameters

key_len is the length of the key in bytes

Returns: configuration constant.

Definition at line 339 of file CC32xxAes.hxx.

◆ nonce_length_to_l()

static int CCMHelper::nonce_length_to_l ( unsigned nonce_len )

inlinestaticprivate

Compute the size of the L parameter in bytes from the nonce length.

Parameters

nonce_len is the length in bytes of the nonce value.

Returns: L value (in bytes) for the encryption.

Definition at line 358 of file CC32xxAes.hxx.

◆ process_block()

static void CCMHelper::process_block	(	const uint8_t *	din,
		uint8_t *	dout
	)

inlinestaticprivate

Performs encryption (or decryption) on a single block of data.

(cleartext/ciphertext, not the authentication data).

Parameters

din	unaligned pointer to 16 bytes of input.
dout	unaligned pointer to 16 bytes of output space.

Definition at line 429 of file CC32xxAes.hxx.

◆ read_tag()

static void CCMHelper::read_tag ( std::string * tag_out )

inlinestaticprivate

Finalizes encyrption/decryption and reads out the checksum tag.

Parameters

tag_out needs to be resized to the desired number of bytes length before calling. It will be filled with the checksum bytes.

Definition at line 438 of file CC32xxAes.hxx.

◆ reset()

static void CCMHelper::reset ( )

inlinestaticprivate

Resets / turns on the AES engine.

Definition at line 325 of file CC32xxAes.hxx.

◆ static_decrypt_init()

static void CCMHelper::static_decrypt_init	(	const std::string &	aes_key,
		const std::string &	nonce,
		const std::string &	auth_data,
		unsigned	data_len,
		uint8_t	tag_len
	)

inlinestatic

Definition at line 149 of file CC32xxAes.hxx.

◆ static_encrypt_init()

static void CCMHelper::static_encrypt_init	(	const std::string &	aes_key,
		const std::string &	nonce,
		const std::string &	auth_data,
		unsigned	data_len,
		uint8_t	tag_len
	)

inlinestatic

Definition at line 184 of file CC32xxAes.hxx.

Member Data Documentation

◆ decryptorStream_

std::unique_ptr<SyncStream> CCMHelper::decryptorStream_

private

Implementation object.

Definition at line 452 of file CC32xxAes.hxx.

◆ outputStream_

StringAppendStream* CCMHelper::outputStream_

private

Stream that catches the decrypted output in the user-provided strings.

Owned by decryptorStream_.

Definition at line 455 of file CC32xxAes.hxx.

◆ tagOut_

std::string CCMHelper::tagOut_

private

Variable that will receive the output tag.

Definition at line 457 of file CC32xxAes.hxx.

The documentation for this class was generated from the following file:

CC32xxAes.hxx

Classes

Public Member Functions

Static Public Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ create_decryptor_stream()

◆ data_finalize()

◆ data_process()

◆ decrypt()

◆ decrypt_init()

◆ encrypt()

◆ get_mode()

◆ interpret_key_size()

◆ nonce_length_to_l()

◆ process_block()

◆ read_tag()

◆ reset()

◆ static_decrypt_init()

◆ static_encrypt_init()

Member Data Documentation

◆ decryptorStream_

◆ outputStream_

◆ tagOut_