Skip to navigation
Database AdministrationOcient Security Guide

Set Up Data Encryption

View as Markdown

The Ocient® System enables you to set up data encryption on data drives that support The Computing Group (TCG) Opal Specification and store the encryption secrets in an external Key Management System (KMS) utilizing the Key Management Interoperability Protocol (KMIP). This series of workflows demonstrates generating and storing secrets using the Thalesᴹᴰ CipherTrust Manager KMS.

Prerequisites

A KMIP server, such as Thales CipherTrust Manager, must be available to store secrets.

  • The Ocient node must be a registered client of the KMIP server.
  • The client certificate and key file must be on the client, e.g., /var/opt/ocient/kmip/client.crt and /var/opt/ocient/kmip/client.key.
  • The CA certificate must be present on the client, e.g., /var/opt/ocient/ca.pem.
  • The client must be able to communicate with the KMIP server.

The SEDutil CLI utility must be installed to manage the SED configuration of the drive. The sedutil-cli command must be available on the system path variable PATH.

Ensure all NVMe drives intended for use with Ocient are:

  • Bound to the kernel NVMe driver.
  • Have no partition table.
  • Be in the Opal factory state.
    • Use --revertTPer or --revertNoErase SEDutil commands.
  • Have these initial settings for the drives and SIDPassword set to admin:
    • Locked = N
    • LockingEnabled = N
    • LockingSupported = Y
    • MBRDone = N
    • MBREnabled = N
    • MBRAbsent = N
    • MediaEncrypt = Y

Set Up Data Encryption

Use a configuration file and script to generate the secret or key.

  1. Generate a configuration file with the path /var/opt/ocient/ockmip.conf. The configuration file uses the PyKMIP configuration file format, such as this text.
Configuration
[client]
host=thales01.example.com
port=5696
certfile=/var/opt/ocient/kmip/client.crt
keyfile=/var/opt/ocient/kmip/client.key
ca_certs=/var/opt/ocient/kmip/ca.pem
  1. Run this command.
Shell
sudo /opt/ocient/utils/ockmip init

The script performs these operations for each drive that is detected as unused by the OS (no partition table present or with an Ocient partition):

  • Generate a password or key for locking the drive.
  • Store the secret password or key on the KMIP server.
  • Enable Opal locking on the drive and set the admin1 password to the generated secret.
  • Set the SIDpassword to admin to enable reverting the drive to the factory state in case the admin1 password is lost.

To enable the script to run on start before the drives are bound to the uio or vfio driver by the system bind-uio-driver.service installed by the ocient package, run this command.

sudo /opt/ocient/utils/ockmip install

On reboot, the ockmip service unlocks the drives before they are bound to the uio or vfio driver and available for use by the rolehostd process.

The full setup sequence is as follows:

  1. Configure the ockmip.conf configuration file with all of the appropriate settings.
  2. Stop the rolehostd process if it is running.
  3. Unbind drives from the uio or vfio driver back to the NVMe driver.
  4. If Ocient has already been bootstrapped on the node, use the import-drives command. Otherwise, use the init-drives command.
Bootstrapped
# Ocient has been bootstrapped.
ockmip import-drives
Not Bootstrapped
# Ocient has not been bootstrapped.
ockmip init-drives
  1. Set the node role configuration to useOpal: false within the rolehostd.conf file.
  2. Back up any existing keys in /var/opt/ocient/localKeyStore in case you encounter any issues.
  3. Install the systemd service to unlock drives on the reboot.
Shell
ockmip install
  1. Optionally, perform a power off and power on to ensure the installation was successful and that the ockmip.service successfully unlocks drives on boot.

Migration process output might be similar to this output.

  \[root\@ppolllercs00006 ocient]# ockmip -l DEBUG import-drives
  \[2024-09-12 12:45:32,853]\[INFO] Using conf file /var/opt/ocient/ockmip.conf
  \[2024-09-12 12:45:33,427]\[INFO] importing drive(s)
  \[2024-09-12 12:45:33,427]\[INFO] Importing secret for /dev/nvme15 BTAX240306A015PFGN
  ...

After reboot, the ockmip service output might be similar to this output.

  [root@dpolllercs0002e log]# systemctl status ockmip
  ○ ockmip.service - Oneshot service to unlock NVMe drives via ockmip script using secrets stored in KMIP service.
      Loaded: loaded (/etc/systemd/system/ockmip.service; enabled; preset: disabled)
      Active: inactive (dead) since Wed 2024-09-11 19:11:55 UTC; 31min ago
     Process: 3217 ExecStart=/usr/local/bin/ockmip unlock (code=exited, status=0/SUCCESS)
    Main PID: 3217 (code=exited, status=0/SUCCESS)
         CPU: 3.097s
  Sep 11 19:11:52 dpolllercs0002e ockmip[3217]: [2024-09-11 19:11:52,429][INFO] Retrieving secret for /dev/nvme2 S64GNN0WC04870
  ...

The rolehostd process should start up without the process managing encryption because the ockmip service handles it.

Troubleshooting

For more details on the possible commands, see the help using this command.

sudo /opt/ocient/utils/ockmip --help

To diagnose issues, examine the log located at /var/opt/ocient/log/ockmip.log

To perform actions on a particular drive or set of drives, you can manually specify with the --drives parameter.

sudo ockmip unlock --drives /dev/nvme1n1 --drives /dev/nvme2n1

NCERRInsufficentPermissions Error

When attempting to register the drives, you see this error.

  [2024-08-26 17:27:51,350][INFO] Using conf file /var/opt/ocient/ockmip.conf [2024-08-26 17:27:51,917][INFO] Initializing drive(s) [2024-08-26 17:27:51,917][INFO] Generating and storing secret for /dev/nvme15 [2024-08-26 17:27:52,089][ERROR] Error registering secret with KMIP server /dev/nvme15 Traceback (most recent call last): File "/opt/ocient/utils/test/ocutil.sh.runfiles/xgsrc/python/ocutil/ockmip.py", line 232, in initDrives self.client.register(data) File "/opt/ocient/utils/test/ocutil.sh.runfiles/pip_packages_pykmip/site-packages/kmip/pie/client.py", line 41, in wrapper return function(self, *args, **kwargs) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/opt/ocient/utils/test/ocutil.sh.runfiles/pip_packages_pykmip/site-packages/kmip/pie/client.py", line 573, in register raise exceptions.KmipOperationFailure(status, reason, message) kmip.pie.exceptions.KmipOperationFailure: OPERATION_FAILED: GENERAL_FAILURE - [NCERRInsufficientPermissions]:

To fix this, regenerate the certificate on the endpoint of the Thales device (as the root CA has no trust) in the Thales Administrator.

Disk Replacement

After you swap a disk, initialize it using the ockmip utility to add the encryption secret to Thales.

ockmip.service Status

Check the status after the boot of the system to ensure that all drives have been correctly unlocked.

  [root@ppolllercs00007 ~]# journalctl -u ockmip -S today Sep 12 12:38:09 ppolllercs00007 systemd[1]: Starting Oneshot service to unlock NVMe drives via ockmip script using secrets stored in KMIP service.... Sep 12 12:38:10 ppolllercs00007 ockmip[2681]: [2024-09-12 12:38:10,623][INFO] Using conf file /var/opt/ocient/ockmip.conf Sep 12 12:38:11 ppolllercs00007 ockmip[2681]: [2024-09-12 12:38:11,221][INFO] Unlocking drive(s)
  ...

Timeouts When Contacting Thales

If there is a network outage or if Thales maintenance happens, you might see this output when you attempt to unlock the drives.

  Sep 12 17:05:59 ppolllercs0000d systemd[1]: Starting Oneshot service to unlock NVMe drives via ockmip script using secrets stored in KMIP service.... Sep 12 17:06:01 ppolllercs0000d ockmip[3346]: [2024-09-12 17:06:01,040][INFO] Using conf file /var/opt/ocient/ockmip.conf Sep 12 17:06:31 ppolllercs0000d ockmip[3346]: [2024-09-12 17:06:31,345][ERROR] An error occurred while connecting to appliance cmttnprd5a.t-mobile.com: timed out Sep 12 17:06:31 ppolllercs0000d ockmip[3346]: [2024-09-12 17:06:31,346][ERROR] could not open client connection: timed out Sep 12 17:06:31 ppolllercs0000d ockmip[3346]: [2024-09-12 17:06:31,346][ERROR] Unable to open connection to KMIP server
  ...

Related Links

Ocient Security Guide

Authentication Methods