> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up Data Encryption

export const Thales = "Thalesᴹᴰ";

export const Ocient = "Ocient®";

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](https://sedutil.com/) 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](https://github.com/OpenKMIP/PyKMIP) configuration file format, such as this text.

<CodeGroup>
  ```none none theme={null}
  [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
  ```
</CodeGroup>

2. Run this command.

<CodeGroup>
  ```shell shell theme={null}
  sudo /usr/local/bin/ockmip init
  ```
</CodeGroup>

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.

```shell Shell theme={null}
sudo /usr/local/bin/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.

<CodeGroup>
  ```shell shell theme={null}
  ## Ocient has been bootstrapped.
  ockmip import-drives
  ```
</CodeGroup>

<CodeGroup>
  ```shell shell theme={null}
  ## Ocient has not been bootstrapped.
  ockmip init-drives
  ```
</CodeGroup>

5. Set the node role configuration to `useOpal: false` within the `rolehostd.conf` file.
6. Back up any existing keys in `/var/opt/ocient/localKeyStore` in case you encounter any issues.
7. Install the `systemd` service to unlock drives on the reboot.

<CodeGroup>
  ```shell shell theme={null}
  ockmip install
  ```
</CodeGroup>

8. 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.

```text Text theme={null}
[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.

```text Text theme={null}
[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.

```shell Shell theme={null}
sudo /usr/local/bin/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.

```shell Shell theme={null}
sudo ockmip unlock --drives /dev/nvme1n1 --drives /dev/nvme2n1
```

### `NCERRInsufficentPermissions` Error

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

```text Text theme={null}
[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.

```text Text theme={null}
[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.

```text Text theme={null}
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](/ocient-security-guide)

[Authentication Methods](/authentication-methods)