tDocument recent changes to the cream(5) format - cream - Stream encryption utility
(HTM) git clone git://git.z3bra.org/cream.git
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
---
(DIR) commit cb347b39542d4ddd60695660dc0b4338a0f35c4f
(DIR) parent f268d845b7b4f2cfb9d88cae51de02586bdbcc1e
(HTM) Author: Willy Goiffon <contact@z3bra.org>
Date: Tue, 18 Oct 2022 15:07:43 +0200
Document recent changes to the cream(5) format
Diffstat:
M README | 14 ++++++--------
M cream.1 | 25 +++++++++++++++----------
M cream.5 | 118 +++++++++++++++++++++++--------
3 files changed, 109 insertions(+), 48 deletions(-)
---
(DIR) diff --git a/README b/README
t@@ -11,6 +11,7 @@ Features
- No key files involved
- Handle arbitrary chunks of data
- Modern algorithms ([XChaCha20-Poly1305][0] + [Argon2id][1])
+- Decryption parameters discovery
Usage
-----
t@@ -27,17 +28,14 @@ Send an encrypted file over the network
Format
------
-
For convenience, encryption parameters are included at the beginning of
-the stream. The header is 48 bytes long, and can be parsed using the
-file(1) command:
+the stream. This header can be parsed using the file(1) command:
- % file -m cream.magic data.enc
- data.enc: CREAM encrypted data, version 1,
- xchachapoly1305: k=32 iv=16 bs=8192,
- argon2id: m=65536 t=2 p=1
+ % file -m cream.magic cipher.cream
+ cipher.cream: CREAM encrypted data, version 16,
+ xchachapoly1305 bs=4096, argon2id m=65536 t=3 p=4
-The complete format is detailed in cream(5) manual page.
+The header format and magic pattern are detailed in cream(5) manual page.
Installation
-----
(DIR) diff --git a/cream.1 b/cream.1
t@@ -36,14 +36,14 @@ or
.It Fl b Ar size
Change internal buffer length to
.Ar size .
-Default: 8 Kib.
-.It Fl j Ar thread
-Number of thread(s) to use when computing the key. Default: 2.
-.It Fl t Ar time
-Number of iterations to use when computing the key. This effectively
-increases the time cost of computing the key. Default: 2.
+Default: 4096.
.It Fl m Ar memory
-Memory to use when computing the key. Default: 64 Mib.
+Memory to use for computing the key. Default: 64 Mib.
+.It Fl t Ar time
+Number of iterations to perform. This effectively increases the time
+taken to compute the key. Default: 3.
+.It Fl j Ar thread
+Number of parallel threads used. Default: 4.
.It Fl f Ar file
Read/write encrypted data from/to
.Ar file ,
t@@ -58,13 +58,18 @@ for details about the salt.
Print a quick usage text.
.El
.Sh CRYPTOGRAPHIC CONSIDERATIONS
-Most cryptographic parameters can be changed from the command line.
-These values can increase or decrease the time it takes to compute the
-key, or the memory used when dealing with long streams.
+Cryptographic parameters can be changed from the command line.
+These values will directly affect the time it takes to compute the key,
+by consuming more resources.
.Pp
However, changing any of these values will change the produced key,
or the stream. The same values must be used in order to successfully
decrypt a stream.
+.Pp
+For convenience on the decryption side, the specific parameters used
+during encryption are prepended to the data stream (see
+.Xr cream 5
+for details on the format)
.Sh EXAMPLES
Encrypt a file, then decrypt it (you will be prompted for a password
for each command).
(DIR) diff --git a/cream.5 b/cream.5
t@@ -6,73 +6,131 @@
.Nd Encrypted stream data format
.Sh DESCRIPTION
.Nm
-data is the concatenation of a 48 bytes header and a flow of encrypted data.
+data is the concatenation of a 40 bytes header and a flow of encrypted data.
.Pp
Data is encrypted with a key derivated from a
.Em password
and a
.Em salt .
+
.Sh HEADER FORMAT
-As a convenience for decrypting the stream, the parameters used for
-encryption are specified in a 48 bytes header.
-.Pp
-Header has the following format (all values in network byte order):
+For convenience, encryption parameters are included at the beginning of
+the stream.
+The header is 40 bytes long, and has the following format:
.TS
|c| c| c|
|r| l| l|.
_
BYTES DESCRIPTION VALUE
_
-6 6*8-bit BE unsigned char magic string CREAM\e1
-2 16-bit BE unsigned integer header version
-4 32-bit BE unsigned integer xchacha20 key size
-4 32-bit BE unsigned integer xchacha20 iv size
-4 32-bit BE unsigned integer xchacha20 block size
-4 32-bit BE unsigned integer argon2id time cost
-4 32-bit BE unsigned integer argon2id memory
-4 32-bit BE unsigned integer argon2id threads
-16 16*8-bit BE unsigned integer key derivation salt
+6 magic string CREAM\e1 6*8-bit BE character
+2 header version 16-bit BE unsigned integer
+4 xchacha20 block size 32-bit BE unsigned integer
+4 argon2id memory 32-bit BE unsigned integer
+4 argon2id time cost 32-bit BE unsigned integer
+4 argon2id parallelism 32-bit BE unsigned integer
+16 salt 16*8-bit BE unsigned integer
_
.TE
+
.Sh CRYPTOGRAPHY INTERNALS
.Ss Encryption
-XChaCha20-Poly1305 is used to encrypt the data. It is a symetrical cipher,
-so key used to encrypt the data must be used to decrypt it.
+XChaCha20-Poly1305 is used to encrypt the data. As a symetrical cipher,
+the key used to encrypt the data must be used to decrypt it.
.Pp
-In order to encrypt, or decrypt a continuous stream, the input data is
-split in chunks, and a new key is generated to encrypt it. The smaller
-chunks are, the more keys are computed for a given amount of data.
+To encrypt, or decrypt a continuous stream, the input data is split in
+chunks, and a new key is generated to encrypt it. The smaller chunks are,
+the more keys are computed for a given amount of data.
.Pp
To lower computation cycles, or accomodate memory-constrained system,
the buffer size can be changed. However, this buffer size must be the
same for both encryption and decryption, otherwise resulting in a failure
to decrypt the data.
.Ss Key derivation
-Argon2id is used to derivate the key from a password + salt combo.
+Argon2id is used to derivate the key from a password and a salt.
.Pp
-The master password must be known to both parties, and the salt is sent
-as the first 16 bytes of the stream. This means that the receiver must
-only know the password to decrypt the data.
+The master password must be known to both parties, while the salt is sent
+as part of the header. This means that the receiver must only know the
+password to decrypt the data.
.Pp
Computing an Argon2id key takes multiple factor into accounts:
.Pp
-.Bl -tag -compact -width XXXXXXXXXXX
-.It Em Time
-Defines the amount of computation realized and therefore the execution time, given in number of iterations
-.It Em Memory
+.Bl -tag -compact -width XXXXXXXXXXXXXXX
+.It Em Memory (m)
Defines the memory usage, given in kibibytes.
-.It Em Parallelism
+.It Em Time (t)
+Defines the amount of computation realized and therefore the execution
+time, given in number of iterations
+.It Em Parallelism (p)
Defines the number of parallel threads.
.El
.Pp
-Changing these parameters will affect the speed at which the key will
-be computed, but will also change the key itself.
+These parameters will affect the speed at which the key is computed,
+but will also change the key itself.
.Pp
For use as a symmetric key, you will want to use the exact same parameters
for both encryption and decryption, otherwise decryption of the stream
will be impossible.
+.Pp
+The recommended values are m=2Gib, t=1, p=4. For memory constrained
+environment, use m=64Mib, t=3, p=4. See rfc 9106 for a procedure to
+pick good parameters.
+
+.Sh EXAMPLES
+The following
+.Xr magic 5
+file pattern can be used to parse
+.Nm
+headers using the
+.Xr file 1
+command:
+.Bd -literal
+# cream.magic
+0 string CREAM\e1 CREAM encrypted data,
+>6 beshort x version %d,
+>8 belong x xchachapoly1305
+>8 belong x bs=%d,
+>12 belong x argon2id
+>12 belong x m=%d
+>16 belong x t=%d
+>20 belong x p=%d
+.Ed
+.Pp
+.Bd -literal
+% file -m cream.magic cipher.cream
+cipher.cream: CREAM encrypted data, version 16,
+ xchachapoly1305 bs=4096, argon2id m=65536 t=3 p=4
+.Ed
+
.Sh SEE ALSO
.Xr cream 1 ,
+.Xr file 1 ,
.Xr magic 5
+
+.Sh STANDARDS
+.Rs
+.%A D. J. Bernstein
+.%R https://cr.yp.to/chacha.html
+.%T The ChaCha family of stream ciphers
+.%D January 2008
+.Re
+.Pp
+.Rs
+.%A Y. Nir
+.%A A. Langley
+.%D June 2018
+.%R RFC 8439
+.%T ChaCha20 and Poly1305 for IETF Protocols
+.Re
+.Pp
+.Rs
+.%A A. Biryukov
+.%A D. Dinu
+.%A D. Khovratovich
+.%A S. Josefsson
+.%D September 2021
+.%R RFC 9106
+.%T Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications
+.Re
.Sh AUTHORS
.An Willy Goiffon Aq Mt dev@z3bra.org