Use Clevis With LUKS

You can bind Clevis to a LUKS slot for any volume or device that's LUKS encrypted. When Clevis is bound to a LUKS slot, automatic network-bound decryption is triggered when a user is prompted for a LUKS passphrase entry.

The following instructions explain how to bind and unbind Clevis against a LUKS slot, verify that Clevis is integrated with LUKS for a volume or device and update Clevis for a volume or device if the Tang keys are rotated.

Bind Clevis to a LUKS Slot

To bind Clevis to a LUKS slot to unlock a LUKS encrypted device by using a Tang server, run the clevis luks bind command. Note that the command prompts you to trust the key that's being advertised by the Tang server. Likewise, the command prompts you for the LUKS password.

When typing the command, provide the path to the device that's LUKS encrypted. In the following example, the system uses LVM and the root volume is LUKS encrypted, so /dev/ol/root is used as the device path. You could equally use a block device such as /dev/sda1. Also, you must provide the URL to the Tang server in a JSON string.

See the following example:

sudo clevis luks bind -d /dev/ol/root tang '{"url": "http://tang-server.example.org:7500"}'
...
The advertisement is signed with the following keys:
        i9sPMu_sn6vMjzyJm8ZALj7opDE

Do you wish to trust the advertisement? [yN] y
Enter existing LUKS password:

This operation performs several steps:

Clevis creates a new key with the same entropy as the primary LUKS key.
The new key is encrypted by Clevis using the Tang key.
Clevis stores the token and metadata to contact the Tang server in the LUKS header.
The key is enabled for use with LUKS.

Verify Clevis Integration With LUKS

You can verify Clevis integration with LUKS in several ways.

Check the LUKSMeta information for a device by using the cryptsetup command.
```
sudo cryptsetup luksDump /dev/ol/root              
```
The output displays that the Clevis key has been added to one of the slots and a clevis token is assigned for that slot.
Check which slot is used by Clevis and the Tang server information for the binding by running the clevis luks list command.
```
sudo clevis luks list -d /dev/ol/root            
```
Check whether the device is automatically unlocked at boot.

If the device is required at boot and clevis-dracut is installed and configured, the system continues to prompt you for a LUKS passphrase at boot; however, Clevis tries to decrypt its key by using the Tang server and unlocks the device automatically. The passphrase prompt closes after a period if Clevis is successful.

Update Clevis for Tang Key Rotation

Periodically a Tang server administrator might rotate Tang keys on the server for more security. When this happens, it's possible that Clevis is unable to decrypt the LUKS token correctly and this must be regenerated using the new Tang key. If Clevis fails to decrypt the LUKS token, you must authenticate to LUKS using passphrase entry at boot.

To check whether Tang keys have been rotated and to regenerate a newly encrypted token, perform the following steps:

Identify the LUKS slot that Clevis is bound to for a specified device.
```
sudo clevis luks list -d /dev/ol/root
```
Output similar to the following might be displayed:
```
1: tang '{"url":"http://tang-server.example.org:7500"}'
```
Get Clevis to report whether the Tang key has been updated on the specified slot and automatically regenerate the LUKS token.
```
sudo clevis luks report -d /dev/ol/root -s 1
```
Output similar to the following might be displayed:
```
...
Report detected that some keys were rotated.
Do you want to regenerate luks metadata with 
"clevis luks regen -d /dev/ol/root -s 1"? [ynYN]
```
Enter y to tell Clevis to automatically regenerate the LUKS token.

Note that you can optionally unbind Clevis from an existing LUKS slot and then bind it again if the instructions to regenerate a token don't work for you.

Unbind Clevis From a LUKS Slot

You can unbind Clevis from a LUKS slot by using the clevis luks unbind command:

Note that you must specify the slot number that Clevis is bound to by specifying the -s option, followed by the slot number. Be aware that this operation is destructive and wipes the LUKSMeta data for the slot that's specified, so you're prompted to confirm the operation.

Use the clevis luks unbind command to remove Clevis LUKS metadata from a slot.
```
sudo clevis luks unbind -d /dev/ol/root -s 1
```
Verify that the slot is clear of metadata in LUKS.
```
sudo cryptsetup luksDump /dev/ol/root
```
The output displays that no metadata exists for clevis in the slot.