| layout | default |
|---|---|
| title | Security Architecture |
Technical deep dive into the security design and implementation of the Device Fingerprinting Library.
The library follows industry-standard security principles:
Multiple layers of protection ensure that no single vulnerability compromises the system:
┌─────────────────────────────────────────┐
│ Application Layer │
│ (Input validation, access control) │
├─────────────────────────────────────────┤
│ Cryptographic Layer │
│ (Encryption, signing, hashing) │
├─────────────────────────────────────────┤
│ Storage Layer │
│ (Secure key storage, disk encryption) │
├─────────────────────────────────────────┤
│ Hardware Layer │
│ (TPM, secure enclave, trusted modules)│
└─────────────────────────────────────────┘
- Functions only access data they need
- Users receive minimum required permissions
- Default configurations are restrictive
- Explicit opt-in for advanced features
- Errors default to secure state
- Ambiguous situations are treated as failures
- No sensitive data leaks on error
- Detailed errors logged only internally
- Algorithm choices are modular and swappable
- Easy migration to stronger algorithms
- Support for both current and post-quantum crypto
- Version tracking for forward compatibility
Purpose: Generate unique fingerprints from hardware data
Specification:
- Algorithm: SHA-3-256 (Keccak-256)
- Output: 256 bits (32 bytes)
- Collision resistance: 2^128
- Preimage resistance: 2^256
Usage:
from cryptography.hazmat.primitives import hashes
# Generate fingerprint hash
hasher = hashes.Hash(hashes.SHA3_256())
hasher.update(hardware_data)
fingerprint = hasher.finalize()Security Properties:
- Deterministic: Same input always produces same output
- Non-reversible: Cannot recover input from hash
- Avalanche effect: Small input change dramatically changes output
- No known collision attacks
Purpose: Encrypt sensitive data at rest
Specification:
- Algorithm: AES (Advanced Encryption Standard)
- Key size: 256 bits (32 bytes)
- Mode: GCM (Galois/Counter Mode)
- Nonce size: 96 bits (12 bytes)
- Authentication tag: 128 bits (16 bytes)
Usage:
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import os
# Generate random key and nonce
key = AESGCM.generate_key(bit_length=256)
nonce = os.urandom(12)
# Encrypt data
cipher = AESGCM(key)
ciphertext = cipher.encrypt(nonce, plaintext, associated_data=b"aad")
# Decrypt data (authentication tag verified automatically)
plaintext = cipher.decrypt(nonce, ciphertext, associated_data=b"aad")Security Properties:
- Authenticated encryption prevents tampering
- Nonce prevents replay attacks
- GCM mode is efficient and hardware-accelerated
- 256-bit key provides protection against quantum computers (in theory)
Purpose: Convert passwords to cryptographic keys
Specification:
- Algorithm: Scrypt
- CPU cost (N): 32,768
- Block size (r): 8
- Parallelization (p): 1
- Output: 256 bits (32 bytes)
- Salt: 256 bits (32 bytes)
Security Parameters:
| Scenario | N | r | p | Time |
|---|---|---|---|---|
| Interactive | 16,384 | 8 | 1 | ~100ms |
| Sensitive | 32,768 | 8 | 1 | ~250ms |
| Paranoid | 65,536 | 8 | 1 | ~500ms |
Usage:
from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
import os
salt = os.urandom(32)
kdf = Scrypt(
salt=salt,
length=32,
n=32768,
r=8,
p=1
)
key = kdf.derive(password)Security Properties:
- Memory-hard: Resistant to GPU/ASIC attacks
- Time-hard: Computational cost cannot be reduced
- Salt prevents rainbow table attacks
- Parameters are conservative and adjustable
User Data
│
├─→ Validate input
│
├─→ Derive encryption key from password
│ (using Scrypt)
│
├─→ Generate random nonce
│
├─→ Encrypt with AES-256-GCM
│ (includes authentication)
│
├─→ Store: [nonce | ciphertext | auth_tag]
│
└─→ Write to disk or OS keyring
Stored Data [nonce | ciphertext | auth_tag]
│
├─→ Read from secure location
│
├─→ Derive encryption key from password
│ (using same Scrypt parameters)
│
├─→ Extract components: nonce, ciphertext, auth_tag
│
├─→ Decrypt with AES-256-GCM
│ (verifies authentication tag)
│
├─→ Validate decrypted data
│
└─→ Return plaintext (or error if tampering detected)
- Usage: Temporary data, session storage
- Security: Cleared on application exit
- Performance: Fastest
- Persistence: None
- Windows: Credential Manager
- macOS: Keychain
- Linux: Secret Service / KWallet
- Security: OS-level protection
- Performance: Fast
- Persistence: Permanent
- Location:
.config/device-fingerprinting/ - Encryption: AES-256-GCM
- Security: Full encryption at application level
- Performance: Moderate
- Persistence: Permanent
TPM provides hardware-based security:
Application
│
├─→ TPM_CC_CreatePrimary
│ (Create master key in TPM)
│
├─→ TPM_CC_Create
│ (Create derived keys)
│
├─→ TPM_CC_Sign
│ (Hardware-backed signatures)
│
└─→ TPM_CC_Seal
(Seal data to platform state)
Hardware Information
│
├─→ Extend into TPM PCR
│ (Platform Configuration Register)
│
├─→ Use TPM-sealed key for HMAC
│
└─→ Generate TPM-backed fingerprint
Device State
│
├─→ Collect measurements
│
├─→ Sign with TPM attestation key
│
├─→ Create attestation certificate
│
└─→ Verify via TPM quote
System Metrics Collection
│
├─→ CPU usage
├─→ Memory patterns
├─→ Disk I/O
├─→ Network activity
└─→ Process behavior
│
▼
Feature Normalization
│
├─→ Z-score normalization
└─→ Min-max scaling
│
▼
Isolation Forest Algorithm
│
├─→ Build random forest
├─→ Calculate anomaly score
└─→ Path length analysis
│
▼
Anomaly Score (0-1)
│
└─→ <0.3: Normal
0.3-0.7: Suspicious
>0.7: Anomaly
- No Model Leakage: Models are not stored (recreated each run)
- No Sensitive Data: Only statistical metrics used
- Deterministic: Same metrics always produce same results
- Local Only: No data sent to external services
- Explainable: Can identify contributing metrics
- What: Device hardware identifiers
- Risk: Device tracking, privacy concerns
- Protection: Can be encrypted, anonymized in transit
- Disclosure Impact: Device can be identified
- Handling: Treat as sensitive PII
- What: AES, Scrypt, TPM keys
- Risk: Complete data compromise if leaked
- Protection: Stored in OS keyring or TPM
- Disclosure Impact: Complete break of security
- Handling: Never log, never transmit, clear from memory
- What: CPU, memory, disk usage
- Risk: System profiling, activity detection
- Protection: Only used locally
- Disclosure Impact: Inferential
- Handling: Can be transmitted for analysis
- What: User-provided passwords
- Risk: Key derivation compromise
- Protection: Only held in memory temporarily
- Disclosure Impact: Complete key compromise
- Handling: Never logged, never stored, cleared immediately
Threat: Attacker generates same fingerprint on different hardware
Mitigation:
- Hardware-based fingerprints use immutable properties
- TPM provides hardware attestation
- Multiple fingerprint methods for verification
- Device binding prevents reuse
Threat: Attacker reuses captured fingerprint data
Mitigation:
- Fingerprints include timestamps
- Nonce in encryption prevents replay
- GCM mode provides authentication
- Session-based verification
Threat: Attacker extracts encryption keys
Mitigation:
- Keys never logged or transmitted
- Stored in OS keyring or TPM
- Scrypt parameters prevent brute force
- Memory cleared after use
Threat: Timing, power consumption leaks information
Mitigation:
- Uses cryptography library's constant-time operations
- Python abstracts hardware details
- No custom crypto implementations
- Depends on system-level protections
Threat: Malware accesses stored fingerprints
Mitigation:
- Data encrypted at application level
- TPM provides additional isolation
- OS keyring provides namespace isolation
- Regular security updates recommended
- FIPS 197: AES encryption algorithm
- FIPS 202: SHA-3 hashing algorithm
- NIST SP 800-132: Scrypt key derivation
- NIST SP 800-38D: GCM mode specification
- OWASP Top 10: Addressed in design
- CWE/SANS Top 25: Mitigated vulnerabilities
- NIST Cybersecurity Framework: Alignment
- ISO 27001: Information security management
- GDPR: Privacy-by-design principles
- CCPA: Data minimization
- HIPAA: Encryption requirements
- PCI DSS: Secure data handling
# DON'T: Hardcode keys
KEY = "hardcoded_secret_key"
# DO: Use environment variables
import os
KEY = os.environ.get('ENCRYPTION_KEY')
# DO: Use OS keyring
from keyring import get_password
KEY = get_password("app_name", "encryption_key")# DON'T: Log sensitive data
logger.error(f"Fingerprint: {fingerprint}, Key: {key}")
# DO: Log only sanitized information
logger.error(f"Failed to retrieve device fingerprint")# Regularly update the library
pip install --upgrade device-fingerprinting-pro
# Check for security advisories
pip audit # or pip-audit if available# DON'T: Store credentials in code
generator = DeviceFingerprintGenerator(password="user123")
# DO: Use configuration files with restricted permissions
# config.ini with 0600 permissions
# Then load:
import configparser
config = configparser.ConfigParser()
config.read('config.ini')
password = config.get('security', 'password')If you discover a security vulnerability:
-
Do not: Post in public issues or discussions
-
Do: Email security@example.com with:
- Vulnerability description
- Steps to reproduce
- Potential impact
- Suggested fix (if available)
-
Timeline: 90-day responsible disclosure period
See SECURITY.md for complete policy.
- AES-256-GCM encryption
- Scrypt key derivation
- TPM 2.0 support
- ML-based anomaly detection
- Kyber post-quantum key encapsulation
- Hardware security token support
- Enhanced audit logging
- Security event correlation
- Dilithium post-quantum signatures
- Confidential computing support
- Zero-knowledge proofs
- Distributed trust mechanisms
- NIST Cryptographic Standards
- Python Cryptography Documentation
- OWASP Security Guidelines
- TPM 2.0 Specification
- CWE Database
For security-related questions or concerns, please contact the security team or review SECURITY.md.