dipki::Cipher Class Reference

Generic block cipher functions. More...

Public Types
enum class	AeadAlg
	Authenticated encryption algorithm. More...
enum class	Alg
	Block cipher algorithm. More...
enum class	Mode
	Block cipher mode. More...
enum	Opts : unsigned int
	Advanced options [BitFlags]. More...
enum class	Padding
	Block cipher padding options. More...

Static Public Member Functions
static std::string	AlgName (Alg alg)
	Get the algorithm name. More...
static int	BlockBytes (Alg alg)
	Get the block size in bytes for a given cipher algorithm. More...
static bvec_t	Decrypt (const bvec_t &data, const bvec_t &key, const bvec_t &iv, Alg alg, Mode mode=Mode::ECB, Padding pad=Padding::Default, Opts opts=Opts::None)
	Decrypt data in a byte array using the specified block cipher algorithm, mode and padding. More...
static 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. More...
static bvec_t	DecryptAEAD (const bvec_t &input, const bvec_t &key, const bvec_t &iv, AeadAlg aeadAlg, Opts opts=Opts::None, const bvec_t &aad=bvec_t())
	Decrypt data using authenticated encryption with additional authenticated data (AAD). More...
static 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 bvec_t	Encrypt (const bvec_t &data, const bvec_t &key, const bvec_t &iv, Alg alg, Mode mode=Mode::ECB, Padding pad=Padding::Default, Opts opts=Opts::None)
	Encrypt data in a byte array using the specified block cipher algorithm, mode and padding. More...
static 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 bvec_t	EncryptAEAD (const bvec_t &input, const bvec_t &key, const bvec_t &iv, AeadAlg aeadAlg, Opts opts=Opts::None, const bvec_t &aad=bvec_t())
	Encrypt data using authenticated encryption with additional authenticated data (AAD). More...
static 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	FileDecrypt (const std::string &fileOut, const std::string &fileIn, const bvec_t &key, const bvec_t &iv, Alg alg, Mode mode=Mode::ECB, Padding pad=Padding::Default, Opts opts=Opts::None)
	Decrypt a file. More...
static int	FileEncrypt (const std::string &fileOut, const std::string &fileIn, const bvec_t &key, const bvec_t &iv, Alg alg, Mode mode=Mode::ECB, Padding pad=Padding::Default, Opts opts=Opts::None)
	Encrypt a file. More...
static int	KeyBytes (Alg alg)
	Get the key size in bytes for a given cipher algorithm. More...
static bvec_t	KeyUnwrap (const bvec_t &data, const bvec_t &kek, Alg alg)
	Unwrap (decrypt) key material with a key-encryption key. More...
static bvec_t	KeyWrap (const bvec_t &data, const bvec_t &kek, Alg alg)
	Wrap (encrypt) key material with a key-encryption key. More...
static bvec_t	Pad (const bvec_t &input, Alg alg, Padding pad=Padding::Pkcs5)
	Pad byte array to correct length for ECB and CBC encryption. More...
static bvec_t	Unpad (const bvec_t &input, Alg alg, Padding pad=Padding::Pkcs5)
	Remove padding from an encryption block. More...

Detailed Description

Generic block cipher functions.

Member Enumeration Documentation

AeadAlg

enum dipki::Cipher::AeadAlg

strong

Authenticated encryption algorithm.

Enumerator
Aes_128_Gcm	AEAD_AES_128_GCM authenticated encryption algorithm from RFC 5116.
Aes_192_Gcm	AES-192-GCM authenticated encryption algorithm in the same manner as RFC 5116.
Aes_256_Gcm	AEAD_AES_256_GCM authenticated encryption algorithm from RFC 5116.
ChaCha20_Poly1305	AEAD_CHACHA20_POLY1305 from RFC8439.

Alg

enum dipki::Cipher::Alg

strong

Block cipher algorithm.

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

Mode

enum dipki::Cipher::Mode

strong

Block cipher mode.

Enumerator
ECB	Electronic Code Book mode (default)
CBC	Cipher Block Chaining mode
OCB	Output Feedback mode
CFB	Cipher Feedback mode
CTR	Counter mode.
GCM	Galois/Counter mode (AES only)

Opts

enum dipki::Cipher::Opts : unsigned int

Advanced options [BitFlags].

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

Padding

enum dipki::Cipher::Padding

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 dipki::Cipher::AlgName ( Alg  alg )

static

Get the algorithm name.

Parameters

alg	Cipher algorithm

Returns

Algorithm name as a string, e.g. "AES-128".

cout << "Cipher::AlgName(dipki::Cipher::Alg::Aes256)=" << dipki::Cipher::AlgName(dipki::Cipher::Alg::Aes256) << endl;
// Cipher::AlgName(dipki::Cipher::Alg::Aes256)=AES-256

BlockBytes()

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

static

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

Parameters

alg	Cipher algorithm

Returns

Number of bytes in block.

Remarks

Spoiler: It's 8 for Triple DES and 16 for all AES variants.

cout << "Cipher::BlockBytes(dipki::Cipher::Alg::Aes256)=" << dipki::Cipher::BlockBytes(dipki::Cipher::Alg::Aes256) << endl;
// Cipher::BlockBytes(dipki::Cipher::Alg::Aes256)=16

Decrypt() [1/2]

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

static

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

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 (use Cipher::BlockBytes) or an empty vector bvec_t() for ECB mode or if IV is prefixed.
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 to 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 bvec_t dipki::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.

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 (use Cipher::BlockBytes) or an empty vector bvec_t() for ECB mode or if IV is prefixed.
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|gcm Pad: pkcs5|nopad|oneandzeroes|ansix923|w3c
opts	Advanced options. Use Cipher::Opts::PrefixIV to expect the IV to be prepended to 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. GCM mode is only available with AES.

DecryptAEAD()

static bvec_t dipki::Cipher::DecryptAEAD ( const bvec_t &  input, const bvec_t &  key, const bvec_t &  iv, AeadAlg  aeadAlg, Opts  opts = Opts::None, const bvec_t &  aad = bvec_t()  )

static

Decrypt data using authenticated encryption with additional authenticated data (AAD).

Parameters

input	Input data to be decrypted.
key	Key of exact length for algorithm (16, 24 or 32 bytes).
iv	Initialization Vector (IV) (aka nonce) exactly 12 bytes long, or an empty vector bvec_t() if IV is prefixed.
aeadAlg	Authenticated encryption algorithm.
opts	Advanced options. Use Cipher::Opts::PrefixIV to expect the IV to be prepended at the start of the input.
aad	(optional) Additional authenticated data - this must be identical to the AAD provided during encryption.

Returns

Plaintext in a byte array.

Remarks

The input must include the 16-byte tag appended to the ciphertext and may include a 12-byte prefixed IV. The output will either be exactly 16 bytes shorter than the input, or exactly 28 bytes shorter if the Cipher::Opts::PrefixIV option is used. In all cases the IV must be exactly 12 bytes (96 bits) and the tag must be exactly 16 bytes (128 bits).

DecryptBlock()

static bvec_t dipki::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.

Parameters

data	Input data to be decrypted. Must be an exact multiple of block length for ECB and CBC mode.
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

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 bvec_t dipki::Cipher::Encrypt ( const bvec_t &  data, const bvec_t &  key, const bvec_t &  iv, Alg  alg, Mode  mode = Mode::ECB, Padding  pad = Padding::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 (use 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 bvec_t dipki::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 (use 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|gcm 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. GCM mode is only available with AES.

EncryptAEAD()

static bvec_t dipki::Cipher::EncryptAEAD ( const bvec_t &  input, const bvec_t &  key, const bvec_t &  iv, AeadAlg  aeadAlg, Opts  opts = Opts::None, const bvec_t &  aad = bvec_t()  )

static

Encrypt data using authenticated encryption with additional authenticated data (AAD).

Parameters

input	Input data to be encrypted.
key	Key of exact length for algorithm (16, 24 or 32 bytes).
iv	Initialization Vector (IV) (aka nonce) exactly 12 bytes long.
aeadAlg	Authenticated encryption algorithm.
opts	Advanced options. Use Cipher::Opts::PrefixIV to prepend the 12-byte IV to the output
aad	(optional) Additional authenticated data.

Returns

Ciphertext with tag appended in a byte array, or empty array on error.

Remarks

The output will be exactly 16 bytes longer than the input, or 28 bytes longer if the IV is prefixed.

EncryptBlock()

static bvec_t dipki::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.

Parameters

data	Input data to be encrypted. Must be an exact multiple of block length for ECB and CBC mode.
key	Key of exact length for block cipher algorithm
iv	Initialization Vector (IV) of exactly the block size (use 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.

FileDecrypt()

static int dipki::Cipher::FileDecrypt ( const std::string &  fileOut, const std::string &  fileIn, const bvec_t &  key, const bvec_t &  iv, Alg  alg, Mode  mode = Mode::ECB, Padding  pad = Padding::Default, Opts  opts = Opts::None  )

static

Decrypt a file.

Parameters

fileOut	Name of output file to be created or overwritten
fileIn	Name of input file
key	Key of exact length for block cipher algorithm
iv	Initialization Vector (IV) of exactly the block size (use 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

Zero if successful.

Remarks

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

FileEncrypt()

static int dipki::Cipher::FileEncrypt ( const std::string &  fileOut, const std::string &  fileIn, const bvec_t &  key, const bvec_t &  iv, Alg  alg, Mode  mode = Mode::ECB, Padding  pad = Padding::Default, Opts  opts = Opts::None  )

static

Encrypt a file.

Parameters

fileOut	Name of output file to be created or overwritten
fileIn	Name of input file
key	Key of exact length for block cipher algorithm
iv	Initialization Vector (IV) of exactly the block size (use 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

Zero if successful.

Remarks

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

KeyBytes()

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

static

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

Parameters

alg	Cipher algorithm

Returns

Number of bytes in key.

cout << "Cipher::KeyBytes(dipki::Cipher::Alg::Aes256)=" << dipki::Cipher::KeyBytes(dipki::Cipher::Alg::Aes256) << endl;
// Cipher::KeyBytes(dipki::Cipher::Alg::Aes256)=32

KeyUnwrap()

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

static

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

Parameters

data	Wrapped key.
kek	Key encryption key of exact length for key wrap algorithm.
alg	Block cipher to use for wrapping.

Returns

Unwrapped key material (or empty array on error).

KeyWrap()

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

static

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

Parameters

data	Key material to be wrapped.
kek	Key encryption key of exact length for key wrap algorithm.
alg	Block cipher to use for wrapping.

Returns

Wrapped key (or empty array on error).

Remarks

This wraps (encrypts) key material using a key encryption key (KEK) and uses either the AES Key Wrap Algorithm from [RFC3394] or the Triple-DES Key Wrap algorithm from [RFC3217]. The input data to be wrapped must be a valid length for the underlying data encapsulation mechanism; specifically, at least 16 bytes and a multiple of 8 bytes for AES, or exactly 24 bytes for Triple DES. An AES-wrapped key is exactly 8 bytes longer than the input; a triple-DES-wrapped key is 16 bytes longer.

Pad()

static bvec_t dipki::Cipher::Pad ( const bvec_t &  input, Alg  alg, Padding  pad = Padding::Pkcs5  )

static

Pad byte array to correct length for ECB and CBC encryption.

Parameters

input	Data to be padded
alg	Block cipher being used
pad	Padding method to use (default is PKCS#5/#7)

Returns

Padded data in byte array

dipki::bvec_t input = dipki::Cnv::FromHex("FDFDFDFDFD");
cout << "Input data =  0x" << dipki::Cnv::ToHex(input) << endl;
dipki::bvec_t block = dipki::Cipher::Pad(input, dipki::Cipher::Alg::Tdea);
cout << "Padded data = 0x" << dipki::Cnv::ToHex(block) << endl;
// Input data =  0xFDFDFDFDFD
// Padded data = 0xFDFDFDFDFD030303

Unpad()

static bvec_t dipki::Cipher::Unpad ( const bvec_t &  input, Alg  alg, Padding  pad = Padding::Pkcs5  )

static

Remove padding from an encryption block.

Parameters

input	Padded data
alg	Block cipher being used
pad	Padding method to use (default is PKCS#5/#7)

Returns

Unpadded data in byte array.

Exceptions

std::runtime_error

Exception with error code.