Disk Encryption
One integration, three on-host engines — LUKS, Cryhod and BitLocker — unlocked against a key-encryption-key held in your DuoKey vault.
Overview
Disk Encryption is a single app type in the Apps catalog that protects one or more volumes, each bound to one of three on-host encryption engines. In every case, the volume's own data-encryption key never leaves the host and is unchanged by DuoKey — what DuoKey holds is a key-encryption-key (KEK) that wraps access to it. The host-side engine reaches the KEK through a DuoKey-provided interface (a PKCS#11 provider for LUKS and Cryhod, or a CNG Key Storage Provider certificate for BitLocker) instead of storing it locally, so raw key material never lands on disk in the clear and never lands in the DuoKey Cockpit database either — the KEK stays inside the linked vault and is only ever used there to unwrap.
All three engines reach the vault-held key-encryption-key through a DuoKey-provided interface; the private half of the KEK never leaves the vault.
| Engine | Host OS | Interface | Unlock mechanism |
|---|---|---|---|
| LUKS | Linux | PKCS#11 provider | A keyslot is bound to the vault-held KEK via a PKCS#11 token URI; the driver asks the provider to unwrap the volume key at boot. |
| Prim'X Cryhod | Windows | PKCS#11 provider | Cryhod's encryption centre selects the DuoKey PKCS#11 device and locates the KEK by a configured tag. |
| Microsoft BitLocker | Windows | CNG Key Storage Provider | The vault KEK is exposed as a smart-card certificate and added as a BitLocker key protector. |
Disk Encryption is a single app in the Apps catalog. When you create it you choose the engine (luks, cryhod or bitlocker); the volume, its KEK and its enrollment state are then managed the same way regardless of engine.
Volumes and key-encryption-keys
Each disk-encryption app protects one or more volumes. Creating a volume registers it against a host and, optionally, a workload label — a purely informational tag (for example elasticsearch) noting which data directory the volume protects; it does not change how the volume is encrypted, since these engines protect the underlying volume regardless of what runs on top of it.
Enrolling a volume creates its KEK — an RSA key (2048-bit by default, or 4096-bit) — inside the linked vault (your tenant's software vault by default, or a vault you choose). The KEK is created as a managed key, so it also appears in the Keys module under its vault. Because the KEK is asymmetric, unlocking a volume is an RSA-OAEP decrypt of the wrapped volume key performed inside the vault adapter — the private half of the KEK never leaves it.
| Volume field | Meaning |
|---|---|
| Enrollment state | pending (registered, no KEK bound yet), enrolled (KEK bound and usable), failed, or rotating (a key rotation is in progress). |
| State | active (may unlock), suspended (unlock refused), or revoked. |
| KEK algorithm | RSA-2048 (default) or RSA-4096, selectable at enrollment or rotation time. |
Once a volume's state is anything other than active, DuoKey refuses every unlock request for it — including a legitimate boot. Only suspend or revoke a volume deliberately, and confirm you have an alternative unlock path (for example, a recovery key for BitLocker) before you do.
Enrolling a volume
Create the app and register the volume
Choose the engine (luks, cryhod or bitlocker), give the volume a name, and optionally record the host id, host OS and the on-host volume reference (device path or drive letter).
Enroll the volume
DuoKey creates the RSA KEK in the linked vault and returns an enrollment bundle: the DuoKey provider's endpoint for this volume, the on-host library/config paths, and an ordered list of host-side setup steps for the chosen engine.
Run the host-side steps
Follow the generated steps on the host — installing the DuoKey provider, then binding it into the engine (a LUKS keyslot, a Cryhod device selection, or a BitLocker key protector).
Verify unlock
Confirm the volume unlocks through the provider before removing any interim/local unlock method, then check the volume's status to confirm its KEK is bound and the vault is reachable.
LUKS setup
| Step | What it does |
|---|---|
| Install the DuoKey PKCS#11 provider | Copies the provider library onto the host and writes its configuration (server URL and access token). |
| Enroll the vault-held KEK into a LUKS keyslot | Binds a new keyslot to the RSA KEK exposed by the provider, so the volume key becomes wrapped to the vault. |
| Register the token in the crypttab | Adds a PKCS#11 token URI entry so the volume unlocks automatically at boot through the vault-held KEK. |
| Verify unlock | Confirms the disk-encryption tooling can open the volume via the provider alone. |
The host never stores the KEK; systemd-cryptenroll and cryptsetup reach it through the DuoKey PKCS#11 provider at every unlock.
Cryhod setup
| Step | What it does |
|---|---|
| Install the DuoKey PKCS#11 provider (Windows) | Registers the provider and writes its configuration so Cryhod's encryption centre can enumerate the KEK. |
| Select the PKCS#11 device in the encryption centre | Choose the 'key stored in a smart card or USB device (PKCS#11)' option and select the KEK by its configured tag. |
BitLocker setup
| Step | What it does |
|---|---|
| Expose the vault KEK as a CNG-KSP certificate | Installs the DuoKey Key Storage Provider and enrolls a smart-card certificate whose private key is the vault-held KEK. |
| Add the certificate as a key protector | Binds the volume's encryption key to the vault-held KEK via a certificate-based BitLocker key protector. |
Rotating a volume's key
Rotating a volume creates a new KEK (optionally at a different RSA strength or in a different vault) and re-binds the volume to it, returning a fresh enrollment bundle. The previous KEK is not reused after rotation; re-run the relevant host-side enrollment step so the engine picks up the new key.
BitLocker recovery-key escrow and recovery
BitLocker volumes generate their own recovery protectors (a numerical recovery password, an external key file, or both) independently of the certificate-based key protector DuoKey enrolls. Losing access to both the vault-backed unlock path and a locally stored recovery key would leave a machine permanently locked, so Disk Encryption adds a dedicated, centralized escrow flow for these recovery protectors: instead of relying on a spreadsheet or a local printout, the recovery secret itself is wrapped with the volume's own vault-held KEK and stored centrally.
Escrow, listing and recovery of protectors apply to BitLocker volumes. LUKS and Cryhod volumes do not use this flow.
The recovery secret is wrapped by the same vault-held KEK as the primary unlock path, and every disclosure is recorded in the audit trail.
Escrowing a recovery key
Generate the recovery protector on the host
Add a recovery protector to the volume using standard BitLocker tooling (a numerical recovery password, an external key, or both). This must happen after the volume's KEK has been enrolled.
Submit it for escrow
Send the recovery secret, its type (recovery_password, external_key, or numerical_password), an optional protector id/label, to DuoKey. The secret is encrypted with the volume's vault-held KEK before it is stored — DuoKey never persists it in the clear.
Confirm escrow
The escrowed protector then appears in the volume's protector list, identified by its type and label; the wrapped secret itself is never returned by the listing.
Recovering a locked machine
Identify the locked volume and protector
Find the volume and the specific escrowed protector to use (a machine may have more than one escrowed protector over its lifetime).
Recover the secret
An operator with the appropriate permission requests recovery. DuoKey unwraps the protector's secret using the volume's vault-held KEK and returns it.
Unlock the machine
Enter the recovered recovery password (or supply the recovered external key) at the BitLocker recovery prompt to unlock the machine.
Recovering (disclosing) an escrowed protector is treated as a sensitive operation: it is recorded in the audit trail and activity feed against the requesting user, and the protector's last-recovered timestamp is updated. Restrict the permission to unwrap recovery protectors to operators who are authorized to handle disk recovery.
Prerequisites
المتطلبات المسبقة
- A DuoKey vault to hold the volume KEK (the tenant default software vault is used automatically if none is chosen)
- Administrative access on the host to install the DuoKey provider (PKCS#11 or CNG-KSP)
- For LUKS: a Linux host with cryptsetup / systemd-cryptenroll support
- For Cryhod: Prim'X Cryhod already deployed on the Windows host
- For BitLocker: BitLocker already enabled or ready to enable on the Windows host
Each volume exposes a status check that reports its enrollment state and whether the vault holding its KEK is currently reachable — use it before relying on a newly enrolled volume in production.