Functions for symmetrical or asymmetrical encryption using NaCL. More...

Functions
unsigned char *	pcp_box_encrypt (pcp_key_t secret, pcp_pubkey_t pub, unsigned char message, size_t messagesize, size_t csize)
	Asymmetrically encrypt a message.

unsigned char *	pcp_box_decrypt (pcp_key_t secret, pcp_pubkey_t pub, unsigned char cipher, size_t ciphersize, size_t dsize)
	Asymmetrically decrypt a message.

size_t	pcp_encrypt_stream (Pcpstream in, Pcpstream out, pcp_key_t s, pcp_pubkey_t p, int signcrypt)
	Asymmetrically encrypt a file or a buffer stream.

size_t	pcp_encrypt_stream_sym (Pcpstream in, Pcpstream out, unsigned char symkey, int havehead, pcp_rec_t recsign)
	Symmetrically encrypt a file or a buffer stream.

size_t	pcp_decrypt_stream (Pcpstream in, Pcpstream out, pcp_key_t s, unsigned char symkey, int verify)
	Asymmetrically decrypt a file or a buffer stream.

size_t	pcp_decrypt_stream_sym (Pcpstream in, Pcpstream out, unsigned char symkey, pcp_rec_t recverify)
	Symmetrically decrypt a file or a buffer stream.

size_t	pcp_sodium_mac (unsigned char *cipher, unsigned char cleartext, size_t clearsize, unsigned char nonce, unsigned char key)
	Symmetrically encrypt a message.

int	pcp_sodium_verify_mac (unsigned char *cleartext, unsigned char message, size_t messagesize, unsigned char nonce, unsigned char key)
	Decrypt a symmetrically encrypted message.

Detailed Description

Functions for symmetrical or asymmetrical encryption using NaCL.

Introduction

Encryption is done 32k blockwise using an ephemeral key.

If using asymmetrical encryption the ephemeral key is encrypted asymmetrically using Curve25519 for all recipients and added to the output.

If sign+crypt is requested, a hash of the clear content plus the recipient list will be made and signed. That signature will be encrypted using the ephemeral key as well and appended to the output.

For each encryption cycle (per block) a unique nonce will be used.

Encrypted Output Format

Encrypted output will always written as binary files. No armoring supported yet. The encryption process works as this:

generate a random symetric 32 byte key B<S>
encrypt it asymetrically for each recipient using a unique nonce (B<R>)
encrypt the input file 32k blockwise using the symetric key

Symmetric encryption works the very same with the recipient stuff left out.

Formal format description, asymmetric encrypted files:

     +---------------------------------------------------------+
     | Field         Size      Description                     |
     +-------------+--------+----------------------------------+
     | Type        |      1 | Filetype, 5=ASYM, 23=SYM         |
     +-------------|--------|----------------------------------+
     | Len R       |      4 | Number of recipients         (*) |
     +-------------|--------|----------------------------------+
     | Recipients  |   R*72 | C(recipient)|C(recipient)... (*) |
     +-------------|--------|----------------------------------+
     | Encrypted   |      ~ | The actual encrypted data        |
     +-------------|--------|----------------------------------+

The following will be Left out when doing symetric encryption.

Recipient field format:

    +---------------------------------------------------------+
    | Field         Size      Description                     |
    +-------------+--------+----------------------------------+
    | Nonce       |     24 | Random Nonce, one per R          |
    +-------------|--------|----------------------------------+
    | Cipher      |     48 | S encrypted with PK or R         |
    +-------------|--------|----------------------------------+

R is calculated using public key encryption using the senders secret key, the recipients public key and a random nonce.

Pseudocode:

R = foreach P: N | crypto_box(S, N, P, SK)
L = len(R)
T = 5
write (T | L | R)
foreach I: write (N | crypto_secret_box(I, N, S))

where P is the public key of a recipient, SK is the senders secret key, R is the recipient list, L is the number of recipients, T is the filetype header, I is a block of input with a size of 32k, N is a nonce (new per block) and S the symmetric key.

Function Documentation

unsigned char* pcp_box_decrypt	(	pcp_key_t *	secret,
		pcp_pubkey_t *	pub,
		unsigned char *	cipher,
		size_t	ciphersize,
		size_t *	dsize
	)

Asymmetrically decrypt a message.

This function is used internally and normally a user doesn't need to use it. However, from time to time there maybe the requirement to work with raw NaCL crypto_box() output. This function adds the neccessary padding and it uses PCP key structures.

Parameters

[in]	secret	The secret key structure from the sender.
[in]	pub	The public key structure from the recipient.
[in]	cipher	The encrypted message.
[in]	ciphersize	The size in bytes of the encrypted message.
[out]	dsize	A pointer which will be set to the size of the decrypted result if successful.

Returns: Returns an allocated unsigned char array of the size csize which contains the encrypted result. In case of an error, it returns NULL sets csize to 0. Use fatals_ifany() to check for errors.

unsigned char* pcp_box_encrypt	(	pcp_key_t *	secret,
		pcp_pubkey_t *	pub,
		unsigned char *	message,
		size_t	messagesize,
		size_t *	csize
	)

Asymmetrically encrypt a message.

This function is used internally and normally a user doesn't need to use it. However, from time to time there maybe the requirement to work with raw NaCL crypto_box() output. This function adds the neccessary padding and it uses PCP key structures.

Parameters

[in]	secret	The secret key structure from the sender.
[in]	pub	The public key structure from the recipient.
[in]	message	The clear unencrypted message.
[in]	messagesize	The size in bytes of the message.
[out]	csize	A pointer which will be set to the size of the encrypted result if successful.

Returns: Returns an allocated unsigned char array of the size csize which contains the encrypted result. In case of an error, it returns NULL sets csize to 0. Use fatals_ifany() to check for errors.

size_t pcp_decrypt_stream	(	Pcpstream *	in,
		Pcpstream *	out,
		pcp_key_t *	s,
		unsigned char *	symkey,
		int	verify
	)

Asymmetrically decrypt a file or a buffer stream.

This function decrypts a stream 32k+16-blockwise for a number of recipients.

Calls pcp_decrypt_stream_sym() after assembling the encrypted recipient list.

FIXME: should return the pcp_rec_t structure upon successfull verification somehow.

Parameters

[in]	in	Stream to read the data to decrypt from.
[out]	out	Stream to write decrypted result to.
[in]	s	Secret key structure of the recipient.
[in]	symkey	Ephemeral key for symmetric decryption. Set to NULL if you call this function directly.
	verify	Flag to indicate sign+crypt. If 1 it tries to verify a signature, otherwise not.

Returns: Returns the size of the output written to the output stream or 0 in case of errors.

size_t pcp_decrypt_stream_sym	(	Pcpstream *	in,
		Pcpstream *	out,
		unsigned char *	symkey,
		pcp_rec_t *	recverify
	)

Symmetrically decrypt a file or a buffer stream.

This function decrypts a stream 32k+16-blockwise using a given ephemeral key. Usually compute this key using the pcp_scrypt() function. If not called directly, the key have been extracted from the recipient list.

Uses crypto_secret_box_open() for each 32k+16-block with a random nonce for each.

Parameters

[in]	in	Stream to read the data to decrypt from.
[out]	out	Stream to write decrypted result to.
[in]	symkey	Ephemeral key to use for decryption.
	recverify	Flag to indicate sign+crypt. If 1 it tries to verify a signature, otherwise not.

Returns: Returns the size of the output written to the output stream or 0 in case of errors.

size_t pcp_encrypt_stream	(	Pcpstream *	in,
		Pcpstream *	out,
		pcp_key_t *	s,
		pcp_pubkey_t *	p,
		int	signcrypt
	)

Asymmetrically encrypt a file or a buffer stream.

This function encrypts a stream 32k-blockwise for a number of recipients.

Calls pcp_encrypt_stream_sym() after assembling the encrypted recipient list.

Parameters

[in]	in	Stream to read the data to encrypt from.
[out]	out	Stream to write encrypted result to.
[in]	s	Secret key structure of the sender.
[in]	p	Public key hash containing a list of the recipients.
	signcrypt	Flag to indicate sign+crypt. If 1 it adds a signature, otherwise not.

Returns: Returns the size of the output written to the output stream or 0 in case of errors.

size_t pcp_encrypt_stream_sym	(	Pcpstream *	in,
		Pcpstream *	out,
		unsigned char *	symkey,
		int	havehead,
		pcp_rec_t *	recsign
	)

Symmetrically encrypt a file or a buffer stream.

This function encrypts a stream 32k-blockwise using a given ephemeral key. Usually compute this key using the pcp_scrypt() function.

Uses crypto_secret_box() for each 32k-block with a random nonce for each.

Parameters

[in]	in	Stream to read the data to encrypt from.
[out]	out	Stream to write encrypted result to.
[in]	symkey	Ephemeral key to use for encryption.
[in]	havehead	Flag to indicate if the file header has already been written. Set to 0 if you call this function directly in order to do symmetrical encryption.
	recsign	Recipient list, set this to NULL if you call this function directly.

Returns: Returns the size of the output written to the output stream or 0 in case of errors.

size_t pcp_sodium_mac	(	unsigned char **	cipher,
		unsigned char *	cleartext,
		size_t	clearsize,
		unsigned char *	nonce,
		unsigned char *	key
	)

Symmetrically encrypt a message.

This function encrypts a message symmetrically using crypto_secretbox() using the given Curve25519 raw secret key and the nonce.

It allocates apropriate memory for the result, which will be stored in cipher.

Parameters

[out]	cipher	Encrypted result.
[in]	cleartext	Clear message.
[in]	clearsize	Size of message.
[in]	nonce	A random nonce (24 Bytes).
[in]	key	A Curve25519 key (32 Bytes).

Returns: Returns the size of cipher.

int pcp_sodium_verify_mac	(	unsigned char **	cleartext,
		unsigned char *	message,
		size_t	messagesize,
		unsigned char *	nonce,
		unsigned char *	key
	)

Decrypt a symmetrically encrypted message.

This function decrypts a symmetrically encrypted message using crypto_secretbox_open() using the given Curve25519 raw secret key and the nonce.

It allocates apropriate memory for the result, which will be stored in cleartext.

Parameters

[out]	cleartext	The decrypted result.
[in]	message	The encrypted message.
[in]	messagesize	Size of message.
[in]	nonce	A random nonce (24 Bytes).
[in]	key	A Curve25519 key (32 Bytes).

Returns: Returns 0 in case of success of -1 in case of an error. Check fatals_if_any().