Module tindercrypt::metadata

Tindercrypt Metadata

The process of data encryption has various metadata, such as salts, nonces, algorithms, etc. The purpose of this module to generate and handle them properly.

Currently, Tindercrypt understands the following types of metadata:

• Key derivation metadata: If a user chooses to encrypt their data with a passphrase, they need to use a key derivation algorithm in order to create a key with a specific size. For instance, PBKDF2 requires a salt, a hash function and a number of iterations. The available key derivation algorithms and their associated metadata are covered in KeyDerivationAlgorithm
• Encryption metadata: The encryption algorithms that Tindercrypt currently supports require a unique nonce and optionally supports associated data. The available algorithms and their metadata are covered in EncryptionAlgorithm.

While the user is free to choose their own salts and nonces, in most cases they should just use the ::generate() constructor of the respective metadata types.

Tindercrypt provides a container where the above metadata are stored, the Metadata struct. This struct holds all the encryption context and is provided to cryptors when encrypting/decrypting data. Also, this struct is serialized and prepended to the ciphertext, when encrypting the data. See the Serialization section for more info.

Serialization

Tindercrypt uses Protocol Buffers to handle the (de)serialization of the Metadata struct. There are three reasons why we chose them instead of a custom wire format:

• Security: An attacker with access to the ciphertext cannot create a header that will cause arbitrary code execution. Protocol Buffers are designed to thwart such attacks, and we use a Rust library (rust-protobuf) for the implementation details.
• Extensibility: If in the future we decide that we want to support an extra algorithm, we can do so easily, without breaking the parsing of existing serialized data.
• Interoperability: Anyone can deserialize the metadata header, as long as they use the protobuf definitions of this library. Protocol buffers offer bindings for most common languages.

For each metadata type defined in this module, there is a protobuf definition with almost the same fields. The generated Rust code is available in the proto::metadata module.

In a nutshell, the serialization process is the following:

• Convert a Metadata struct to a proto::metadata::Metadata message.
• Serialize the proto::metadata::Metadata message to a Vec<u8> buffer.
• Extend the buffer to also hold the ciphertext.
• Return the created buffer and the size of the serialized metadata. The latter can be used to know where the ciphertext section begins within the buffer.

The deserialization process is a bit more involved, as we must also check the integrity of the metadata:

• Deserialize the buffer header into a proto::metadata::Metadata message. Failure to do so means that the buffer does not contain such a header, or that the header is corrupted.
• Convert the proto::metadata::Metadata message into a Metadata struct. Failure to do so means that the buffer contains a structurally valid metadata header, but its fields contain invalid values.
• Return the created Metadata struct and the size of the serialized metadata.

Structs

EncryptionMetadata	The metadata that can be used for the encryption process.
KeyDerivationMetadata	The metadata that can be used for the key derivation process.
Metadata	The collection of all encryption-related metadata.

Enums

EncryptionAlgorithm	The encryption algorithm that will be used.
HashFunction	The hash functions that this library supports.
KeyDerivationAlgorithm	The key derivation algorithm that will be used.

Constants

PBKDF2_DEFAULT_HASH_FN	The default hash function for the PBKDF2 key derivation algorithm.
PBKDF2_DEFAULT_ITERATIONS	The default number of iterations for the PBKDF2 key derivation algorithm.
PBKDF2_SALT_SIZE	The size of the salt values for the PBKDF2 key derivation algorithm.
RING_NONCE_SIZE	The size of the nonces for the encryption algorithms provided by Ring.