Cipherpack General User Level API

General User level Cipherpack API types and functionality, see Cipherpack Overview. More...

Namespaces
namespace	cipherpack::hash_util
	Hash utility functions to produce a hash file compatible to sha256sum as well as to produce the hash value itself for validation.

Classes
class	cipherpack::CipherpackListener
	Listener for events occurring while processing a cipherpack message via encryptThenSign() and checkSignThenDecrypt(). More...
class	cipherpack::Constants
struct	cipherpack::CryptoConfig
	CryptoConfig, contains crypto algorithms settings given at encryption wired via the Cipherpack Data Stream, hence received and used at decryption if matching keys are available. More...
class	cipherpack::environment
class	cipherpack::PackHeader
	Cipherpack header less encrypted keys or signatures as described in Cipherpack Data Stream. More...
class	cipherpack::WrappingDataSource
	This class represents an abstract data source object. More...

Macros
#define	JAVA_MAIN_PACKAGE   "org/cipherpack/"

Typedefs
typedef std::shared_ptr< CipherpackListener >	cipherpack::CipherpackListenerRef
template<typename T >
using	cipherpack::secure_vector = std::vector< T, Botan::secure_allocator< T > >

Functions
PackHeader	cipherpack::checkSignThenDecrypt (const std::vector< std::string > &sign_pub_keys, const std::string &dec_sec_key_fname, const jau::io::secure_string &passphrase, jau::io::ByteInStream &source, CipherpackListenerRef listener, const std::string_view &plaintext_hash_algo, const std::string destination_fname="")
	Verify signature then decrypt the source passing to the CipherpackListener if opt-in and also optionally store into destination file. More...
std::string_view	cipherpack::default_hash_algo () noexcept
	Name of default hash algo for the plaintext message, e.g. More...
PackHeader	cipherpack::encryptThenSign (const CryptoConfig &crypto_cfg, const std::vector< std::string > &enc_pub_keys, const std::string &sign_sec_key_fname, const jau::io::secure_string &passphrase, jau::io::ByteInStream &source, const std::string &target_path, const std::string &subject, const std::string &plaintext_version, const std::string &plaintext_version_parent, CipherpackListenerRef listener, const std::string_view &plaintext_hash_algo, const std::string destination_fname="")
	Encrypt then sign the source producing a cipherpack stream passed to the CipherpackListener if opt-in and also optionally store into destination_fname. More...
std::shared_ptr< Botan::Private_Key >	cipherpack::load_private_key (const std::string &privatekey_fname, const jau::io::secure_string &passphrase)
std::shared_ptr< Botan::Public_Key >	cipherpack::load_public_key (const std::string &pubkey_fname)
std::string	cipherpack::to_string (const PackHeader &ph) noexcept

Detailed Description

General User level Cipherpack API types and functionality, see Cipherpack Overview.

Cipherpack Overview

Cipherpack, a secure stream processor utilizing public-key signatures to authenticate the sender and public-key encryption of a symmetric-key for multiple receiver ensuring their privacy and high-performance message encryption.

Cipherpack securely streams messages through any media, via file using ByteInStream_File and via all libcurl network protocols using ByteInStream_URL are build-in and supported.
Note: libcurl must be enabled via -DUSE_LIBCURL=ON at build.

A user may use the media agnostic ByteInStream_Feed to produce the input stream by injecting data off-thread and a CipherpackListener to receive the processed output stream.

Cipherpack is implemented using C++17 and accessible via C++ and Java.

Cipherpack Implementation

Implementation Status

READY TO USE

Cipherpack Operations

The following public-key signature and encryption, as well as symmetric-key message encryption operations are performed:

• Writing a DER Header-1, containing the general message information and receiver count, see PackHeader details.
• Writing a DER Header for each recevr, containing the fingerprint, encrypted symmetric-key and encrypted symmetric-nonce.
• Writing a DER Header-2, containing the sender's signature over the whole header
• Writing the symmetrically encrypted message, using the symmetric-key for encryption + MAC via AEAD ChaCha20Poly1305.

Implementation performs all operation in-place without redundant copies, processing the stream.

Cipherpack Data Stream

The stream's header contains the sender's public-key fingerprint and its signature for authentication by the receiving parties.

Further, the stream contains triples per receiver, its public-key fingerprint, the encrypted symmetric-key and the encrypted symmetric-nonce for each receiver, allowing a secure messaging between multiple parties:

• Symmetric encryption of the plaintext message ensures high-performance processing.
• Symmetric stream-key is unique for each message

Implementation uses an Authenticated Encryption with Additional Data (AEAD) encryption+MAC cipher algo, i.e. cipherpack::constants::aead_cipher_algo.

The random nonce, unique for one message and used for the symmetric encryption is not a secret and doesn't have to be confidential. However, since we already encrypt the symmetric-key for each receiver, we transmit the nonce with it, encrypted.

The cipherpack stream will be produced as follows:

DER Header 1 {
    ASN1_Type::OctetString               stream_magic              // simple stream identifier to be matched
    ASN1_Type::OctetString               target_path               // optional target path for the plaintext message, user application specific.
    ASN1_Type::Integer                   plaintext_size            // size in bytes of plaintext message, zero if not determined at start of streaming
    ASN1_Type::Integer                   creation_timestamp_sec    // message creation timestamp, second component
    ASN1_Type::Integer                   creation_timestamp_nsec   // message creation timestamp, nanoseconds component
    ASN1_Type::OctetString               subject                   // optional subject of message, user application specific.
    ASN1_Type::OctetString               plaintext_version         // version of this plaintext message, user application specific.
    ASN1_Type::OctetString               plaintext_version_parent  // version of this plaintext message's preceding message, user application specific.
    ASN1_Type::OctetString               pk_type                   // public-key type. Default `RSA`.
    ASN1_Type::OctetString               pk_fingerprt_hash_algo    // public-key fingerprint hash. Default `SHA-256`.
    ASN1_Type::OctetString               pk_enc_padding_algo       // public-key encryption padding. Default `OAEP`.
    ASN1_Type::OctetString               pk_enc_hash_algo          // public-key encryption hash. Default `SHA-256`.
    ASN1_Type::OctetString               pk_sign_algo              // public-key signature algorithm. Default `EMSA1(SHA-256)`.
    ASN1_Type::ObjectId                  sym_enc_mac_oid           // symmetric-key encryption+MAC algorithm. Default `ChaCha20Poly1305`.
    ASN1_Type::OctetString               fingerprt_sender          // fingerprint of public sender key used for header signature
    ASN1_Type::Integer                   receiver_count,           // number of receiver triples { fingerprint, encrypted-symmetric-keys, encrypted-nonce }
}
DER Header recevr_1 {
    ASN1_Type::OctetString               fingerprt_recevr_1,       // fingerprint of receiver's public-key_1 used for encrypted_skey_recevr_1
    ASN1_Type::OctetString               encrypted_skey_recevr_1,  // encrypted symmetric-key with receiver's public-key_1
    ASN1_Type::OctetString               encrypted_nonce_recevr_1, // encrypted symmetric-encryption nonce with receiver's public-key_1
},
DER Header recevr_2 {
    ASN1_Type::OctetString               fingerprt_recevr_2,       // fingerprint of receiver's public-key_1 used for encrypted_skey_recevr_2
    ASN1_Type::OctetString               encrypted_skey_recevr_2,  // encrypted symmetric-key with receiver's public-key_2
    ASN1_Type::OctetString               encrypted_nonce_recevr_2, // encrypted symmetric-encryption nonce with receiver's public-key_2
} ...
DER Header 2 {
    ASN1_Type::OctetString               sign_sender               // sender's signature over whole header, matching fingerprt_sender
},
uint8_t encrypted_data[ciphertext_size]                            // the encrypted message, `ciphertext_size` bytes resulting to `plaintext_size` plaintext message

See also

encryptThenSign()

checkSignThenDecrypt()

Macro Definition Documentation

JAVA_MAIN_PACKAGE

#define JAVA_MAIN_PACKAGE   "org/cipherpack/"

Definition at line 141 of file cipherpack.hpp.

Typedef Documentation

secure_vector

template<typename T >

using cipherpack::secure_vector = typedef std::vector<T, Botan::secure_allocator<T> >

Definition at line 166 of file cipherpack.hpp.

CipherpackListenerRef

typedef std::shared_ptr<CipherpackListener> cipherpack::CipherpackListenerRef

Definition at line 559 of file cipherpack.hpp.

Function Documentation

to_string()

std::string cipherpack::to_string ( const PackHeader &  ph )

inlinenoexcept

Definition at line 431 of file cipherpack.hpp.

load_public_key()

std::shared_ptr< Botan::Public_Key > cipherpack::load_public_key

(

const std::string &

pubkey_fname

)

Definition at line 181 of file crypto0.cpp.

Here is the caller graph for this function:

load_private_key()

std::shared_ptr< Botan::Private_Key > cipherpack::load_private_key	(	const std::string &	privatekey_fname,
		const jau::io::secure_string &	passphrase
	)

Definition at line 310 of file crypto0.cpp.

Here is the caller graph for this function:

default_hash_algo()

std::string_view cipherpack::default_hash_algo ( )

noexcept

Name of default hash algo for the plaintext message, e.g.

for encryptThenSign() and checkSignThenDecrypt().

Value is BLAKE2b(512).

Note:

• SHA-256 performs 64 rounds over 512 bits (blocks size) at a time.
  • Often better optimized and hardware implemented.
• SHA-512 performs 80 rounds over 1024 bits (blocks size) at a time.
  • Requires double storage size than SHA-256, i.e. 512/256 bits.
  • 25% more rounds, i.e. calculations than SHA-256
  • Operating on 64-bit words instead of SHA-256's 32-bit words
  • Theoretically shall outperform SHA-256 by 2 / 1.25 = 1.6 on 64-bit architectures, however, SHA-256 is often better optimized and hardware implemented.
• BLAKE2b(512) usually beats both, SHA-256 and SHA-512 on 64-bit machines.
  • It even matches their performance if using hardware accelerated implementations.

Examples

commandline.cpp, and test_01_cipherpack.cpp.

Definition at line 110 of file crypto0.cpp.

Here is the caller graph for this function:

encryptThenSign()

PackHeader cipherpack::encryptThenSign	(	const CryptoConfig &	crypto_cfg,
		const std::vector< std::string > &	enc_pub_keys,
		const std::string &	sign_sec_key_fname,
		const jau::io::secure_string &	passphrase,
		jau::io::ByteInStream &	source,
		const std::string &	target_path,
		const std::string &	subject,
		const std::string &	plaintext_version,
		const std::string &	plaintext_version_parent,
		CipherpackListenerRef	listener,
		const std::string_view &	plaintext_hash_algo,
		const std::string	destination_fname = ""
	)

Encrypt then sign the source producing a cipherpack stream passed to the CipherpackListener if opt-in and also optionally store into destination_fname.

Parameters

crypto_cfg	Used CryptoConfig, consider using CryptoConfig::getDefault()
enc_pub_keys	Public keys of the receiver, used to encrypt the symmetric-key for multiple parties.
sign_sec_key_fname	Private key of the sender, used to sign the DER-Header-1 incl encrypted symmetric-key for authenticity.
passphrase	Passphrase for sign_sec_key_fname, may be an empty secure_string for no passphrase.
source	The source jau::io::ByteInStream of the plaintext message.
target_path	Optional target path for the message, user application specific.
subject	Optional subject of message, user application specific.
plaintext_version	Version of this plaintext message, user semantic
plaintext_version_parent	Version of this plaintext message's preceding message, user application specific
listener	CipherpackListener listener used for notifications and optionally to send the ciphertext destination bytes via CipherpackListener::contentProcessed()
plaintext_hash_algo	Optional hash algorithm for the plaintext message, produced for convenience and not wired. See default_hash_algo(). Pass an empty string to disable.
destination_fname	Optional filename of the ciphertext destination file, not used if empty (default). If not empty and file already exists, file will be overwritten.

Returns

PackHeader, where true == PackHeader::isValid() if successful, otherwise not.

See also

Cipherpack Overview

Cipherpack Data Stream

checkSignThenDecrypt()

CipherpackListener

jau::io::ByteInStream

Examples

commandline.cpp, and test_01_cipherpack.cpp.

Definition at line 518 of file crypto1.cpp.

Here is the caller graph for this function:

checkSignThenDecrypt()

PackHeader cipherpack::checkSignThenDecrypt	(	const std::vector< std::string > &	sign_pub_keys,
		const std::string &	dec_sec_key_fname,
		const jau::io::secure_string &	passphrase,
		jau::io::ByteInStream &	source,
		CipherpackListenerRef	listener,
		const std::string_view &	plaintext_hash_algo,
		const std::string	destination_fname = ""
	)

Verify signature then decrypt the source passing to the CipherpackListener if opt-in and also optionally store into destination file.

Parameters

sign_pub_keys	Authorized sender public-keys to verify the sender's signature and hence the authenticity of the message incl. encrypted symmetric-key and ciphertext message.
dec_sec_key_fname	Private key of the receiver, used to decrypt the symmetric-key. It shall match one of the keys used to encrypt.
passphrase	The passphrase for dec_sec_key_fname, may be an empty secure_string for no passphrase.
source	The source jau::io::ByteInStream of the cipherpack containing the encrypted message.
listener	The CipherpackListener listener used for notifications and optionally to send the plaintext destination bytes via CipherpackListener::contentProcessed()
plaintext_hash_algo	Optional hash algorithm for the plaintext message, produced for convenience and not wired. See default_hash_algo(). Pass an empty string to disable.
destination_fname	Optional filename of the plaintext destination file, not used if empty (default). If not empty and file already exists, file will be overwritten.

Returns

PackHeader, where true == PackHeader::isValid() if successful, otherwise not.

See also

Cipherpack Overview

Cipherpack Data Stream

encryptThenSign()

CipherpackListener

jau::io::ByteInStream

Examples

commandline.cpp, and test_01_cipherpack.cpp.

Definition at line 1134 of file crypto1.cpp.

Here is the caller graph for this function: