Module encryptable 

This module defines traits for encrypting data. There are three categories here.

Some (legacy) encryptables are made up of many small individually encrypted items. For instance, a cipher is currently made up of many small EncStrings and some further json objects that themselves contain EncStrings. The use of this is generally discouraged for new designs. Still, this is generally the only trait that should be implemented outside of the crypto crate.

Encrypting data directly, a content type must be provided, since an encrypted byte array alone is not enough to tell the decryption code how to interpret the decrypted bytes. For this, there are two traits, PrimitiveEncryptable and PrimitiveEncryptableWithContentType. The former assumes that the implementation provides content format when encrypting, based on the type of struct that is being encrypted. The latter allows the caller to specify the content format at runtime, which is only allowed within the crypto crate.

PrimitiveEncryptable is implemented for crate::content_format::Bytes<C> types, where C is a type that implements the ConstContentFormat trait. This allows for compile-time type checking of the content format, and the risk of using the wrong content format is limited to converting untyped bytes into a Bytes<C>

Round-trip contract

The encrypt traits here and crate::Decryptable form a symmetric pair with a contract that callers rely on:

• Decryption MUST yield a value that contains no encrypted material — no wrapped keys and no residual EncStrings that are still bound to the key that was used to decrypt. Everything protected by that key must be fully decrypted.
• Encryption MUST produce output that is fully encrypted under the provided key. No encrypted items may be copied from the input. Plaintext data co-existing with encrypted data is allowed, and may be copied through.

Together these mean that decrypting with one key and re-encrypting with another round-trips: for any two valid keys K and K1, decrypt(encrypt(decrypt(x, K), K1), K1) = decrypt(x, K).

Traits

CompositeEncryptable

An encryption operation that takes the input value and encrypts the fields on it recursively. Implementations should generally consist of calling PrimitiveEncryptable::encrypt for all the fields of the type. Sometimes, it is necessary to call CompositeEncryptable::encrypt_composite, if the object is not a flat struct.

PrimitiveEncryptable

An encryption operation that takes the input value - a primitive such as String and encrypts it into the output value. The implementation decides the content format.

PrimitiveEncryptableWithContentType 🔒

An encryption operation that takes the input value - a primitive such as Vec<u8> - and encrypts it into the output value. The caller must specify the content format.