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.

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