A SymmetricKey can be used to seal and unseal messages. This SymmetricKey class can be (re) derived from a seed using set of recipe specified in JSON Format for Recipes. So, you can use this symmetric-key to seal a message, throw the key away, and re-generate the key when you need to unseal the message so long as you still have the original seed and recipe. More...

#include <symmetric-key.hpp>

Public Member Functions
	SymmetricKey (const SodiumBuffer &keyBytes, std::string recipe)
	Construct a SymmetricKey from its members.

	SymmetricKey (const SymmetricKey &other)
	Construct a SymmetricKey by copying another one.

	SymmetricKey (const std::string &seedString, const std::string &recipe)
	Construct a new SymmetricKey by (re)deriving it from a seed string and a set of recipe in JSON Format for Recipes. More...

const std::vector< unsigned char >	sealToCiphertextOnly (const unsigned char *message, const size_t messageLength, const std::string &unsealingInstructions={}) const
	Seal a plaintext message. More...

const std::vector< unsigned char >	sealToCiphertextOnly (const SodiumBuffer &message, const std::string &unsealingInstructions={}) const
	Seal a plaintext message. More...

const PackagedSealedMessage	seal (const SodiumBuffer &message, const std::string &unsealingInstructions={}) const
	Seal a plaintext message. More...

const PackagedSealedMessage	seal (const std::string &message, const std::string &unsealingInstructions={}) const
	Seal a plaintext message. More...

const PackagedSealedMessage	seal (const std::vector< unsigned char > &message, const std::string &unsealingInstructions={}) const
	Seal a plaintext message. More...

const PackagedSealedMessage	seal (const unsigned char *message, const size_t messageLength, const std::string &unsealingInstructions={}) const
	Seal a plaintext message. More...

const SodiumBuffer	unseal (const unsigned char *ciphertext, const size_t ciphertextLength, const std::string &unsealingInstructions={}) const
	Unseal a message. More...

const SodiumBuffer	unseal (const std::vector< unsigned char > &ciphertext, const std::string &unsealingInstructions={}) const
	Unseal a message. More...

const SodiumBuffer	unseal (const PackagedSealedMessage &packagedSealedMessage) const
	Unseal a message by re-deriving the SymmetricKey from a seed. More...

const std::string	toJson (int indent=-1, const char indent_char=' ') const
	Serialize this object to a JSON-formatted string. More...

const SodiumBuffer	toSerializedBinaryForm () const
	Serialize to byte array as a list of: (keyBytes, recipe) More...

Static Public Member Functions
static SymmetricKey	deriveFromSeed (const std::string &seedString, const std::string &recipe)
	Construct a new SymmetricKey by (re)deriving it from a seed string and a set of recipe in JSON Format for Recipes. More...

static const SodiumBuffer	unseal (const PackagedSealedMessage &packagedSealedMessage, const std::string &seedString)
	Unseal a message by re-deriving the SymmetricKey from a seed. More...

static SymmetricKey	fromSerializedBinaryForm (const SodiumBuffer &serializedBinaryForm)
	Deserialize from a byte array stored as a list of: (keyBytes, recipe) More...

static SymmetricKey	fromJson (const std::string &symmetricKeyAsJson)
	Internal implementation of JSON parser for the JSON contructor.

Public Attributes
const SodiumBuffer	keyBytes
	The binary representation of the symmetric key. More...

const std::string	recipe
	A JSON Format for Recipes string used to specify how this key is derived.

Protected Member Functions
const SodiumBuffer	unsealMessageContents (const unsigned char *ciphertext, const size_t ciphertextLength, const std::string &unsealingInstructions={}) const
	Internal implementation of unseal.

Detailed Description

A SymmetricKey can be used to seal and unseal messages. This SymmetricKey class can be (re) derived from a seed using set of recipe specified in JSON Format for Recipes. So, you can use this symmetric-key to seal a message, throw the key away, and re-generate the key when you need to unseal the message so long as you still have the original seed and recipe.

Sealing a message (plaintext) creates a _ciphertext which contains the message but from which observers who do not have the UnsealingKey cannot discern the contents of the message. Sealing also provides integrity-protection, which will preven the message from being unsealed if it is modified. We use the verbs seal and unseal, rather than encrypt and decrypt, because the encrypting alone does not confer that the message includes an integrity (message authentication) code to prove that the ciphertext has not been tampered with.

The seal operation is built on LibSodium's crypto_secretbox_easy function, but despite it's name the construct isn't as easy as it should be. The caller must store both the ciphertext AND a 24-byte nonce (crypto_secretbox_NONCEBYTES = 24). Hence, the SymmetricKey seal operation outputs a composite ciphertext containing the nonce followed by the "secret box" ciphertext generated by LibSodium. Since the "secret box" is 16 bytes longer than the message size (crypto_secretbox_MACBYTES = 16), the composite ciphertext is is 40 bytes longer than the message length (24 for then nonce, plus the 16 added to create the secret box)

Constructor & Destructor Documentation

◆ SymmetricKey()

SymmetricKey::SymmetricKey	(	const std::string &	seedString,
		const std::string &	recipe
	)

Construct a new SymmetricKey by (re)deriving it from a seed string and a set of recipe in JSON Format for Recipes.

Parameters

seedString	The private seed which is used to generate the key. Anyone who knows (or can guess) this seed can re-generate the key by passing it along with the recipe.
recipe	The recipe in JSON Format for Recipes.

Member Function Documentation

◆ deriveFromSeed()

SymmetricKey SymmetricKey::deriveFromSeed	(	const std::string &	seedString,
		const std::string &	recipe
	)

static

Construct a new SymmetricKey by (re)deriving it from a seed string and a set of recipe in JSON Format for Recipes.

Parameters

seedString	The private seed which is used to generate the key. Anyone who knows (or can guess) this seed can re-generate the key by passing it along with the recipe.
recipe	The recipe in JSON Format for Recipes.

◆ fromSerializedBinaryForm()

SymmetricKey SymmetricKey::fromSerializedBinaryForm ( const SodiumBuffer & serializedBinaryForm )

static

Deserialize from a byte array stored as a list of: (keyBytes, recipe)

Stored in SodiumBuffer's fixed-length list format. Strings are stored as UTF8 byte arrays.

◆ seal() [1/4]

const PackagedSealedMessage SymmetricKey::seal	(	const SodiumBuffer &	message,
		const std::string &	unsealingInstructions = `{}`
	)		const

Seal a plaintext message.

Parameters

message	The plaintxt message to seal
unsealingInstructions	If this optional string is passed, the same string must be passed to unseal the message. It can be used to pair a sealed message with public instructions about what should happen after the message is unsealed.

Returns: PackagedSealedMessage Everything needed to re-derive the SymmetricKey from the seed (except the seed string iteslf) and unseal the message.

◆ seal() [2/4]

const PackagedSealedMessage SymmetricKey::seal	(	const std::string &	message,
		const std::string &	unsealingInstructions = `{}`
	)		const

Seal a plaintext message.

Parameters

message	The plaintxt message to seal
unsealingInstructions	If this optional string is passed, the same string must be passed to unseal the message. It can be used to pair a sealed message with public instructions about what should happen after the message is unsealed.

Returns: PackagedSealedMessage Everything needed to re-derive the SymmetricKey from the seed (except the seed string iteslf) and unseal the message.

◆ seal() [3/4]

const PackagedSealedMessage SymmetricKey::seal	(	const std::vector< unsigned char > &	message,
		const std::string &	unsealingInstructions = `{}`
	)		const

Seal a plaintext message.

Parameters

message	The plaintxt message to seal
unsealingInstructions	If this optional string is passed, the same string must be passed to unseal the message. It can be used to pair a sealed message with public instructions about what should happen after the message is unsealed.

Returns: PackagedSealedMessage Everything needed to re-derive the SymmetricKey from the seed (except the seed string iteslf) and unseal the message.

◆ seal() [4/4]

const PackagedSealedMessage SymmetricKey::seal	(	const unsigned char *	message,
		const size_t	messageLength,
		const std::string &	unsealingInstructions = `{}`
	)		const

Seal a plaintext message.

Parameters

message	The plaintxt message to seal
messageLength	The length of the plaintext message to seal
unsealingInstructions	If this optional string is passed, the same string must be passed to unseal the message. It can be used to pair a sealed message with public instructions about what should happen after the message is unsealed.

Returns: PackagedSealedMessage Everything needed to re-derive the SymmetricKey from the seed (except the seed string iteslf) and unseal the message.

◆ sealToCiphertextOnly() [1/2]

const std::vector< unsigned char > SymmetricKey::sealToCiphertextOnly	(	const SodiumBuffer &	message,
		const std::string &	unsealingInstructions = `{}`
	)		const

Seal a plaintext message.

Parameters

message	The plaintxt message to seal
unsealingInstructions	If this optional string is passed, the same string must be passed to unseal the message. It can be used to pair a sealed message with public instructions about what should happen after the message is unsealed.

Returns: const std::vector<unsigned char> The sealed ciphertext without the additional context needed to unseal (the recipe required to re-derive the key and any unsealingInstructions which must match on unsealing.)

◆ sealToCiphertextOnly() [2/2]

const std::vector< unsigned char > SymmetricKey::sealToCiphertextOnly	(	const unsigned char *	message,
		const size_t	messageLength,
		const std::string &	unsealingInstructions = `{}`
	)		const

Seal a plaintext message.

Parameters

message	The plaintxt message to seal
messageLength	The length of the plaintext message in bytes
unsealingInstructions	If this optional string is passed, the same string must be passed to unseal the message.

Returns: const std::vector<unsigned char> The sealed ciphertext without the additional context needed to unseal (the recipe required to re-derive the key and any unsealingInstructions which must match on unsealing.)

◆ toJson()

const std::string SymmetricKey::toJson	(	int	indent = `-1`,
		const char	indent_char = `' '`
	)		const

Serialize this object to a JSON-formatted string.

It can be reconstituted by calling the constructor with this string.

Parameters

indent	The number of characters to indent the JSON (optional)
indent_char	The character with which to indent the JSON (optional)

Returns: const std::string A SymmetricKey serialized to JSON format.

◆ toSerializedBinaryForm()

const SodiumBuffer SymmetricKey::toSerializedBinaryForm ( ) const

Serialize to byte array as a list of: (keyBytes, recipe)

Stored in SodiumBuffer's fixed-length list format. Strings are stored as UTF8 byte arrays.

◆ unseal() [1/4]

const SodiumBuffer SymmetricKey::unseal ( const PackagedSealedMessage & packagedSealedMessage ) const

Unseal a message by re-deriving the SymmetricKey from a seed.

Parameters

packagedSealedMessage The message to be unsealed

Returns: const SodiumBuffer The plaintesxt message that had been sealed

◆ unseal() [2/4]

const SodiumBuffer SymmetricKey::unseal	(	const PackagedSealedMessage &	packagedSealedMessage,
		const std::string &	seedString
	)

static

Unseal a message by re-deriving the SymmetricKey from a seed.

Parameters

seedString	The seed string used to generate the SymmetricKey that sealed this message
packagedSealedMessage	The message to be unsealed

Returns: const SodiumBuffer The plaintesxt message that had been sealed

◆ unseal() [3/4]

const SodiumBuffer SymmetricKey::unseal	(	const std::vector< unsigned char > &	ciphertext,
		const std::string &	unsealingInstructions = `{}`
	)		const

Unseal a message.

Parameters

ciphertext	The sealed message to be unsealed
unsealingInstructions	If this optional value was set during the SymmetricKey::seal operation, the same value must be provided to unseal the message or the operation will fail.

Returns: const SodiumBuffer

Exceptions

CryptographicVerificationFailureException Thrown if the ciphertext is not valid and cannot be unsealed.

◆ unseal() [4/4]

const SodiumBuffer SymmetricKey::unseal	(	const unsigned char *	ciphertext,
		const size_t	ciphertextLength,
		const std::string &	unsealingInstructions = `{}`
	)		const

Unseal a message.

Parameters

ciphertext	The sealed message to be unsealed
ciphertextLength	The length of the sealed message
unsealingInstructions	If this optional value was set during the SymmetricKey::seal operation, the same value must be provided to unseal the message or the operation will fail. It can be used to pair a secret (sealed) message with public instructions about what should happen after the message is unsealed.

Returns: const SodiumBuffer

Exceptions

CryptographicVerificationFailureException Thrown if the ciphertext is not valid and cannot be unsealed.

Member Data Documentation

◆ keyBytes

const SodiumBuffer SymmetricKey::keyBytes

The binary representation of the symmetric key.

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

C:/Users/stuar/git/dicekeys-seeded-crypto/lib-seeded/symmetric-key.hpp
C:/Users/stuar/git/dicekeys-seeded-crypto/lib-seeded/symmetric-key.cpp

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SymmetricKey()

Member Function Documentation

◆ deriveFromSeed()

◆ fromSerializedBinaryForm()

◆ seal() [1/4]

◆ seal() [2/4]

◆ seal() [3/4]

◆ seal() [4/4]

◆ sealToCiphertextOnly() [1/2]

◆ sealToCiphertextOnly() [2/2]

◆ toJson()

◆ toSerializedBinaryForm()

◆ unseal() [1/4]

◆ unseal() [2/4]

◆ unseal() [3/4]

◆ unseal() [4/4]

Member Data Documentation

◆ keyBytes