open-vault/website/content/docs/secrets/transform/ff3-tweak-details.mdx

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