Configuring Client-Side Key Caching

When a VM is first registered with KeyControl, KeyControl creates a new key and delivers it to that VM. After the initial registration, KeyControl delivers a new key whenever the VM re-boots and authenticates itself with KeyControl.

If the VM cannot access the KeyControl cluster for a time exceeding the Grace Period, access to clear-text devices is revoked. Also, if the VM is not able to contact the KeyControl cluster on boot, the keys will not be accessible and access will be revoked.

If you want to maintain data access even when KeyControl is not reachable, you can use the CLI to enable the client-side cached key mode for a specific drive in a VM. In this mode, keys can be wrapped in a passphrase and cached on the VM for a specified period of time. If the VM boots and is not able to access the KeyControl cluster, the keys for this drive can still be accessed by typing the passphrase.

Note: Client-side key caching is not available for root-encrypted drives, and is not supported on the Windows boot partition.

After a disk has been attached using cached keys, access remains available until either the keys expire or an explicit hcl detach command is issued. If the keys have expired, the next time a user attempts to access the disk they will see an error message stating that access is denied. We recommend that you reattach all disks using the normal KeyControl keys as soon as access to KeyControl is restored.

Procedure

Log into the VM as root.
Enter the command hcl cache [-n number-of-days] [-p passphrase] <diskname | -a> where:
- -n number-of-days is the number of days for which the keys should be cached. If the -n option is not specified, keys will be cached for a default of one day. The max number of days the keys should be cached is 9999 days.
- -p passphrase is the passphrase that should be used to access the cached keys.
- diskname | -a is either a specific disk name or -a for all disks in the VM.
For example, if you have two disks called sdb1 and sdb2 and you want to cache the keys for sdb1 for 3 days using the passphrase "HyTrust", you would enter:

# hcl cache -n 3 -p HyTrust sdb1

If you want to cache the keys for both disks for one day and be prompted for the passphrase, you would enter:
```
# hcl cache -n 1 -a
Enter passphrase (min 4 characters): ********
Re-enter passphrase: ********
Cached keys for device sdb1 sdb2
```

To verify that the keys are properly cached, enter the command: hcl cache -l.

For example:

# hcl cache -l

Cached keys for Devices
---------------------------------------------------
Disk Name         Valid till
---------------------------------------------------
sdb1              06/30/17
sdb2              06/30/17

To access the disks using the cached keys if the KeyControl cluster is unavailable, enter the command: hcl attach [-l [-p passphrase] ] <diskname | -a>, where:
- -l instructs DataControl to look for cached keys.
- -p passphrase is the passphrase for the cached keys.
- diskname | -a is either a specific disk name or -a for all disks in the VM.
For example, let's say that you cached the keys for disk sdb1 for 3 days but you did not cache the keys for device sdb2. Now you want to access both disks when the KeyControl cluster is down. You would enter the following command:
```
# hcl attach -l -a
passphrase: ********
Encrypted device sdb1 (/dev/sdb1) attached; decrypted contents visible at /dev/mapper/clear_sdb1
Could not get encryption key for device sdb2
Failed to attach sdb2
```
DataControl can access the keys cached for sdb1, but as there is no cached key for sdb2, the attach command fails for sdb2. There is no way to access the content of disk sdb2 until the connection to KeyControl is restored.

A similar issue occurs if you cached the keys for both disks but you used a different passphrase for each one. For example, if you cached the keys for sdb1 using the passphrase "HyTrust" and you cached the keys for sdb2 using the passphrase "MyKeys" and you try to attach all disks, you will get the following messages:
```
# hcl attach -l -p HyTrust -a
Encrypted device sdb1 (/dev/sdb1) attached; decrypted contents visible at /dev/mapper/clear_sdb1
Could not get encryption key for device sdb2
Failed to attach sdb2
```
In this case, you would need to issue two separate attach commands to access both disks:
```
# hcl attach -l -p HyTrust sdb1
Encrypted device sdb1 (/dev/sdb1) attached; decrypted contents visible at /dev/mapper/clear_sdb1
# hcl attach -l -p MyKeys sdb2
Encrypted device sdb2 (/dev/sdb2) attached; decrypted contents visible at /dev/mapper/clear_sdb2
```
To remove the keys cached on a VM, enter the command cache -r <diskname | -a>, where:

diskname | -a is either a specific disk name or -a for all disks in the VM.

For example, to remove the keys cached for disk sdb1, you would enter:

# hcl cache -r sdb1

To remove the keys for all disks in the VM, you would enter:

# hcl cache -r -a