Welcome to little lamb

Code » limb » release » tree

[release] / src / doc / shldata.5.md 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
% limb manual
% shldata(5)
% limb 0.1.0
% 2023-07-24

# NAME

shielded data - encryption/decryption protocol

# DESCRIPTION

The "shielded data" protocol is a way to protect data using a user-provided
password. Using specified parameters (cryptographic hash algorithm, iteration
numbers, etc) a secret key is derived from the password and used to encrypt data
via the ChaCha20-Poly1305 algorithm.

Similarly, provided with the original password, the same key derivation function
is applied - using parameters taken from the input data - to obtain the secret
key, used via ChaCha20-Poly1305 to both decrypt & authenticate the data, adding
the derivation parameters to the authentication process.

The actual encryption/decryption is performed using the ChaCha20-Poly1305
algorithm, as described in [RFC 8439][rfc8439].

[rfc8439]: https://datatracker.ietf.org/doc/html/rfc8439

The derivation parameters as well as the encrypted data and the message
authentication code are encoded in [patrim](5) format :

- The file header should use a PATRIM compatible magic constant, with bit 8 of
  said number being set to 1 to indicate it contains shielded data.

- For every ID in the file, bit 7 is a flag with special meaning : If set, it
  indicates that the associated data are part of the shielded data protocol.
  Else, the ID is a custom ID defined/used per the application itself.

- When shielded data are added into a file, first all the IDs referring to key
  derivation must be included, then the `ID_DATA` containing the encrypted data
  followed by the `ID_MAC` containing the authentication code.

- It is possible to have more than one such shielded data in a single file,
  though each will have its own settings & require its own password.

- Application-custom IDs can be used before, after, or in-between such shielded
  data sections, but must not be mixed within groups of shielded data IDs.

Refer to [shldata.h](0) for an interface to the encryption/decryption of
shielded data.

Helpers functions for general purpose PATRIM encoding are also available via
[patrim.h](0).