A sealingKeyBytes is used to seal messages, in combination with a UnsealingKey which can unseal them. The key pair of this sealingKeyBytes and the matching UnsealingKey are generated from a seed and a set of options in JSON format JSON Format for Recipes. More...

#include <sealing-key.hpp>

Public Member Functions
	SealingKey (const std::vector< unsigned char > &sealingKeyBytes, const std::string &recipe)
	Construct a new Public Key object by passing its members.

const std::string	toJson (int indent=-1, const char indent_char=' ') const
	Serialize this object to a JSON-formatted string. 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 and then package the results along with its recipe and unsealingInstructions into a SealedPackagedMessage. More...

const PackagedSealedMessage	seal (const std::vector< unsigned char > &message, const std::string &unsealingInstructions="") const
	Seal a plaintext message and then package the results along with its recipe and unsealingInstructions into a SealedPackagedMessage. More...

const PackagedSealedMessage	seal (const std::string &message, const std::string &unsealingInstructions={}) const
	Seal a plaintext message and then package the results along with its recipe and unsealingInstructions into a SealedPackagedMessage. More...

const PackagedSealedMessage	seal (const unsigned char *message, const size_t messageLength, const std::string &unsealingInstructions) const
	Seal a plaintext message and then package the results along with its recipe and unsealingInstructions into a SealedPackagedMessage. More...

const std::vector< unsigned char >	getSealingKeyBytes () const
	Get the copy of the raw public key bytes used by lib-sodium. More...

const std::string	getRecipeJson () const
	Get the JSON-formatted recipe string used to generate the public-private key pair. More...

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

Static Public Member Functions
static SealingKey	fromJson (const std::string &sealingKeyAsJson)
	Construct a sealingKeyBytes from a JSON string. More...

static const std::vector< unsigned char >	sealToCiphertextOnly (const SodiumBuffer &message, const std::vector< unsigned char > &sealingKeyBytes, const std::string &unsealingInstructions={})
	Avoid Using Seal a message using a raw libsodium public key. More...

static const std::vector< unsigned char >	sealToCiphertextOnly (const unsigned char *message, const size_t messageLength, const std::vector< unsigned char > &sealingKeyBytes, const std::string &unsealingInstructions={})
	Avoid Using Seal a message using a raw libsodium public key. More...

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

Public Attributes
const std::vector< unsigned char >	sealingKeyBytes
	The binary representation of the public key used for sealing.

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

Detailed Description

A sealingKeyBytes is used to seal messages, in combination with a UnsealingKey which can unseal them. The key pair of this sealingKeyBytes and the matching UnsealingKey are generated from a seed and a set of options in JSON format JSON Format for Recipes.

To derive a public key from a seed, first derive the corresponding UnsealingKey and then call UnsealingKey::getSealingKey.

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 prevent 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.

Note that sealing data does not prevent attackers who capture a sealed message (ciphertext) in transit with another validly-sealed message. A SigningKey can be used to sign messages that another party can verify that the message has not been forged or modified since the signer approved it.

Member Function Documentation

◆ fromJson()

SealingKey SealingKey::fromJson ( const std::string & sealingKeyAsJson )

static

Construct a sealingKeyBytes from a JSON string.

Parameters

sealingKeyAsJson The JSON encoding of a sealingKeyBytes

◆ fromSerializedBinaryForm()

SealingKey SealingKey::fromSerializedBinaryForm ( const SodiumBuffer & serializedBinaryForm )

static

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

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

◆ getRecipeJson()

const std::string SealingKey::getRecipeJson ( ) const

inline

Get the JSON-formatted recipe string used to generate the public-private key pair.

Returns: const std::string in JSON Format for Recipes

◆ getSealingKeyBytes()

const std::vector< unsigned char > SealingKey::getSealingKeyBytes ( ) const

Get the copy of the raw public key bytes used by lib-sodium.

Returns: const std::vector<unsigned char>

◆ seal() [1/4]

const PackagedSealedMessage SealingKey::seal	(	const SodiumBuffer &	message,
		const std::string &	unsealingInstructions
	)		const

Seal a plaintext message and then package the results along with its recipe and unsealingInstructions into a SealedPackagedMessage.

Parameters

message	The plaintext message to seal
unsealingInstructions	If this optional string is passed, the same string must be passed to unseal the message.

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

◆ seal() [2/4]

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

Seal a plaintext message and then package the results along with its recipe and unsealingInstructions into a SealedPackagedMessage.

Parameters

message	The plaintext message to seal
unsealingInstructions	If this optional string is passed, the same string must be passed to unseal the message.

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

◆ seal() [3/4]

const PackagedSealedMessage SealingKey::seal	(	const std::vector< unsigned char > &	message,
		const std::string &	unsealingInstructions = `""`
	)		const

Seal a plaintext message and then package the results along with its recipe and unsealingInstructions into a SealedPackagedMessage.

Parameters

message	The plaintext message to seal
unsealingInstructions	If this optional string is passed, the same string must be passed to unseal the message.

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

◆ seal() [4/4]

const PackagedSealedMessage SealingKey::seal	(	const unsigned char *	message,
		const size_t	messageLength,
		const std::string &	unsealingInstructions
	)		const

Seal a plaintext message and then package the results along with its recipe and unsealingInstructions into a SealedPackagedMessage.

Parameters

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

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

◆ sealToCiphertextOnly() [1/4]

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

Seal a plaintext message.

Parameters

message	The plaintext message to seal
unsealingInstructions	If this optional string is passed, the same string must be passed to unseal the message.

Returns: const std::vector<unsigned char>

◆ sealToCiphertextOnly() [2/4]

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

static

Avoid Using Seal a message using a raw libsodium public key.

Instead of using this static method, we recommend you use the seal method on an instance of a sealingKeyBytes object. This static method is used internally to libsodium's seal operation. We have exposed so that others can replicate the internals of this class if necessary, but recommend that only when there are reasons not to call the non-static seal operation on an instance of this class.

Parameters

message	The plaintext message to seal
sealingKeyBytes	The public key matching the private key used to unseal it.
unsealingInstructions	If this optional string is passed, the same string must be passed to unseal the message. RefPDI.

Returns: const std::vector<unsigned char> The sealed message (ciphertext)

◆ sealToCiphertextOnly() [3/4]

const std::vector< unsigned char > SealingKey::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. It can be used to pair a secret (sealed) message with public instructions about what should happen after the message is unsealed.

Returns: const std::vector<unsigned char>

◆ sealToCiphertextOnly() [4/4]

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

static

Avoid Using Seal a message using a raw libsodium public key.

Instead of using this static method, we recommend you use the seal method on an instance of a sealingKeyBytes object. This static method is used internally to libsodium's seal operation. We have exposed so that others can replicate the internals of this class if necessary, but recommend that only when there are reasons not to call the non-static seal operation on an instance of this class.

Parameters

message	The plaintext message to seal
messageLength	The length of the plaintext message to seal (in bytes)
sealingKeyBytes	The public key matching the private key used to unseal it.
unsealingInstructions	If this optional string is passed, the same string must be passed to unseal the message. RefPDI.

Returns: const std::vector<unsigned char> The sealed message (ciphertext)

◆ toJson()

const std::string SealingKey::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

◆ toSerializedBinaryForm()

const SodiumBuffer SealingKey::toSerializedBinaryForm ( ) const

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

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

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

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

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ fromJson()

◆ fromSerializedBinaryForm()

◆ getRecipeJson()

◆ getSealingKeyBytes()

◆ seal() [1/4]

◆ seal() [2/4]

◆ seal() [3/4]

◆ seal() [4/4]

◆ sealToCiphertextOnly() [1/4]

◆ sealToCiphertextOnly() [2/4]

◆ sealToCiphertextOnly() [3/4]

◆ sealToCiphertextOnly() [4/4]

◆ toJson()

◆ toSerializedBinaryForm()