From f0cadbbe6ec0d9e3ed3a9776247ce3ad4ae59bd3 Mon Sep 17 00:00:00 2001 From: Dimitris Karakasilis Date: Thu, 25 Sep 2025 15:24:12 +0300 Subject: [PATCH] Explain the various scenarios Signed-off-by: Dimitris Karakasilis --- README.md | 172 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 169 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2b60058..40416d2 100644 --- a/README.md +++ b/README.md @@ -138,9 +138,17 @@ Implement a "selective enrollment mode" with two distinct behaviors: - Enables full security verification for subsequent attestations #### **Selective Re-enrollment** (SealedVolume exists with specific fields) -- **Empty values** (`""`) = Accept any value, update the stored value -- **Set values** (`"abc123..."`) = Enforce exact match -- **Omitted fields** = Skip verification entirely (allows flexibility) +- **Empty values** (`""`) = Accept any value, update the stored value (re-enrollment mode) +- **Set values** (`"abc123..."`) = Enforce exact match (enforcement mode) +- **Omitted fields** = Skip verification entirely (ignored mode) + +**Selective Enrollment Behavior Summary:** + +| Field State | Verification | Updates | Use Case | +|-------------|-------------|---------|----------| +| **Empty** (`""`) | ✅ Accept any value | ✅ Update with current | Re-learn after TPM/firmware changes | +| **Set** (`"abc123"`) | ✅ Enforce exact match | ❌ No updates | Strict security enforcement | +| **Omitted** (deleted) | ❌ Skip entirely | ❌ Never re-enrolled | Ignore volatile PCRs (e.g., PCR 11) | ### Required Implementation Changes @@ -203,6 +211,135 @@ spec: 6. **Flexible Boot Stages**: Omit PCR 11 entirely so users can decrypt during boot AND after full system startup 7. **Kernel Updates**: Omit PCR 11 to avoid quarantine on routine Kairos upgrades +### Practical Operator Workflows + +#### **Scenario 1: Reusing Existing Passphrases After SealedVolume Recreation** + +**Problem**: An operator needs to recreate a SealedVolume (e.g., after accidental deletion or configuration changes) but wants to keep using the existing passphrase to avoid re-encrypting the disk. + +**Solution**: The system automatically reuses existing Kubernetes secrets when available: + +```bash +# 1. Operator accidentally deletes SealedVolume +kubectl delete sealedvolume my-encrypted-volume + +# 2. Original secret still exists in cluster +kubectl get secret my-encrypted-volume-encrypted-data +# NAME TYPE DATA AGE +# my-encrypted-volume-encrypted-data Opaque 1 5d + +# 3. When TPM client reconnects, system detects existing secret +# and reuses the passphrase instead of generating a new one +``` + +**Behavior**: The system will: +- Detect the existing secret with the same name +- Log: "Secret already exists, reusing existing secret" +- Use the existing passphrase for decryption +- Recreate the SealedVolume with current TPM attestation data +- Maintain continuity without requiring disk re-encryption + +#### **Scenario 2: Deliberately Skipping PCRs After Initial Enrollment** + +**Problem**: An operator initially enrolls with PCRs 0, 7, and 11, but later realizes PCR 11 changes frequently due to kernel updates and wants to ignore it permanently. + +**Solution**: Remove the PCR from the SealedVolume specification: + +```bash +# 1. Initial enrollment created SealedVolume with: +# pcrValues: +# pcrs: +# "0": "abc123..." +# "7": "def456..." +# "11": "ghi789..." + +# 2. Operator edits SealedVolume to remove PCR 11 entirely +kubectl edit sealedvolume my-encrypted-volume +# Remove the "11": "ghi789..." line completely + +# 3. Result - omitted PCR 11: +# pcrValues: +# pcrs: +# "0": "abc123..." +# "7": "def456..." +# # PCR 11 omitted = ignored entirely +``` + +**Behavior**: The system will: +- Skip PCR 11 verification entirely (no enforcement) +- Never re-enroll PCR 11 in future attestations +- Log: "PCR verification successful using selective enrollment" (without mentioning PCR 11) +- Continue enforcing PCRs 0 and 7 normally + +#### **Scenario 3: Manual PCR Selection During Initial Setup** + +**Problem**: An operator knows certain PCRs will be unstable and wants to exclude them from the beginning. + +**Solution**: Create the initial SealedVolume manually with only desired PCRs: + +```yaml +# Create SealedVolume with selective PCR enforcement from the start +apiVersion: keyserver.kairos.io/v1alpha1 +kind: SealedVolume +metadata: + name: selective-pcr-volume +spec: + TPMHash: "known-tpm-hash" + partitions: + - label: "encrypted-data" + secret: + name: "my-passphrase" + path: "passphrase" + attestation: + ekPublicKey: "" # Re-enrollment mode + akPublicKey: "" # Re-enrollment mode + pcrValues: + pcrs: + "0": "" # Re-enrollment mode (will learn) + "7": "" # Re-enrollment mode (will learn) + # "11": omitted # Skip PCR 11 entirely +``` + +**Behavior**: The system will: +- Learn and enforce PCRs 0 and 7 on first attestation +- Completely ignore PCR 11 (never verify, never store) +- Allow flexible boot stages without PCR 11 interference + +#### **Scenario 4: Kernel Upgrade - Temporary PCR Re-enrollment** + +**Problem**: An operator is performing a kernel upgrade and knows PCR 11 will change, but wants to continue enforcing it after the upgrade (unlike permanent omission). + +**Solution**: Set the PCR value to empty string to trigger re-enrollment mode: + +```bash +# 1. Before kernel upgrade - PCR 11 is currently enforced +kubectl get sealedvolume my-volume -o jsonpath='{.spec.attestation.pcrValues.pcrs.11}' +# Output: "abc123def456..." (current PCR 11 value) + +# 2. Set PCR 11 to empty string to allow re-enrollment +kubectl patch sealedvolume my-volume --type='merge' \ + -p='{"spec":{"attestation":{"pcrValues":{"pcrs":{"11":""}}}}}' + +# 3. Perform kernel upgrade and reboot + +# 4. After reboot, TPM client reconnects and system learns new PCR 11 value +# Log will show: "Updated PCR value during selective enrollment, pcr: 11" + +# 5. Verify new PCR 11 value is now enforced +kubectl get sealedvolume my-volume -o jsonpath='{.spec.attestation.pcrValues.pcrs.11}' +# Output: "new789xyz012..." (new PCR 11 value after kernel upgrade) +``` + +**Behavior**: The system will: +- Accept any PCR 11 value on next attestation (re-enrollment mode) +- Update the stored PCR 11 with the new post-upgrade value +- Resume strict PCR 11 enforcement with the new value +- Log: "Updated PCR value during selective enrollment" + +**Key Difference from Scenario 2:** +- **Scenario 2 (Omit PCR)**: PCR 11 permanently ignored, never verified again +- **Scenario 4 (Empty PCR)**: PCR 11 temporarily re-enrolled, then enforced with new value + ### Critical Implementation Notes - **TPM Hash MUST remain mandatory** - without it, multiple clients would match the same SealedVolume @@ -211,5 +348,34 @@ spec: - **Consider rate limiting** to prevent abuse of enrollment mode - **Update documentation** with operational procedures for each use case +### Quick Reference for Documentation + +**Common Operations:** + +```bash +# Skip a PCR permanently (never verify again) +kubectl edit sealedvolume my-volume +# Remove the PCR line entirely from pcrValues.pcrs + +# Temporarily allow PCR re-enrollment (e.g., before kernel upgrade) +kubectl patch sealedvolume my-volume --type='merge' -p='{"spec":{"attestation":{"pcrValues":{"pcrs":{"11":""}}}}}' + +# Re-learn a PCR after hardware change (e.g., PCR 0 after BIOS update) +kubectl patch sealedvolume my-volume --type='merge' -p='{"spec":{"attestation":{"pcrValues":{"pcrs":{"0":""}}}}}' + +# Re-learn AK after TPM replacement +kubectl patch sealedvolume my-volume --type='merge' -p='{"spec":{"attestation":{"akPublicKey":""}}}' + +# Check current PCR enforcement status +kubectl get sealedvolume my-volume -o jsonpath='{.spec.attestation.pcrValues.pcrs}' | jq . +``` + +**Log Messages to Expect:** + +- `"Secret already exists, reusing existing secret"` - Passphrase reuse scenario +- `"Updated PCR value during selective enrollment"` - Re-enrollment mode active +- `"PCR verification successful using selective enrollment"` - Omitted PCRs ignored +- `"PCR enforcement mode verification passed"` - Strict enforcement active + ### Priority: High This blocks current test failures and addresses fundamental operational challenges for production deployments.