Connexion / Inscription Account

What is Policy-Based Decryption?

Policy-based Decryption (PBD) is a collection of technologies that enable automated unlocking of encrypted volumes of hard drives on physical and virtual machines using a variety of unlocking methods. When the unlocking method uses a special network server, we call it Network-Bound Disk Encryption (NBDE).

As you can see in many recent releases of Red Hat Enterprise Linux (RHEL), Red Hat is committed to bringing improvements to PBD and NBDE. This article attempts to introduce some of them.

Tang keys rotation

NBDE requires a special network server. In RHEL, this server is called Tang and setting up NBDE involves setting up Tang. Tang generates keys to use for data encryption and decryption. Administrators should rotate these keys periodically and also update the clients to use the new keys, to avoid data loss.

Rotating Tang keys involves generating new keys for the server and excluding the current ones from the server advertisement so that clients no longer use the former keys, but the new ones, the ones advertised. Rotated keys still exist from the perspective of the server, and clients that were bound to them still work. It is advisable to update client bindings to use the new keys, and once no clients are using the rotated keys, we can then remove them safely.

Binding update in the clients

Updating the bindings on the client-side involves comparing the keys used for binding with the ones advertised by the Tang server. If the keys used for binding are not present in the server advertisement, it means they have been rotated in the server, in which case you could update the binding to use the new keys.

Performing this kind of verification was a complex task, as one had to deal directly with several command-line interface (CLI) utilities, such as cryptsetup, jose, luksmeta -- if handling LUKS v1 devices --, and so on, to verify whether the bindings are using rotated keys. 

Getting information to answer questions like "What bindings do I have in this device, if any?" or "What configuration is it using in this particular slot, as in, which Tang server is it bound to?", for instance, was already a non-trivial task.

RHEL now offers a few command-line utilities that help to answer these questions and also help to simplify the process of performing the key rotation on the clients when required. 

One of the tools you'll use is clevis, a utility to do things like bind, encrypt and decrypt devices. The clevis luks list command that can list clevis pins bound to a particular LUKS device.

Using clevis luks list

This command indicates whether there are any bindings, and what their configuration details are. As an example, identify Clevis bindings in the/dev/sda2 device:

clevis luks list -d /dev/sda2
1: tang '{"url":""}'

The output of clevis luks list in this example indicates slot number 1 in /dev/sda2 is bound to a Tang configuration, and the associated Tang server is This is useful information we did not have before.

At this point, the clevis luks report and clevis luks regen operations help you with identifying if there are any rotated keys and performing the binding update itself.

Digital-Transformation-Minispot-Technology-illustration-quote copy_Blog-thumbnail.pngThe clevis luks report and clevis luks regen commands

These two commands simplify the rotation of keys. The former tells you whether you are using any rotated keys, and the latter performs a rebinding, which means your Tang server will be using the new keys after it finishes.

Using clevis luks report compares the keys in use in the binding with the keys advertised by the server. If it detects the keys differ, it reports about the presence of rotated keys and offers to use clevis luks regen, to update the binding.

Using clevis luks regen, on the other hand, performs a rebinding using the existing binding configuration. After it runs, the binding will be using the new keys, and if you re-run clevis luks report, then you will get no output, meaning that there are no rotated keys present.

For specifics on how to use these commands, please refer to the RHEL product documentation.

Edit bindings

This new option to clevis luks helps you to edit a particular binding configuration to change specific attributes. For example, in a tang pin, you can change the URL address of the Tang server:

clevis luks edit -d /dev/sda2 -s 1

The previous command opens a text editor with the JSON configuration of the pin in slot number 1 in /dev/sda2, which we can then edit:

  "url": ""

Once you complete the editing, you can save and quit the editor. At this point, Clevis validates the updated JSON configuration and applies it if it does not detect any errors.At the end of this step, you have updated the binding with the new configuration.

Just like their own configuration, the pins support changing different attributes: For example, the tang pin allows changing the URL of the Tang server, while the tpm2 pin allows changing properties like the hash or key, for instance. When using the sss pin, one of the attributes we could change is the threshold of Shamir’s Secret Sharing scheme; we could also either add or remove new pins to its configuration.


As key rotation plays a crucial part in Network-Bound Disk Encryption, RHEL has been focusing on improving the user experience around the relevant procedures involved in it. The procedures that have been traditionally complex. In this post, we presented a few command-line utilities that simplify both verifying if any keys should be updated, as well as updating them when required. Additionally, we also presented another utility that enables you to change parameters in the binding configuration in an easy way.

About the author

Sergio Correia is a software engineer in the Linux Security Group at Red Hat. He is part of the Special Projects team, which is focused on productization and development of security technologies such as fapolicyd, USBGuard and AIDE. He currently maintains the Policy-Based Decryption (PBD) components, which includes Clevis and Tang.