This guide explains the security implications, threat model, and best practices for AutoDecrypt.

AutoDecrypt implements a layered security approach that balances convenience with protection:

• Hardware Security: TPM2 chip provides hardware-based key storage
• Boot Integrity: PCR binding detects unauthorized system modifications
• Fallback Protection: Original LUKS passphrases remain valid
• Transparent Operation: No changes to existing LUKS setup

✅ Software-based attacks

• Malware cannot extract keys from TPM2
• Keys are sealed to hardware state

✅ Boot tampering detection

• PCR binding detects bootloader modifications
• BIOS/UEFI changes invalidate automatic unlock

✅ Remote attacks

• Keys never leave the TPM2 chip
• No network communication required

✅ Drive theft (powered off)

• Full disk encryption remains intact
• TPM2 keys tied to specific hardware

⚠️ Physical access attacks

• Physical access to running system
• Hardware tampering with TPM2 chip
• Cold boot attacks on RAM

⚠️ Authorized user attacks

• Root access bypasses encryption
• Physical keyboard access during boot

⚠️ Advanced persistent threats

• Sophisticated hardware implants
• TPM2 chip replacement attacks

• Hardware-based: Keys stored in tamper-resistant TPM2 chip
• Non-extractable: Keys cannot be read directly from TPM2
• Hardware-bound: Keys tied to specific TPM2 instance

# Keys are "sealed" to system state
# Only released when conditions match:
# 1. Same TPM2 chip
# 2. Same PCR values (if PCR binding used)
# 3. Valid authentication

• SHA256: Preferred for maximum security
• SHA1: Fallback for older systems
• Algorithm detection: Automatic selection of best available

• Boot state verification: Detects unauthorized changes
• Tamper resistance: Invalid PCR values prevent unlock
• Integrity checking: Validates system boot path

# PCR 7 contains Secure Boot policy measurements
# Changes when:
# - BIOS/UEFI updated
# - Secure Boot settings modified
# - Boot path altered

sudo tpm2_pcrread sha256:7  # Check current value

With PCR Binding (More Secure):

• Detects boot tampering
• Requires reconfiguration after BIOS updates
• May fail with some hardware configurations

Without PCR Binding (More Compatible):

• Works across BIOS updates
• Less tampering detection
• Better hardware compatibility

AutoDecrypt uses additional LUKS keyslots without affecting existing ones:

# Example keyslot layout:
# Slot 0: Original user passphrase
# Slot 1: TPM2 binding (AutoDecrypt)
# Slots 2-7: Available for other uses

• Original LUKS passphrases remain unchanged
• Manual unlock always possible as fallback
• No reduction in existing security

# PCR 7 binding with SHA256
sudo clevis luks bind -d /dev/sda2 tpm2 '{
  "pcr_ids": "7",
  "hash": "sha256",
  "pcr_bank": "sha256"
}'

Benefits:

• Strongest tamper detection
• Hardware state verification
• Secure Boot integration

Considerations:

• Requires reconfiguration after BIOS updates
• May not work with all hardware
• More complex troubleshooting

# SHA256 without PCR binding
sudo clevis luks bind -d /dev/sda2 tpm2 '{
  "hash": "sha256"
}'

Benefits:

• Strong encryption
• Hardware key protection
• Better compatibility

Considerations:

• No boot tamper detection
• Survives BIOS updates
• Simpler maintenance

# Default settings (usually SHA1)
sudo clevis luks bind -d /dev/sda2 tpm2 '{}'

Benefits:

• Maximum hardware compatibility
• Simple configuration
• Reliable operation

Considerations:

• Weaker hash algorithm
• No tamper detection
• Minimum security level

1. Enable Secure Boot (if supported):

   # Check Secure Boot status
   bootctl status | grep "Secure Boot"
   
   # Enable in BIOS/UEFI if available

2. Use strong LUKS passphrases:

   # Add strong backup passphrase
   sudo cryptsetup luksAddKey /dev/sda2

3. Document configuration:

   # Save configuration details
   sudo clevis luks list -d /dev/sda2 > security-config.txt

# Monthly security check
./autodecrypt.sh test

# Check for PCR changes
sudo tpm2_pcrread sha256:7

# Verify keyslot integrity
sudo cryptsetup luksDump /dev/sda2

# Before BIOS updates (if using PCR binding):
./autodecrypt.sh test > pre-update-status.txt

# After BIOS updates:
./autodecrypt.sh test  # Will likely fail
./autodecrypt.sh install  # Reconfigure with new PCR values

1. LUKS header backup:

   sudo cryptsetup luksHeaderBackup /dev/sda2 --header-backup-file luks-header-backup.img

2. Configuration documentation:

   # Document TPM2 settings
   sudo tpm2_getcap properties-fixed > tpm2-properties.txt
   sudo clevis luks list -d /dev/sda2 > clevis-bindings.txt

3. Recovery preparation:

   # Ensure you have LUKS passphrases available
   # Test manual unlock capability
   # Prepare recovery media with LUKS tools

1. Secure physical access to systems using AutoDecrypt
2. Monitor for hardware tampering indicators
3. Use chassis intrusion detection if available
4. Implement screen locks for running systems

# Check TPM2 ownership
sudo tpm2_getcap properties-fixed | grep TPM2_PT_OWNER

# Verify TPM2 is not clearable by software
sudo tpm2_getcap properties-fixed | grep TPM2_PT_LOCKOUT_COUNTER

• Home desktop/laptop with physical security
• Development systems with non-sensitive data
• Systems with strong physical access controls

Recommended Configuration:

# Balanced security with PCR binding
./autodecrypt.sh install  # Uses automatic configuration

• Workplace laptops that travel
• Servers in shared environments
• Systems with occasional physical access by others

Recommended Configuration:

# Maximum security with monitoring
./autodecrypt.sh install
# Plus regular monitoring and update procedures

• Systems with sensitive data
• Environments with insider threats
• Systems in physically insecure locations

Additional Measures:

# Consider additional layers:
# - Network-based key escrow
# - Multi-factor authentication
# - Hardware security keys
# - Full system monitoring

1. Physical access: Cannot protect against physical attacks
2. Root compromise: Root access bypasses all protections
3. TPM2 vulnerabilities: Depends on TPM2 implementation security
4. Boot process: Vulnerable during unencrypted boot phase

# Defense in depth:
# 1. Physical security measures
# 2. Access control and monitoring
# 3. Network security
# 4. Regular security updates
# 5. Incident response planning

❌ Maximum security environments

• Where physical security cannot be guaranteed
• Systems handling classified information
• Environments with sophisticated adversaries

❌ Compliance requirements

• Regulations requiring manual authentication
• Standards prohibiting automatic decryption
• Audit requirements for human verification

❌ Shared systems

• Multi-user systems without individual TPM2 instances
• Systems where multiple users need access
• Environments without clear ownership

• GDPR: Consider data protection implications
• HIPAA: May require additional controls for healthcare data
• SOX: Financial data may need enhanced protections
• PCI DSS: Credit card data has specific encryption requirements

# Maintain security documentation:
# 1. Risk assessment results
# 2. Configuration decisions and rationale
# 3. Regular testing and monitoring procedures
# 4. Incident response procedures

If using network boot with AutoDecrypt:

# Consider additional protections:
# - Secure network protocols (TLS/IPSec)
# - Network access controls
# - Boot image integrity verification

For virtualized environments:

# VM-specific considerations:
# - Virtual TPM2 security model
# - Hypervisor trust boundaries
# - VM migration implications

AutoDecrypt with containerized workloads:

# Container considerations:
# - Host system encryption
# - Container runtime security
# - Secret management integration

#!/bin/bash
# security-test.sh - Regular security validation

echo "=== AutoDecrypt Security Test ==="

# Test basic functionality
./autodecrypt.sh test

# Verify TPM2 security
sudo tpm2_getcap properties-fixed | grep -E "(OWNER|LOCKOUT)"

# Check PCR integrity
sudo tpm2_pcrread sha256:7

# Validate keyslot usage
sudo cryptsetup luksDump /dev/sda2 | grep -A5 "Key Slot"

echo "Security test completed at $(date)"

When conducting security assessments:

1. Test boot process security
2. Evaluate physical access controls
3. Assess TPM2 configuration
4. Validate recovery procedures
5. Review logging and monitoring

This security guide provides a foundation for secure AutoDecrypt deployment. For specific compliance or high-security environments, consult with security professionals familiar with your requirements.