tcream.5 - cream - Stream encryption utility
(HTM) git clone git://git.z3bra.org/cream.git
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
---
tcream.5 (3620B)
---
1 .Dd 2022-09-15
2 .Dt CREAM 5
3 .Os POSIX.1-2017
4 .Sh NAME
5 .Nm cream
6 .Nd Encrypted stream data format
7 .Sh DESCRIPTION
8 .Nm
9 data is the concatenation of a 40 bytes header and a flow of encrypted data.
10 .Pp
11 Data is encrypted with a key derivated from a
12 .Em password
13 and a
14 .Em salt .
15
16 .Sh HEADER FORMAT
17 For convenience, encryption parameters are included at the beginning of
18 the stream.
19 The header is 40 bytes long, and has the following format:
20 .TS
21 |c| c| c|
22 |r| l| l|.
23 _
24 BYTES DESCRIPTION VALUE
25 _
26 6 magic string CREAM\e1 6*8-bit BE character
27 2 header version 16-bit BE unsigned integer
28 4 xchacha20 block size 32-bit BE unsigned integer
29 4 argon2id memory 32-bit BE unsigned integer
30 4 argon2id time cost 32-bit BE unsigned integer
31 4 argon2id parallelism 32-bit BE unsigned integer
32 16 salt 16*8-bit BE unsigned integer
33 _
34 .TE
35
36 .Sh CRYPTOGRAPHY INTERNALS
37 .Ss Encryption
38 XChaCha20-Poly1305 is used to encrypt the data. As a symetrical cipher,
39 the key used to encrypt the data must be used to decrypt it.
40 .Pp
41 To encrypt, or decrypt a continuous stream, the input data is split in
42 chunks, and a new key is generated to encrypt it. The smaller chunks are,
43 the more keys are computed for a given amount of data.
44 .Pp
45 To lower computation cycles, or accomodate memory-constrained system,
46 the buffer size can be changed. However, this buffer size must be the
47 same for both encryption and decryption, otherwise resulting in a failure
48 to decrypt the data.
49 .Ss Key derivation
50 Argon2id is used to derivate the key from a password and a salt.
51 .Pp
52 The master password must be known to both parties, while the salt is sent
53 as part of the header. This means that the receiver must only know the
54 password to decrypt the data.
55 .Pp
56 Computing an Argon2id key takes multiple factor into accounts:
57 .Pp
58 .Bl -tag -compact -width XXXXXXXXXXXXXXX
59 .It Em Memory (m)
60 Defines the memory usage, given in kibibytes.
61 .It Em Time (t)
62 Defines the amount of computation realized and therefore the execution
63 time, given in number of iterations
64 .It Em Parallelism (p)
65 Defines the number of parallel threads.
66 .El
67 .Pp
68 These parameters will affect the speed at which the key is computed,
69 but will also change the key itself.
70 .Pp
71 For use as a symmetric key, you will want to use the exact same parameters
72 for both encryption and decryption, otherwise decryption of the stream
73 will be impossible.
74 .Pp
75 The recommended values are m=2Gib, t=1, p=4. For memory constrained
76 environment, use m=64Mib, t=3, p=4. See rfc 9106 for a procedure to
77 pick good parameters.
78
79 .Sh EXAMPLES
80 The following
81 .Xr magic 5
82 file pattern can be used to parse
83 .Nm
84 headers using the
85 .Xr file 1
86 command:
87 .Bd -literal
88 # cream.magic
89 0 string CREAM\e1 CREAM encrypted data,
90 >6 beshort x version %d,
91 >8 belong x xchachapoly1305
92 >8 belong x bs=%d,
93 >12 belong x argon2id
94 >12 belong x m=%d
95 >16 belong x t=%d
96 >20 belong x p=%d
97 .Ed
98 .Pp
99 .Bd -literal
100 % file -m cream.magic cipher.cream
101 cipher.cream: CREAM encrypted data, version 16,
102 xchachapoly1305 bs=4096, argon2id m=65536 t=3 p=4
103 .Ed
104
105 .Sh SEE ALSO
106 .Xr cream 1 ,
107 .Xr file 1 ,
108 .Xr magic 5
109
110 .Sh STANDARDS
111 .Rs
112 .%A D. J. Bernstein
113 .%R https://cr.yp.to/chacha.html
114 .%T The ChaCha family of stream ciphers
115 .%D January 2008
116 .Re
117 .Pp
118 .Rs
119 .%A Y. Nir
120 .%A A. Langley
121 .%D June 2018
122 .%R RFC 8439
123 .%T ChaCha20 and Poly1305 for IETF Protocols
124 .Re
125 .Pp
126 .Rs
127 .%A A. Biryukov
128 .%A D. Dinu
129 .%A D. Khovratovich
130 .%A S. Josefsson
131 .%D September 2021
132 .%R RFC 9106
133 .%T Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications
134 .Re
135 .Sh AUTHORS
136 .An Willy Goiffon Aq Mt dev@z3bra.org