A new platform for documentation and tutorials is launching soon.
We are migrating Vault documentation into HashiCorp Developer, our new developer experience.
»FF3-1 Tweak Usage Documentation
»Introduction
The Vault Transform Secrets Engine uses the FF3-1 algorithm for FPE (format preserving encryption) transformations. The key benefit of format preserving encryption schemes is that it allows for the secure encryption of plaintexts over small domain spaces [1]. However, this comes with the introduction of a parameter called the tweak, which is supplied to the FF3-1 algorithm. Up until recently, the formal definitions of security in FPE schemes have assumed that an attacker only has access to one tweak when probing the codebook for a particular key. However, following the work of Bellare, this notion was changed to assume that an attacker could control multiple tweaks when generating a codebook and trying to create a nontrivial distinguisher for FF3-1.
This page will detail some best practices when using tweaks.
Note that this guidance only holds when the tweak source selected when using the Vault
FF3-1 transform is supplied or internal.
»FF3-1 Best Practices:
Vault recommends the following practices when utilizing tweaks with the FF3-1 transform.
- Encryption should be as restricted as possible via ACLs.
- Tweaks are not user controlled, but are randomly chosen and treated as sensitive (if not secret).
- Tweaks make use of the max length allowed for the bytestring, and have high entropy (as uniformly variable as possible over the max tweak domain space and differing with each encryption). Tweaks should utilize the full domain space.
- Care should be taken to ensure that the same tweak is not used to encrypt two of the same values that correspond to different underlying entities.
The following section aims to give some broad motivation for these recommendations. For details, please see the Further Resources section at the bottom of the page.
»FF3-1 Tweak Usage
FF3-1 is a tweakable encryption scheme that was created to solve the problem of encrypting on small domains. Tweaks were introduced to synthetically increase the domain space. With the introduction of tweaks, an attacker must now have the correct encryption of the plaintext and the correct tweak in order to backtrack via a codebook from an encryption to a plaintext.
However, this can be risky when the number of tweaks used in FF3-1 setups is too small or is chosen on a restricted domain, or when it is user-generated and access control on encrypting is too broad. In the former case, a codebook can still be easily created if the tweaks are known (since tweak values are not necessarily secret [3]). In the latter case, an attacker who gains access to encrypting data (ie, has chosen-plaintext strength) can manipulate the tweaks to essentially bypass that synthetic extension of the domain space.
Another observation to note about FF3-1 is that encrypting the same plaintext with the same key and tweak is deterministic, so two plaintexts that happen to coincide will lead to two ciphertexts that coincide. Thus, no matching plaintexts for different objects should be stored with the same tweaks. For example, if the ciphertexts corresponding to the last four digits of phone numbers are stored, then there may be plaintext collisions, and these collision values should not be encrypted with the same tweak [3, Appendix C].
As a third observation, FF3-1 splits tweaks in half and uses half a tweak in each round function. Therefore, ideally, randomly chosen tweaks should have high entropy within each half of the tweak. In the worst case scenario, creating many encryptions with tweaks with the same right or left half will lead to more biased encryptions (where the distinction between the corresponding encryptions rely solely on the randomness of the abelian summation operator). In practice, using randomly chosen tweaks will be enough -- however, it is important to avoid using an algorithm to generate tweaks that yields similarity between two halves of tweaks [4].
