org.cipherpack.Cipherpack Class Reference

More...

Collaboration diagram for org.cipherpack.Cipherpack:

Classes
class	HashUtil
	Hash utility functions to produce a hash file compatible to sha256sum as well as to produce the hash value itself for validation. More...

Static Public Member Functions
static PackHeader	checkSignThenDecrypt (final List< String > sign_pub_keys, final String dec_sec_key_fname, final ByteBuffer passphrase, final ByteInStream source, final CipherpackListener listener, final String plaintext_hash_algo, final String destination_fname)
	Verify signature then decrypt the source passing to the CipherpackListener if opt-in and also optionally store into destination file. More...
static final String	default_hash_algo ()
	Name of default hash algo for the plaintext message, e.g. More...
static PackHeader	encryptThenSign (final CryptoConfig crypto_cfg, final List< String > enc_pub_keys, final String sign_sec_key_fname, final ByteBuffer passphrase, final ByteInStream source, final String target_path, final String subject, final String plaintext_version, final String plaintext_version_parent, final CipherpackListener listener, final String plaintext_hash_algo, final 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...

Static Public Attributes
static final int	buffer_size = 16384
	Intermediate copy buffer size of 16384 bytes, usually the 4 x 4096 bytes page-size. More...

Detailed Description

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()

Definition at line 126 of file Cipherpack.java.

Member Function Documentation

default_hash_algo()

static final String org.cipherpack.Cipherpack.default_hash_algo ( )

static

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.

Definition at line 150 of file Cipherpack.java.

Here is the caller graph for this function:

encryptThenSign()

static PackHeader org.cipherpack.Cipherpack.encryptThenSign ( final CryptoConfig  crypto_cfg, final List< String >  enc_pub_keys, final String  sign_sec_key_fname, final ByteBuffer  passphrase, final ByteInStream  source, final String  target_path, final String  subject, final String  plaintext_version, final String  plaintext_version_parent, final CipherpackListener  listener, final String  plaintext_hash_algo, final String  destination_fname  )

static

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 null or empty for no passphrase.
source	The source ByteInStream of the plaintext message.
target_path	Optional target path for the message, user application specific.
subject	Optional subject of message from sender, user application specific.
plaintext_version	Version of this plaintext message, user application specific.
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 Cipherpack#default_hash_algo(). Pass an empty string to disable.
destination_fname	Optional filename of the plaintext destination file, not used if null or 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

ByteInStream_Feed

ByteInStream_URL

ByteInStream

Definition at line 179 of file Cipherpack.java.

Here is the caller graph for this function:

checkSignThenDecrypt()

static PackHeader org.cipherpack.Cipherpack.checkSignThenDecrypt ( final List< String >  sign_pub_keys, final String  dec_sec_key_fname, final ByteBuffer  passphrase, final ByteInStream  source, final CipherpackListener  listener, final String  plaintext_hash_algo, final String  destination_fname  )

static

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 null or empty for no passphrase.
source	The source 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 Cipherpack#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

ByteInStream_Feed

ByteInStream_URL

ByteInStream

Definition at line 237 of file Cipherpack.java.

Here is the caller graph for this function:

Member Data Documentation

buffer_size

final int org.cipherpack.Cipherpack.buffer_size = 16384

static

Intermediate copy buffer size of 16384 bytes, usually the 4 x 4096 bytes page-size.

Definition at line 129 of file Cipherpack.java.

---

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

• java/org/cipherpack/Cipherpack.java