Bind an existing LUKS volume to Panocrypt

Use this path when you already have a LUKS-encrypted data volume and want to test managed unlock on a real encrypted data volume without changing root-disk boot behavior.

What runs on the host

This path uses standard LUKS and Clevis packages from your distribution. No Panocrypt-specific host agent is required for the bind or unlock path. Read No custody of disk keys before binding a real volume. The local unlock key is created and wrapped on the machine, while Panocrypt only participates in the policy-approved recovery exchange. Read LUKS keyslots for the removable keyslot model before binding a real volume.

What this proves

• A real LUKS data volume can use Panocrypt for managed network-bound unlock.
• Panocrypt can allow or deny future managed unlock without owning your local recovery material.
• You can test Panocrypt controls without changing the host boot path.
• You can add Panocrypt-managed unlock without installing Panocrypt host software.

It does not prove unattended root-disk unlock during boot.

Before you start

You need:

• The LUKS block device path, for example /dev/disk/by-id/....
• Customer-controlled recovery material for the volume.
• cryptsetup, clevis, and clevis-luks installed from your distro.
• A Panocrypt device URL for this volume.
• A maintenance window if the volume is attached to an application.

Back up the LUKS header before changing keyslots:

sudo cryptsetup luksHeaderBackup /dev/disk/by-id/YOUR_VOLUME \
  --header-backup-file luks-header-backup.img

Volume bind path

1. Confirm recovery material and header backup.
2. Register a Panocrypt device and copy the Existing LUKS device URL.
3. Bind an unused keyslot to the Panocrypt device URL.
4. Close and reopen the volume through Clevis.
5. Test allowed, denied, and optional manual-approval unlock behavior.
6. Review unlock decision evidence in Panocrypt.

Bind the volume

Set the block-device path and Panocrypt URL explicitly. Prefer stable /dev/disk/by-id/... or /dev/disk/by-uuid/... paths over short names like /dev/sdb.

export LUKS_DEVICE="/dev/disk/by-id/YOUR_VOLUME"
export PANOCRYPT_DEVICE_URL="https://tango.panocrypt.com/YOUR_ORG/YOUR_DEVICE"
export RECOVERY_KEY="/path/to/customer-held-recovery-key"

export CLEVIS_CFG="$(printf '{"url":"%s"}' "$PANOCRYPT_DEVICE_URL")"
sudo clevis luks bind -y -k "$RECOVERY_KEY" -d "$LUKS_DEVICE" tang "$CLEVIS_CFG"

Confirm the token:

sudo clevis luks list -d "$LUKS_DEVICE"
sudo cryptsetup luksDump "$LUKS_DEVICE" | sed -n '/Keyslots:/,/Tokens:/p'

The Panocrypt binding uses one LUKS keyslot. Your customer-held recovery material should remain available through a separate local path.

Test managed unlock

Close the mapper only when it is safe for the application using this volume.

sudo umount /mount/point
sudo cryptsetup close YOUR_MAPPER_NAME
sudo clevis luks unlock -d "$LUKS_DEVICE" -n YOUR_MAPPER_NAME
sudo mount /dev/mapper/YOUR_MAPPER_NAME /mount/point

If the unlock succeeds, Panocrypt allowed that managed unlock under the current device policy. Review the device activity in the console.

To prove denied unlock, disable managed unlock for the device or remove the host from Direct Allowed IPs, close the mapper again, and retry:

if sudo clevis luks unlock -d "$LUKS_DEVICE" -n YOUR_MAPPER_NAME; then
  echo "unexpected: managed unlock succeeded"
  exit 1
else
  echo "expected: Panocrypt-managed unlock was denied"
fi

Use unlock controls

Use these operation pages for control tests after the volume is bound.

Task	Where
Disable or restore managed unlock	Disable unlocks
Allow a single future unlock	Source IP and one-time unlocks
Require approval before unlock	Approval groups
Review source policy	Source IP and one-time unlocks
Review evidence	Device detail -> Recent activity or Audit

Remove the binding

Removing Panocrypt from the local LUKS device means removing the Panocrypt-bound Clevis keyslot after you confirm another local recovery path works. The disk can stay encrypted, and independent recovery keyslots remain yours.

Use Remove Panocrypt from a LUKS device for the recovery checks, slot inspection, removal command, and verification steps.

Operating boundary

You bound a real LUKS volume to Panocrypt through standard Clevis tooling and verified that Panocrypt can allow or deny future managed unlock. The host still owns local LUKS recovery material and local keyslot management.