# Test Panocrypt unlock on a temporary LUKS volume

Use this path when you want to understand Panocrypt without touching a real
server disk. You create a disposable file-backed LUKS volume, bind one LUKS
keyslot to Panocrypt through the standard Clevis `tang` pin, then test allowed
and denied managed unlock.

## Why this path is low risk

This path uses your distribution's LUKS and Clevis packages only. You do not
install Panocrypt software on the host. The host talks to the Panocrypt device
URL through the same Linux primitives an existing encrypted volume would use.
Read [No custody of disk keys](https://docs.panocrypt.com/trust/non-escrow/) first if you want to see why
this proof does not give Panocrypt custody of the disk key.

Read [LUKS keyslots](https://docs.panocrypt.com/concepts/luks-keyslots/) if you want to understand why
this proof binds one removable keyslot while your local recovery material
stays separate.

## What this proves

- A LUKS keyslot can bind to a Panocrypt device URL through the standard Clevis
  `tang` pin.
- Panocrypt can allow or deny future network-bound unlock based on device
  policy.
- Manual approval can be tested without risking a boot disk when your org uses
  manual approval for unlocks.
- The console can show device state and unlock decision evidence.
- Panocrypt-managed unlock can be tested with zero Panocrypt host software.

## What this does not prove

- Root-disk boot unlock.
- Initramfs networking.
- Initramfs CA certificate trust.
- Panocrypt-assisted setup of a provider image.

## Before you start

You need:

- A Linux host where you can run `sudo`.
- `cryptsetup`, `clevis`, and `clevis-luks` from your distribution.
- A Panocrypt org with permission to register devices.
- Customer-controlled recovery material for the temporary volume.

On Ubuntu-family systems, the package install usually looks like this:

```sh
sudo apt-get update
sudo apt-get install -y cryptsetup clevis clevis-luks
```

## Temporary-volume test path

1. [Create a temporary file-backed block device](#create-the-temporary-volume).
2. [Format it as a LUKS volume](#create-the-temporary-volume) with
   customer-controlled recovery material.
3. Add a small test file so you can prove the same encrypted volume
   reopened.
4. [Register a Panocrypt device](#register-the-panocrypt-device).
5. [Bind an unused LUKS keyslot](#bind-a-luks-keyslot-to-panocrypt) with the
   standard Clevis `tang` pin and the Panocrypt device URL.
6. [Close the volume and reopen it](#prove-allowed-unlock) through
   Clevis/Panocrypt.
7. [Disable managed unlock](#prove-denied-unlock) and confirm future
   Panocrypt-managed unlock is denied.
8. Optionally [try manual approval](#try-manual-approval).
9. [Clean up](#clean-up) the temporary volume.

## Create the temporary volume

This creates a 128 MiB file-backed block device, formats it as LUKS2, mounts
it, and writes a test file.

```sh
export WORKDIR="$(mktemp -d)"
export IMG="$WORKDIR/panocrypt-test-luks.img"
export RECOVERY_KEY="$WORKDIR/recovery.key"
export MAPPER="panocrypt-test"
export MNT="$WORKDIR/mnt"

openssl rand -base64 32 > "$RECOVERY_KEY"
chmod 0600 "$RECOVERY_KEY"

truncate -s 128M "$IMG"
export LOOP="$(sudo losetup --find --show "$IMG")"

sudo cryptsetup luksFormat --type luks2 --batch-mode \
  --key-file "$RECOVERY_KEY" "$LOOP"
sudo cryptsetup open --key-file "$RECOVERY_KEY" "$LOOP" "$MAPPER"
sudo mkfs.ext4 -q "/dev/mapper/$MAPPER"

mkdir -p "$MNT"
sudo mount "/dev/mapper/$MAPPER" "$MNT"
echo "panocrypt temporary LUKS volume proof" | sudo tee "$MNT/sentinel.txt"
sync
```

Keep `$RECOVERY_KEY` until the test is finished. It is the local recovery
material for this temporary volume.

## Register the Panocrypt device

In the Panocrypt console:

1. Open your org.
2. Go to **Maintain** -> **Devices**.
3. Select **Add first device** or **Add device**.
4. Name the device, for example `temporary-luks-proof`.
5. In **Policy**, choose the source policy you want to prove first.
6. Finish the flow and copy the **Existing LUKS** device URL.

For the first run, allow the current host source IP so the Clevis bind and
unlock can reach Panocrypt. You can narrow or remove that access later to prove
denied unlock.

Set the copied URL:

```sh
export PANOCRYPT_DEVICE_URL="https://tango.panocrypt.com/YOUR_ORG/YOUR_DEVICE"
```

## Bind a LUKS keyslot to Panocrypt

Bind an unused LUKS keyslot through the standard Clevis `tang` pin.

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

Confirm the Clevis token exists:

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

## Prove allowed unlock

Close the volume and reopen it through Clevis/Panocrypt.

```sh
sudo umount "$MNT"
sudo cryptsetup close "$MAPPER"

sudo clevis luks unlock -d "$LOOP" -n "$MAPPER"
sudo mount "/dev/mapper/$MAPPER" "$MNT"
sudo cat "$MNT/sentinel.txt"
```

Expected result:

```text
panocrypt temporary LUKS volume proof
```

In Panocrypt, review the device activity. You should see evidence for the
managed unlock request and its decision.

The same managed unlock controls apply to this temporary volume and to later
real devices. Use
[Source IP and one-time unlocks](https://docs.panocrypt.com/operations/source-ip-and-one-time-unlocks/)
for source allowlists and **Allow once**. Use
[Disable unlocks](https://docs.panocrypt.com/operations/disable-unlocks/) and
[Approval groups](https://docs.panocrypt.com/operations/approval-groups/) for those controls.

## Prove denied unlock

In the Panocrypt console, open the device and disable managed unlock. You can
also remove the host from **Direct Allowed IPs** or apply a source policy that
does not include the host.

Then close the volume and try the same managed unlock again.

```sh
sudo umount "$MNT" 2>/dev/null || true
sudo cryptsetup close "$MAPPER" 2>/dev/null || true

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

This proves Panocrypt can deny a future network-bound unlock. It does not lock
a running host, remove keys from memory, modify the LUKS header remotely, or
delete your local recovery material.

## Try manual approval

If your org uses manual approval for unlocks, require manual approval for this
device and retry the same Clevis unlock.

```sh
sudo cryptsetup close "$MAPPER" 2>/dev/null || true

deadline=$((SECONDS + 1800))
until sudo clevis luks unlock -d "$LOOP" -n "$MAPPER"; do
  if [ "$SECONDS" -gt "$deadline" ]; then
    echo "timed out waiting for manual approval"
    exit 1
  fi
  echo "waiting for approval; retrying..."
  sleep 5
done
```

In the console, go to **Maintain** -> **Manual unlock**, review the unlock
request, and approve or deny it. Approval lets the pending managed unlock
continue under the policy you configured.

For reusable manual approval rules, use
[Approval groups](https://docs.panocrypt.com/operations/approval-groups/). For phone or browser prompts,
register [Mobile notifications](https://docs.panocrypt.com/operations/mobile-notifications/) first.

## Clean up

When the test is done, unmount and remove the temporary resources.

```sh
sudo umount "$MNT" 2>/dev/null || true
sudo cryptsetup close "$MAPPER" 2>/dev/null || true
sudo losetup -d "$LOOP" 2>/dev/null || true
rm -rf "$WORKDIR"
```

In Panocrypt, either restore managed unlock if you want to keep testing, or
archive the device record when the test is complete.

If you want to practice removing the local binding instead of deleting the
temporary volume, use
[Remove Panocrypt from a LUKS device](https://docs.panocrypt.com/trust/remove-panocrypt-binding/) for the
`clevis luks unbind` flow.

## Proof result

You used only distro LUKS and Clevis packages on the host. Panocrypt published
the device URL, participated in the recovery exchange, allowed one managed
unlock, then denied a later managed unlock after policy changed. The sentinel
test file proved the same encrypted volume was closed and reopened.