DiceKeys Seeded Cryptography Library
SymmetricKey Class Reference

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
seedStringThe 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.
recipeThe 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
seedStringThe 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.
recipeThe 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
messageThe plaintxt message to seal
unsealingInstructionsIf 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
messageThe plaintxt message to seal
unsealingInstructionsIf 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
messageThe plaintxt message to seal
unsealingInstructionsIf 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
messageThe plaintxt message to seal
messageLengthThe length of the plaintext message to seal
unsealingInstructionsIf 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
messageThe plaintxt message to seal
unsealingInstructionsIf 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
messageThe plaintxt message to seal
messageLengthThe length of the plaintext message in bytes
unsealingInstructionsIf 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
indentThe number of characters to indent the JSON (optional)
indent_charThe 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
packagedSealedMessageThe 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
seedStringThe seed string used to generate the SymmetricKey that sealed this message
packagedSealedMessageThe 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
ciphertextThe sealed message to be unsealed
unsealingInstructionsIf 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
CryptographicVerificationFailureExceptionThrown 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
ciphertextThe sealed message to be unsealed
ciphertextLengthThe length of the sealed message
unsealingInstructionsIf 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
CryptographicVerificationFailureExceptionThrown 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: