Interface to encrypt and decrypt Bytes data to/from a secure string. More...

#include <datacrypt.hpp>

Public Types
enum	Cipher { Cipher::EVP_aes_128_gcm, Cipher::EVP_aes_192_gcm, Cipher::EVP_aes_256_gcm, Default = EVP_aes_256_gcm, Invalid }
	Cipher selection. More...

Static Public Member Functions
static int	blockOctets (Cipher cipher)
	Return the block size of the Cipher in octets. More...

static std::string	cipher2String (const Cipher &cipher)
	String representation of an Cipher instance. More...

static int	decrypt (const std::string &key, const std::string src, Bytes &dest)
	Decrypt data with a key. More...

static void	encrypt (Cipher cipher, const std::string &key, const Bytes &src, std::string &dst)
	Encrypt data with a key into a string (so the encrypted data will not contain a 0/zero). More...

static int	ivOctets (Cipher cipher)
	Return the size of the IV (initialization vector) for the given Cipher in bits. More...

static int	keyOctets (Cipher cipher)
	Return the size of the key for the given Cipher in bits. More...

static Cipher	string2Cipher (const std::string &s)
	Convert a string representation to an Cipher. More...

static int	tagLength (Cipher cipher)
	Return the tag length of the Cipher in octets. More...

Static Private Member Functions
static size_t	cipherOctets (Cipher cipher, size_t octets)
	Calculate the size of the encrypted data from the input size. More...

static bool	decode (const std::string &src, std::string &cipher, std::string &data, std::string &iv, std::string &tag)
	Decode an ENC[] string into its parts. More...

static std::string	paddedKey (Cipher cipher, const std::string key)
	Pad or trim a key to match the key size for the Cipher. More...

Detailed Description

Interface to encrypt and decrypt Bytes data to/from a secure string.

Intended for smaller secrets such as passwords, works for larger data volumes but with a time penalty, encryption/decryption of 10MiB on a 3.4GHz Corei7 takes 0.8s/0.7s. Ideal for deployment configuration data.

The format of the encrypted string is

ENC[cipher:{cipher},data:{encrypted data},iv:{initialization vector},tag:{tag}]

for example

ENC[cipher:EVP_aes_256_gcm,data:dOxteDqw7POETW6RnDwWGVOUHkGf5OE7S1UY157ZEDx0Fv5vc9c=,iv:/GXteCh6FEt2IZbmgBurjA==,tag:WgKBIu/JgCZivZRTtb5A9Q==]

As the only external data required to decrypt is the key, and the other information required to decrypt included in the encrypted string, it is robust against change and not coupled to specific programs or programming languages. In fact, if the encryption uses DataCrypt::Cipher::Default, a simple decrypt/encrypt cycle will move to newer ciphers without changing any code.

The IV and tag are not secrets. The iv needs to be random to prevent entropy loss with access to multiple encrypted strings generated with the same key. The encrypt function will take care of generating unique IV's for each call to encrypt. The tag is used to verify the decryption success, and is generated internally upon encrypt.

The available DataCrypt::Cipher choices are

cipher	key size in bytes (octets)
EVP_aes_128_gcm	16
EVP_aes_192_gcm	24
EVP_aes_256_gcm	32

If the provided key size is smaller, it is padded by repeating the specified key until filled. Use EVP_aes_256_gcm with a strong 32 byte key for maximum safety.

Only the data size in the encrypted string will depend on the size of the original data. The encrypted string data will be around 1.4 times larger for an original data size of 38 bytes, and about 1.3 times for an original data size of 240 bytes.

Definition at line 74 of file datacrypt.hpp.

Member Enumeration Documentation

◆ Cipher

enum dodo::common::DataCrypt::Cipher

strong

Cipher selection.

GCM is the more secure block cipher, smaller key sizes ought to be faster at the expense of work required to crack.

Enumerator
EVP_aes_128_gcm	https://www.openssl.org/docs/man1.0.2/man3/EVP_aes_128_gcm.html
EVP_aes_192_gcm	https://www.openssl.org/docs/man1.0.2/man3/EVP_aes_192_gcm.html
EVP_aes_256_gcm	https://www.openssl.org/docs/man1.0.2/man3/EVP_aes_256_gcm.html

Definition at line 81 of file datacrypt.hpp.

Member Function Documentation

◆ blockOctets()

static int dodo::common::DataCrypt::blockOctets ( Cipher cipher )

inlinestatic

Return the block size of the Cipher in octets.

Parameters

cipher The Cipher

Returns: The size of the block in octets.

Definition at line 124 of file datacrypt.hpp.

References EVP_aes_128_gcm, EVP_aes_192_gcm, and EVP_aes_256_gcm.

Referenced by cipherOctets().

Here is the caller graph for this function:

◆ cipher2String()

static std::string dodo::common::DataCrypt::cipher2String ( const Cipher & cipher )

inlinestatic

String representation of an Cipher instance.

Parameters

cipher The Cipher to get the iv bit size for.

Returns: The string representation.

Definition at line 154 of file datacrypt.hpp.

References EVP_aes_128_gcm, EVP_aes_192_gcm, and EVP_aes_256_gcm.

Referenced by encrypt(), and string2Cipher().

Here is the caller graph for this function:

◆ cipherOctets()

static size_t dodo::common::DataCrypt::cipherOctets	(	Cipher	cipher,
		size_t	octets
	)

inlinestaticprivate

Calculate the size of the encrypted data from the input size.

Parameters

cipher	The Cipher to calculate for.
octets	The number of octets in the data to encrypt.

Returns: The size of the encrypted data.

Definition at line 209 of file datacrypt.hpp.

References blockOctets().

Referenced by encrypt().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ decode()

bool dodo::common::DataCrypt::decode	(	const std::string &	src,
		std::string &	cipher,
		std::string &	data,
		std::string &	iv,
		std::string &	tag
	)

staticprivate

Decode an ENC[] string into its parts.

Parameters

src	The source encrypt string.
cipher	The cipher string part.
data	The data string part.
iv	The iv string part.
tag	The tag string part.

Returns: false if the decode failed / invalid src string.

Definition at line 101 of file datacrypt.cpp.

References dodo::common::split().

Referenced by decrypt().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ decrypt()

int dodo::common::DataCrypt::decrypt	(	const std::string &	key,
		const std::string	src,
		Bytes &	dest
	)

static

Decrypt data with a key.

Parameters

key	The key to decrypt with.
src	The source data to decrypt.
dest	The Bytes that will receive the decrypted data. The caller will become owner of the pointer in Bytes and responsible for cleaning it up with free().