NAME¶

cryptctl - Set up LUKS-based disk encryption

SYNOPSIS¶

cryptctl init-server

cryptctl list-keys

cryptctl edit-key UUID

cryptctl show-key UUID

cryptctl encrypt

cryptctl online-unlock

cryptctl offline-unlock

cryptctl erase

DESCRIPTION¶

cryptctl is a utility for setting up disk encryption using the popular well-established LUKS method. It generates random numbers to use as encryption keys, and safely keep the keys on a centralised key server. It can encrypt arbitrary directories into encrypted disk partitions.

The key server stores all encryption keys in a database directory (by default /var/lib/cryptctl/keydb) and serves the keys via an RPC protocol over TCP (by default on port 3737) to client computers. The key server is the central component of encryption setup, hence it must be deployed with extra physical/network security measures; regular backup of the key database must be carried out to ensure its availability. Communication between key server and client computers is protected by TLS via a certificate, and authorised via a password specified by the system administrator during key server's initial setup.

The encryption routine sets up encrypted file systems using using aes-xts-plain64 cipher, with a fixed-size (512-bit) key generated from cryptically secure random pool. Encrypted directories will always be mounted automatically upon system boot by retrieving their encryption keys from key server automatically; this operation tolerates temporary network failure or key server down time by making continuous attempts until success, for maximum of 24 hours.

The system administrator can define an upper limit number of computers that can get hold of a key simultaneously. After a client computer successfully retrieves a key, it will keep reporting back to key server that it is online, and the key server closely tracks its IP, host name, and timestamp, in order to determine number of computers actively using the key; if the upper limit number of computers is reached, the key will no longer be handed out automatically; system administrator can always retrieve encryption keys by using key server's access password.

cryptctl can optionally utilise an external key management appliance that understands KMIP v1.3 to store the actual disk encryption keys. Should you choose to use the external appliance, you may enter KMIP connectivity details such as host name, port, certificate, and user credentials during server initialisation sequence. If you do not wish to use the external appliance, cryptctl will store encryption keys in its own database.

KEY SERVER ACTIONS¶

init-server

Initialise key server parameters such as password, TLS certificate, Email notifications, etc. This initial setup must be carried out before starting the key server.

list-keys

Show all records from key database, sorted according to last usage.

edit-key

Edit usage limitation and mount options of a key record.

show-key

Show key record details such as mount options and current usages.

send-command

In a key record, save a pending command to tell a computer (that polls for commands regularly) to mount or umount a disk.

clear-commands

Clear all pending commands in a key record.

ENCRYPTION ROUTINE¶

On a client computer, calling "cryptctl encrypt" will commence the encryption routine. The workflow will ask user for location of key server, key user limit, and other questions. Then pre-encryption checks will be conducted to validate the input parameters, and after a final confirmation prompt, encryption routine will start:

1

Wipe the partition to be encrypted.

2

Generate an encryption key from cryptographically secure random source provided by internal (auto-launched) or external KMIP service.

3

Set up LUKS metadata on the partition to encrypt, then make new file system on it, matching the type of that from the directory to encrypt.

4

Copy all files, file attributes, and directories from the directory to encrypt to the new encrypted partition. The backup operation is carried out via rsync using an efficient method.

5

Send RPC request to key server to save the encryption key, along with mount point location and options.

6

Save key server's information into configuration file (/etc/sysconfig/cryptctl-client) so that after a reboot, encrypted disks can be mounted automatically using keys retrieved from the key server.

7

The key server will send out a notification Email (if enabled) to inform system administrator that the directory has been successfully encrypted.

The original un-encrypted data will be moved into a directory with prefix name "cryptctl-moved-", please erase the original un-encrypted data after having successfully tested your systems with the now encrypted directory.

UNLOCKING ROUTINE¶

Without manual intervention, a client computer will always attempt to automatically unlock encrypted disks upon reboot. The process tolerates temporary network failure and key server's down time by making continuous attempts for up to 24 hours until a key is successfully retrieved. If Email notification is enabled on the key server, the system administrator will be informed via Email that a computer has successfully retrieve encryption key(s).

The key server makes sure that upper limit number (defined by user) of computers is not exceeded before handing out the keys. System administrator can override the protection by running "cryptctl online-unlock" on the client computer and provide key server's access password in the prompt, which will then unconditionally retrieve encryption keys to unlock the disks. Consequently the key server will not track key usage from the computer, despite that it is now holding the encryption keys.

In normal circumstances, encryption keys are retrieved via network communication. Should the key server become unavailable or the communication be cut off, already unlocked file systems will remain mounted, however locked file systems will not be able to retrieve encryption keys from the key server. Hence, this manual procedure has been designed to allow unlocking of encrypted disks directly from key database record, via physical access to both the key server and client computer. This procedure is not applicable should you have used an external KMIP appliance to store encryption keys, nor will it trigger Email notification or track key usage.

1

On client computer, identify the encrypted file system's UUID from output of command "lsblk -O" (as root).

2

On key server, navigate to key database directory (located in /var/lib/cryptctl/keydb by default), copy the key file named after UUID onto a removable storage device, such as an SD card.

3

Transport the key file to the client computer, run "cryptctl offline-unlock", and provide path to the key file in prompt.

4

Re-enter mount point location/options or accept their defaults. The file system is now unlocked and mounted.

COMMUNICATION SECURITY¶

The key server and client use TLS (Transport Layer Security) to securely transfer password and disk encryption keys, the program always enforces TLS certificate verification before transferring the sensitive data. A key server requires exactly one TLS certificate (and associated certificate infrastructure) to operate.

For experimental purposes, you may use a self-signed certificate to operate the key server and client, such certificate can be easily generated from command:
openssl req -new -newkey rsa:2048 -days 30 -nodes -x509 -keyout testing.key -out testing.crt

When asked for a "Common Name", enter the fully qualified domain name of key server; after the certificate is generated successfully, you may initialise key server using "testing.crt" (certificate file) and "testing.key" (certificate key file).

By default, a client only trusts well-known certificate authorities defined in /etc/ssl/ca-bundle.pem. To operate the client using the self-signed certificate, transfer the certificate file to client and append the following parameter to every operation:
-ca=/path/to/testing.crt

By default, the key server accepts encryption requests from all password-authenticated clients, and hands out encryption keys to all clients that request keys for a valid disk UUID. If you wish to further strengthen verification on client identity, you may enter an authority certificate file during server's initialisation sequence, from there all clients must present valid certificate issued by the specified CA in order to contact the key server.

In order to build a public key infrastructure to issue server and client certificates, consider using lightweight tools
such as "easy-rsa" by OpenVPN, or YaST Certificate Management program.

ON USING EXTERNAL KMIP SERVER APPLIANCE¶

By default, the key server stores all disk encryption keys along with key usage tracking data in a built-in database. If you decide to use an external KMIP server appliance to store and manage disk encryption keys, you may enter its connectivity details during server's initialisation sequence. You must make the decision on whether to use external KMIP server before any disk is encrypted using the key server, and you may not change the settings (e.g. turn off KMIP and use built-in database again) once a disk has been encrypted.

By default, cryptctl performs strong verification on all TLS certificates. When it acts as a KMIP client, it verifies the common name of KMIP server against the certificate presented by it, along with other checks such as validity date. Should any certificate verification error occur, cryptctl will report back with the error reason and temporarily cease conversation with the KMIP server. It is strongly recommended to leave certificate verification enabled.

However, should you wish not to verify KMIP server certificate, you may turn it off by editing server configuration file /etc/sysconfig/cryptctl-server , find key "KMIP_TLS_DO_VERIFY" and change its value to "no", then restart cryptctl-server.service. Turning off the verification opens up the risk of leaking disk encryption keys to eavesdroppers.

CHANGE/REVOKE OR DELETE ENCRYPTION KEY¶

If you decide to revoke or change encryption key for an encrypted file system, please back up the encrypted data onto a disk and re-run the encryption routine in order to encrypt with a new key. The utility does not provide other means to revoke or change encryption key.

Destroy an encryption key will render an encrypted file system irreversibly lost, execute "cryptctl erase" on the client computer and enter the file system UUID will erase the key tracking record from key server, the key content from KMIP server (if used), and the metadata of encrypted file system.

FILES¶

/etc/sysconfig/cryptctl-server

/etc/sysconfig/cryptctl-client

AUTHOR¶

Howard Guo <hguo@suse.com>