# 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](https://docs.panocrypt.com/trust/non-escrow/) 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](https://docs.panocrypt.com/concepts/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:

```sh
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](#before-you-start).
2. Register a Panocrypt device and copy the **Existing LUKS** device URL.
3. [Bind an unused keyslot](#bind-the-volume) to the Panocrypt device URL.
4. [Close and reopen the volume](#test-managed-unlock) 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`.

```sh
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:

```sh
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.

```sh
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:

```sh
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](https://docs.panocrypt.com/operations/disable-unlocks/) |
| Allow a single future unlock | [Source IP and one-time unlocks](https://docs.panocrypt.com/operations/source-ip-and-one-time-unlocks/) |
| Require approval before unlock | [Approval groups](https://docs.panocrypt.com/operations/approval-groups/) |
| Review source policy | [Source IP and one-time unlocks](https://docs.panocrypt.com/operations/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](https://docs.panocrypt.com/trust/remove-panocrypt-binding/)
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.