Generic block cipher functions. More...

Public Types
enum class	Alg
	Block cipher algorithm. More...

enum class	Mode
	Block cipher mode. More...

enum	Opts : unsigned int
	Advanced options. More...

enum class	Pad
	Block cipher padding options. More...

Public Member Functions
bool	Final ()
	Clear the Cipher object. More...

bool	InitDecrypt (const bvec_t &key, const bvec_t &iv, Alg alg, Mode mode)
	Initialise the Cipher object ready for repeated incremental decryption operations. More...

bool	InitEncrypt (const bvec_t &key, const bvec_t &iv, Alg alg, Mode mode)
	Initialise the Cipher object ready for repeated incremental encryption operations. More...

crsysapi::bvec_t	Update (const bvec_t &data)
	Transform byte input data with previously initialized key, mode and direction. More...

Static Public Member Functions
static std::string	AlgName (Alg alg)
	Get the algorithm name as a string. More...

static int	BlockBytes (Alg alg)
	Get the block size in bytes for a given cipher algorithm. More...

static crsysapi::bvec_t	Decrypt (const bvec_t &data, const bvec_t &key, const bvec_t &iv, Alg alg, Mode mode=Mode::ECB, Pad pad=Pad::Default, Opts opts=Opts::None)
	Decrypt data in a byte array using the specified block cipher algorithm, mode and padding, with advanced options. More...

static crsysapi::bvec_t	Decrypt (const bvec_t &data, const bvec_t &key, const bvec_t &iv, const std::string &algModePad, Opts opts=Opts::None)
	Decrypt data in a byte array using the specified block cipher algorithm, mode and padding, with advanced options. More...

static crsysapi::bvec_t	DecryptBlock (const bvec_t &data, const bvec_t &key, const bvec_t &iv, Alg alg, Mode mode=Mode::ECB)
	Decrypt a block of data. More...

static crsysapi::bvec_t	Encrypt (const bvec_t &data, const bvec_t &key, const bvec_t &iv, Alg alg, Mode mode=Mode::ECB, Pad pad=Pad::Default, Opts opts=Opts::None)
	Encrypt data in a byte array using the specified block cipher algorithm, mode and padding. More...

static crsysapi::bvec_t	Encrypt (const bvec_t &data, const bvec_t &key, const bvec_t &iv, const std::string &algModePad, Opts opts=Opts::None)
	Encrypt data in a byte array using the specified block cipher algorithm, mode and padding. More...

static crsysapi::bvec_t	EncryptBlock (const bvec_t &data, const bvec_t &key, const bvec_t &iv, Alg alg, Mode mode=Mode::ECB)
	Encrypt a block of data. More...

static int	KeyBytes (Alg alg)
	Get the key size in bytes for a given cipher algorithm. More...

static crsysapi::bvec_t	KeyUnwrap (const bvec_t &data, const bvec_t &kek, Alg alg)
	Unwrap (decrypt) encrypted key material with a key-encryption key. More...

static crsysapi::bvec_t	KeyWrap (const bvec_t &data, const bvec_t &kek, Alg alg)
	Wrap (encrypt) key material with a key-encryption key. More...

static std::string	ModeName (Mode mode)
	Get mode name as a string. More...

Detailed Description

Generic block cipher functions.

Member Enumeration Documentation

◆ Alg

enum crsysapi::Cipher::Alg

strong

Block cipher algorithm.

Enumerator
Tdea	Triple DES (3DES, des-ede3)
Aes128	AES-128.
Aes192	AES-192.
Aes256	AES-256.

◆ Mode

enum crsysapi::Cipher::Mode

strong

Block cipher mode.

Enumerator
ECB	Electronic Code Book mode (default)
CBC	Cipher Block Chaining mode
OFB	Output Feedback mode
CFB	Cipher Feedback mode
CTR	Counter mode.

◆ Opts

enum crsysapi::Cipher::Opts : unsigned int

Advanced options.

Enumerator
None	Use default options.
PrefixIV	Prepend the IV before the ciphertext in the output (ignored for ECB mode)

◆ Pad

enum crsysapi::Cipher::Pad

strong

Block cipher padding options.

Enumerator
Default	Use default padding.
NoPad	No padding is added.
Pkcs5	The padding scheme described in PKCS#5/#7.
OneAndZeroes	Pad with 0x80 followed by as many zero bytes necessary to fill the block.
AnsiX923	The padding scheme described in ANSI X9.23.
W3CPadding	The padding scheme described in W3C https://www.w3.org/TR/xmlenc-core1/#sec-Padding

Member Function Documentation

◆ AlgName()

static std::string crsysapi::Cipher::AlgName ( Alg alg )

static

Get the algorithm name as a string.

Parameters

alg	Cipher algorithm

Returns: Name of algorithm.

◆ BlockBytes()

static int crsysapi::Cipher::BlockBytes ( Alg alg )

static

Get the block size in bytes for a given cipher algorithm.

Parameters

alg	Cipher algorithm

Returns: Block size in bytes.

◆ Decrypt() [1/2]

static crsysapi::bvec_t crsysapi::Cipher::Decrypt	(	const bvec_t &	data,
		const bvec_t &	key,
		const bvec_t &	iv,
		Alg	alg,
		Mode	mode = `Mode::ECB`,
		Pad	pad = `Pad::Default`,
		Opts	opts = `Opts::None`
	)

static

Decrypt data in a byte array using the specified block cipher algorithm, mode and padding, with advanced options.

Parameters

data	Input data to be decrypted
key	Key of exact length for block cipher algorithm
iv	Initialization Vector (IV) of exactly the block size (see Cipher::BlockBytes()) or an empty vector `bvec_t()` for ECB mode
alg	Cipher algorithm
mode	Cipher mode
pad	Padding method to use
opts	Advanced options. Use `Cipher::Opts::PrefixIV` to expect the IV to be prepended at the start of the input.

Returns: Decrypted plaintext in byte array or empty array on error

Remarks: Default padding is Pkcs5 for ECB and CBC mode and NoPad for all other modes. It is an error if the specified padding is not found after decryption.

◆ Decrypt() [2/2]

static crsysapi::bvec_t crsysapi::Cipher::Decrypt	(	const bvec_t &	data,
		const bvec_t &	key,
		const bvec_t &	iv,
		const std::string &	algModePad,
		Opts	opts = `Opts::None`
	)

static

Decrypt data in a byte array using the specified block cipher algorithm, mode and padding, with advanced options.

Parameters

data	Input data to be decrypted
key	Key of exact length for block cipher algorithm
iv	Initialization Vector (IV) of exactly the block size (see Cipher::BlockBytes()) or an empty vector `bvec_t()` for ECB mode
algModePad	String with block cipher algorithm, mode and padding, e.g. "aes128/cbc/pkcs5" Alg: aes128\|aes192\|aes256\|tdea\|3des\|desede3 Mode: ecb\|cbc\|ofb\|cfb\|ctr Pad: pkcs5\|nopad\|oneandzeroes\|ansix923\|w3c
opts	Advanced options. Use `Cipher::Opts::PrefixIV` to expect the IV to be prepended at the start of the input.

Returns: Decrypted plaintext in byte array or empty array on error

Remarks: Default padding is Pkcs5 for ECB and CBC mode and NoPad for all other modes. It is an error if the specified padding is not found after decryption.

◆ DecryptBlock()

static crsysapi::bvec_t crsysapi::Cipher::DecryptBlock	(	const bvec_t &	data,
		const bvec_t &	key,
		const bvec_t &	iv,
		Alg	alg,
		Mode	mode = `Mode::ECB`
	)

static

Decrypt a block of data.

Must be an exact multiple of block length.

Parameters

data	Input data to be decrypted
key	Key of exact length for block cipher algorithm
iv	Initialization Vector (IV) of exactly the block size (see Cipher::BlockBytes()) or an empty vector `bvec_t()` for ECB mode
alg	Cipher algorithm (required)
mode	Cipher mode (default = ECB)

Returns: Decrypted plaintext in byte array. Output is always the same length as the input.

Exceptions

std::runtime_error Exception with error code.

◆ Encrypt() [1/2]

static crsysapi::bvec_t crsysapi::Cipher::Encrypt	(	const bvec_t &	data,
		const bvec_t &	key,
		const bvec_t &	iv,
		Alg	alg,
		Mode	mode = `Mode::ECB`,
		Pad	pad = `Pad::Default`,
		Opts	opts = `Opts::None`
	)

static

Encrypt data in a byte array using the specified block cipher algorithm, mode and padding.

Parameters

data	Input data to be encrypted
key	Key of exact length for block cipher algorithm
iv	Initialization Vector (IV) of exactly the block size (see Cipher::BlockBytes()) or an empty vector `bvec_t()` for ECB mode
alg	Cipher algorithm
mode	Cipher mode
pad	Padding method to use
opts	Advanced options. Use `Cipher::Opts::PrefixIV` to prepend the IV to the output.

Returns: Ciphertext in byte array or empty array on error

Remarks: Default padding is Pkcs5 for ECB and CBC mode and NoPad for all other modes.

◆ Encrypt() [2/2]

static crsysapi::bvec_t crsysapi::Cipher::Encrypt	(	const bvec_t &	data,
		const bvec_t &	key,
		const bvec_t &	iv,
		const std::string &	algModePad,
		Opts	opts = `Opts::None`
	)

static

Encrypt data in a byte array using the specified block cipher algorithm, mode and padding.

Parameters

data	Input data to be encrypted
key	Key of exact length for block cipher algorithm
iv	Initialization Vector (IV) of exactly the block size (see Cipher::BlockBytes()) or an empty vector `bvec_t()` for ECB mode
algModePad	String with block cipher algorithm, mode and padding, e.g. "aes128/cbc/pkcs5" Alg: aes128\|aes192\|aes256\|tdea\|3des\|desede3 Mode: ecb\|cbc\|ofb\|cfb\|ctr Pad: pkcs5\|nopad\|oneandzeroes\|ansix923\|w3c
opts	Advanced options. Use `Cipher::Opts::PrefixIV` to prepend the IV to the output.

Returns: Ciphertext in byte array or empty array on error

Remarks: Default padding is Pkcs5 for ECB and CBC mode and NoPad for all other modes.

◆ EncryptBlock()

static crsysapi::bvec_t crsysapi::Cipher::EncryptBlock	(	const bvec_t &	data,
		const bvec_t &	key,
		const bvec_t &	iv,
		Alg	alg,
		Mode	mode = `Mode::ECB`
	)

static

Encrypt a block of data.

Must be an exact multiple of block length.

Parameters

data	Input data to be encrypted
key	Key of exact length for block cipher algorithm
iv	Initialization Vector (IV) of exactly the block size (see Cipher::BlockBytes()) or an empty vector `bvec_t()` for ECB mode
alg	Cipher algorithm (required)
mode	Cipher mode (default = ECB)

Returns: Ciphertext in byte array. Output is always the same length as the input.

Exceptions

std::runtime_error Exception with error code.

◆ Final()

bool crsysapi::Cipher::Final ( )

Clear the Cipher object.

Returns: True if successful.

◆ InitDecrypt()

bool crsysapi::Cipher::InitDecrypt	(	const bvec_t &	key,
		const bvec_t &	iv,
		Alg	alg,
		Mode	mode
	)

Initialise the Cipher object ready for repeated incremental decryption operations.

Parameters

key	Key of exact length for block cipher algorithm
iv	Initialization Vector (IV) of exactly the block size (see Cipher::BlockBytes()) or an empty vector `bvec_t()` for ECB mode
alg	Cipher algorithm to be used
mode	Cipher mode

Returns: True if successful.

◆ InitEncrypt()

bool crsysapi::Cipher::InitEncrypt	(	const bvec_t &	key,
		const bvec_t &	iv,
		Alg	alg,
		Mode	mode
	)

Initialise the Cipher object ready for repeated incremental encryption operations.

Parameters

key	Key of exact length for block cipher algorithm
iv	Initialization Vector (IV) of exactly the block size (see Cipher::BlockBytes()) or an empty vector `bvec_t()` for ECB mode
alg	Cipher algorithm to be used
mode	Cipher mode

Returns: True if successful.

◆ KeyBytes()

static int crsysapi::Cipher::KeyBytes ( Alg alg )

static

Get the key size in bytes for a given cipher algorithm.

Parameters

alg	Cipher algorithm

Returns: Key size in bytes.

◆ KeyUnwrap()

static crsysapi::bvec_t crsysapi::Cipher::KeyUnwrap	(	const bvec_t &	data,
		const bvec_t &	kek,
		Alg	alg
	)

static

Unwrap (decrypt) encrypted key material with a key-encryption key.

Parameters

data	Input data to be decrypted
kek	Key encryption key
alg	Cipher algorithm (required)

Returns: Unwrapped key material in byte array.

Exceptions

std::runtime_error Exception with error code.

◆ KeyWrap()

static crsysapi::bvec_t crsysapi::Cipher::KeyWrap	(	const bvec_t &	data,
		const bvec_t &	kek,
		Alg	alg
	)

static

Wrap (encrypt) key material with a key-encryption key.

Parameters

data	Input key material to be encrypted
kek	Key encryption key
alg	Cipher algorithm (required)

Returns: Wrapped key in byte array.

Exceptions

std::runtime_error Exception with error code.

◆ ModeName()

static std::string crsysapi::Cipher::ModeName ( Mode mode )

static

Get mode name as a string.

Parameters

mode	Block cipher mode

Returns: Name of block cipher mode.

◆ Update()

crsysapi::bvec_t crsysapi::Cipher::Update ( const bvec_t & data )

Transform byte input data with previously initialized key, mode and direction.

Parameters

data	Input data

Returns: Transformed data

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Alg

◆ Mode

◆ Opts

◆ Pad

Member Function Documentation

◆ AlgName()

◆ BlockBytes()

◆ Decrypt() [1/2]

◆ Decrypt() [2/2]

◆ DecryptBlock()

◆ Encrypt() [1/2]

◆ Encrypt() [2/2]

◆ EncryptBlock()

◆ Final()

◆ InitDecrypt()

◆ InitEncrypt()

◆ KeyBytes()

◆ KeyUnwrap()

◆ KeyWrap()

◆ ModeName()

◆ Update()