4.10. Using Network-Bound Disk Encryption

The Network-Bound Disk Encryption (NBDE) allows the user to encrypt root volumes of hard drives on physical and virtual machines without requiring to manually enter a password when systems are restarted.
In Red Hat Enterprise Linux 7, NBDE is implemented through the following components and technologies:
The Network-Bound Disk Encryption using Clevis and Tang

Figure 4.2. The Network-Bound Disk Encryption using Clevis and Tang

Tang is a server for binding data to network presence. It makes a system containing your data available when the system is bound to a certain secure network. Tang is stateless and does not require TLS or authentication. Unlike escrow-based solutions, where the server stores all encryption keys and has knowledge of every key ever used, Tang never sees a single client key. Tang never gains any identifying information from the client.
The Clevis is a pluggable framework for automated decryption. In NBDE, Clevis provides automated unlocking of LUKS volumes. The clevis package provides the client side of the feature.
A Clevis Pin is a plug-in into the Clevis framework. One of such PINs is a plug-in that implements interactions with the NBDE server — Tang.
Clevis and Tang are generic client and server components to provide network-bound encryption. In Red Hat Enterprise Linux 7, they are used in conjunction to encrypt and decrypt root volumes of hard drives to accomplish the Network-Bound Disk Encryption.
Both client- and server-side components use the José library to perform encryption and decryption operations.
The Clevis Pin for Tang server gets a list of the Tang server's advertised asymmetric keys. Alternatively, since the keys are asymmetric, a list of Tang’s public keys can be distributed out of the band so that clients can operate without access to the Tang server. This mode is called offline provisioning.
The Clevis Pin for Tang uses one of the public keys to generate a unique, cryptographically-strong encryption key. Once the data are encrypted using this key, the key is discarded. The client should store the state produced by this provisioning operation in a convenient location. This process of encrypting data is the provisioning step. The provisioning state for NBDE is stored in the LUKS header leveraging the luksmeta package.
When the client is ready to access its data, it loads the metadata produced in the provisioning step and it responds to recover the encryption key. This process is the recovery step.
In NBDE, Clevis binds a LUKS volume using a PIN so that it can be automatically unlocked. After successful completion of the binding process, the disk can be unlocked using the provided Dracut unlocker.

4.10.1. Deploying a Tang server

To install the tang package and its dependencies, enter the following command as root:
~]# yum install tang
Enable and start the tangd service using systemd:
~]# systemctl enable tangd.socket --now
Created symlink from /etc/systemd/system/multi-user.target.wants/tangd.socket to /usr/lib/systemd/system/tangd.socket.
Since tangd uses the systemd socket activation mechanism, the server starts as soon as the first connection comes in. A new set of cryptographic keys is automatically generated at the first start.
To perform cryptographic operations such as manual key generation, use the jose utility. Enter the jose -h command or see the jose(1) man pages for more information.

Example 4.3. Rotating Tang Keys

It is important to periodically rotate your keys. The precise interval at which you should rotate them depends upon your application, key sizes, and institutional policy. For some common recommendations, see the Cryptographic Key Length Recommendation page.
To rotate keys, start with the generation of new keys in the key database directory, typically /var/db/tang. For example, you can create new signature and exchange keys with the following commands:
~]# DB=/var/db/tang
~]# jose jwk gen -i '{"alg":"ES512"}' -o $DB/new_sig.jwk
~]# jose jwk gen -i '{"alg":"ECMR"}' -o $DB/new_exc.jwk
Rename the old keys to have a leading . to hide them from advertisement:
~]# mv $DB/old_sig.jwk $DB/.old_sig.jwk
~]# mv $DB/old_exc.jwk $DB/.old_exc.jwk
Tang immediately picks up all changes. No restart is required.
At this point, new client bindings pick up the new keys and old clients can continue to utilize the old keys. When you are sure that all old clients use the new keys, you can remove the old keys.


Be aware that removing the old keys while clients are still using them can result in data loss.
Tang uses port 80 for communication. This port is also widely-used for web servers. To change Tang's port number, override the tangd.socket unit file using the standard systemd mechanisms. See Red Hat Enterprise Linux 7 System Administrator's Guide: Creating and Modifying systemd Unit Files for more information. Deploying High-Availability Systems

Tang provides two methods for building a high-availability deployment:
  1. Client Redundancy (Recommended)
    Clients should be configured with the ability to bind to multiple Tang servers. In this setup, each Tang server has its own keys and clients are able to decrypt by contacting a subset of these servers. Clevis already supports this workflow through its sss plug-in.
    For more information about this setup, see the following man pages:
    • tang(8), section High Availability
    • clevis(1), section Shamir's Secret Sharing
    • clevis-encrypt-sss(1)
    Red Hat recommends this method for a high-availability deployment.
  2. Key Sharing
    For redundancy purposes, more than one instance of Tang can be deployed. To set up a second or any subsequent instance, install the tang packages and copy the key directory to the new host using rsync over SSH. Note that Red Hat does not recommend this method because sharing keys increases the risk of key compromise and requires additional automation infrastructure.

4.10.2. Deploying an Encryption Client

To install the Clevis pluggable framework and its PINs on the machine with an encrypted volume (client), enter the following command as root:
~]# yum install clevis
To encrypt plaintext data into a JSON Web Encryption (JWE) ciphertext object using a Tang PIN, use the clevis encrypt tang command, for example:
~]$ clevis encrypt tang '{"url":"http://tang.srv"}' < PLAINTEXT > JWE
The advertisement contains the following signing keys:


Do you wish to trust these keys? [ynYN] y
Change the http://tang.srv URL in the previous example to match the URL of the server where tang is installed. The JWE output file contains your encrypted cipher text. This cipher text is read from the PLAINTEXT input file.
To decrypt data, use the clevis decrypt command and provide the cipher text (JWE):
~]$ clevis decrypt < JWE > PLAINTEXT
For more information, see the clevis-encrypt-tang(1) man page or use the built-in CLI help:
~]$ clevis
Usage: clevis COMMAND [OPTIONS]

  clevis bind luks    Binds a LUKSv1 device using the specified policy
  clevis decrypt      Decrypts using the policy defined at encryption time
  clevis encrypt http Encrypts using a REST HTTP escrow server policy
  clevis encrypt sss  Encrypts using a Shamir's Secret Sharing policy
  clevis encrypt tang Encrypts using a Tang binding server policy

~]$ clevis decrypt
Usage: clevis decrypt < JWE > PLAINTEXT

Decrypts using the policy defined at encryption time

~]$ clevis encrypt tang
Usage: clevis encrypt tang CONFIG < PLAINTEXT > JWE

Encrypts using a Tang binding server policy

This command uses the following configuration properties:

  url: <string>   The base URL of the Tang server (REQUIRED)

  thp: <string>   The thumbprint of a trusted signing key

  adv: <string>   A filename containing a trusted advertisement
  adv: <object>   A trusted advertisement (raw JSON)

Obtaining the thumbprint of a trusted signing key is easy. If you
have access to the Tang server's database directory, simply do:

    $ jose jwk thp -i $DBDIR/$SIG.jwk 

Alternatively, if you have certainty that your network connection
is not compromised (not likely), you can download the advertisement
yourself using:

    $ curl -f $URL/adv > adv.jws

4.10.3. Configuring Manual Enrollment

To bind an existing LUKS volume to its automation policy, install the clevis-luks subpackage:
~]# yum install clevis-luks
Then use the clevis bind luks command, for example:
~]# clevis bind luks -d /dev/sda tang '{"url":"http://tang.srv"}'
The advertisement contains the following signing keys:


Do you wish to trust these keys? [ynYN] y
You are about to initialize a LUKS device for metadata storage.
Attempting to initialize it may result in data loss if data was
already written into the LUKS header gap in a different format.
A backup is advised before initialization is performed.

Do you wish to initialize /dev/sda? [yn] y
Enter existing LUKS password:
This command performs four steps:
  1. Creates a new key with the same entropy as the LUKS master key.
  2. Encrypts the new key with Clevis.
  3. Stores the Clevis JWE object in the LUKS header with LUKSMeta.
  4. Enables the new key for use with LUKS.
This disk can now be unlocked with your existing password as well as with the Clevis policy. For more information, see the clevis-bind-luks(1) man page.


The binding procedure assumes that there is at least one free LUKS password slot. The clevis bind luks command takes one of the slots.
To verify that the Clevis JWE object is successfully placed in a LUKS header, use the luksmeta show command:
~]# luksmeta show -d /dev/sda
0   active empty
1   active cb6e8904-81ff-40da-a84a-07ab9ab5715e
2 inactive empty
3 inactive empty
4 inactive empty
5 inactive empty
6 inactive empty
7 inactive empty
To enable the early boot system to process the disk binding, enter the following commands on an already-installed system:
~]# yum install clevis-dracut
~]# dracut -f

4.10.4. Configuring Automated Enrollment Using Kickstart

Clevis can integrate with Kickstart to provide a fully automated enrollment process.
  1. Instruct Kickstart to partition the disk such that the root partition has enabled LUKS encryption with a temporary password. The password is temporary for the enrollment process.
    part /boot --fstype="xfs" --ondisk=vda --size=256
    part / --fstype="xfs" --ondisk=vda --grow --encrypted --passphrase=temppass
  2. Install the related Clevis packages by listing them in the %packages section:
  3. Call clevis bind luks to perform binding in the %post section. Afterward, remove the temporary password:
    clevis bind luks -f -k- -d /dev/vda2 \                                          
        tang '{"url":"http://tang.srv","thp":"_OsIk0T-E2l6qjfdDiwVmidoZjA"}' \ 
        <<< "temppass"                                                              
    cryptsetup luksRemoveKey /dev/vda2 - <<< "temppass"
    In the above example, note that we specify the thumbprint that we trust on the Tang server as part of our binding configuration, enabling binding to be completely non-interactive.
For more information on Kickstart installations, see the Red Hat Enterprise Linux 7 Installation Guide. For information on Linux Unified Key Setup-on-disk-format (LUKS), see Section 4.9.1, “Using LUKS Disk Encryption”.

4.10.5. Deploying Virtual Machines in a NBDE Network

The clevis bind luks command does not change the LUKS master key. This implies that if you create a LUKS-encrypted image for use in a virtual machine or cloud environment, all the instances that run this image will share a master key. This is extremely insecure and should be avoided at all times.
This is not a limitation of Clevis but a design principle of LUKS. If you wish to have encrypted root volumes in a cloud, you need to make sure that you perform the installation process (usually using Kickstart) for each instance of Red Hat Enterprise Linux in a cloud as well. The images cannot be shared without also sharing a LUKS master key.
If you intend to deploy automated unlocking in a virtualized environment, Red Hat strongly recommends that you use Kickstart (see Section 4.10.4, “Configuring Automated Enrollment Using Kickstart”) or another automated provisioning tool to ensure that each encrypted VM has a unique master key.

4.10.6. Building Automatically-enrollable VM Images for Cloud Environments

Deploying automated decryption images in a cloud environment can provide a unique set of challenges. Like other virtualization environments detailed above, images should be instantiated at most once to avoid sharing the LUKS master key. Therefore, automated deployment systems such as Kickstart should be used to ensure master key uniqueness during the image building process.
Cloud environments enable two Tang server deployment options which we consider here. First, the Tang server can be deployed within the cloud environment itself. Second, the Tang server can be deployed outside of the cloud on independent infrastructure with a VPN link between the two infrastructures.
Deploying Tang natively in the cloud does allow for easy deployment. However, given that it shares infrastructure with the data persistence layer of ciphertext of other systems, it may be possible for both the Tang server’s private key and the Clevis metadata to be stored on the same physical disk. Access to this physical disk permits a full compromise of the ciphertext data.


For this reason, Red Hat strongly recommends that the Tang server is deployed off premises with a VPN link between the cloud and the Tang server. This ensures that the Tang server’s private key cannot be accidentally combined with the Clevis metadata. It also provides local control of the Tang server if the cloud infrastructure is in risk.

4.10.7. Additional Resources

For more information, see the following man pages:
  • tang(8)
  • clevis(1)
  • jose(1)