84 lines
4.3 KiB
Plaintext
84 lines
4.3 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: FF3-1 Tweak Usage Documentation
|
|
description: |-
|
|
Details and best practices for FF3-1 transform usage.
|
|
---
|
|
# 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].
|
|
|
|
## Further Resources:
|
|
|
|
* 1: https://eprint.iacr.org/2020/1311.pdf
|
|
* 2: https://csrc.nist.gov/news/2017/recent-cryptanalysis-of-ff3
|
|
* 3: https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-38g.pdf
|
|
* 4: https://img.chainnews.com/paper/568b1f587c93f63832f083dd449107c2.pdf
|