# PQC Dual USB Library
[](https://badge.fury.io/py/pqcdualusb)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://en.wikipedia.org/wiki/Post-quantum_cryptography)
A comprehensive **Python library** for post-quantum cryptographic dual USB backup operations with advanced hardware security features and side-channel attack countermeasures.
> **NOTE:** This is a library package** designed to be imported into your applications. It provides a set of functions to manage secure backups. For the full documentation with interactive diagrams, architecture details, and contribution guidelines, please visit the [GitHub Repository](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library).
---
## Overview
The **PQC Dual USB Library** provides a robust, enterprise-grade solution for securing data against threats from both classical and quantum computers. It offers a functional API for developers to integrate post-quantum cryptography (PQC) into applications requiring secure data storage, especially for scenarios involving redundant backups on physical devices like USB drives.
The library is designed with a "secure-by-default" philosophy, automatically handling complex security operations like side-channel attack mitigation, secure memory management, and hybrid cryptographic schemes.
---
## ️ Architecture Overview
```
┌─────────────────────────────────────────────────────────────┐
│ YOUR APPLICATION │
└─────────────────────┬───────────────────────────────────────┘
│ Import & Use
▼
┌─────────────────────────────────────────────────────────────┐
│ pqcdualusb Library │
├─────────────────────────────────────────────────────────────┤
│ storage.py │ High-level API (init, rotate, verify) │
│ backup.py │ Backup creation and restoration │
│ crypto.py │ Classical crypto (AES-256-GCM, Argon2id) │
│ pqc.py │ Post-quantum crypto (Kyber, Dilithium) │
│ device.py │ USB device validation │
│ audit.py │ Tamper-evident logging │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Physical Storage (USB Drives) │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ PRIMARY USB │ │ BACKUP USB │ │
│ │ • Token │◄────────────►│ • Token │ │
│ │ • State │ Redundant │ • State │ │
│ │ • Backup │ │ • Backup │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
---
## Key Features
### Post-Quantum Security
- **NIST-standardized algorithms**: Kyber1024 (KEM) and Dilithium3 (signatures)
- **Hybrid encryption**: Combines classical AES-256-GCM with post-quantum KEMs
- **Future-proof**: Protection against both classical and quantum computer attacks
### Dual USB Architecture
- **Split secret design**: Data is secured across two physical USB devices
- **Redundant storage**: Automatic synchronization between primary and backup drives
- **Atomic operations**: Ensures data integrity even during power failures
### ️ Security Features
- **Secure memory**: Automatic wiping of sensitive data from RAM
- **Side-channel resistance**: Constant-time operations to prevent timing attacks
- **Strong KDF**: Argon2id protects passphrases against brute-force attacks
- **Tamper-evident logging**: Comprehensive audit trail of all security events
### Developer-Friendly
- **Simple API**: Clean, functional interface with minimal boilerplate
- **Type hints**: Full type annotations for better IDE support
- **Comprehensive tests**: Extensive test suite ensures reliability
- **Cross-platform**: Works on Windows, Linux, and macOS
---
## Installation
```bash
pip install pqcdualusb
```
### Backend Dependencies
The library requires at least one PQC backend. Choose one:
**Option 1: Python backend (Recommended for most users)**
```bash
pip install pqcdualusb[pqc]
```
**Option 2: High-performance Rust backend**
For advanced users who need maximum performance. See the [GitHub README](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library#installation) for Rust setup instructions.
---
## Quick Start Guide
This example demonstrates the end-to-end process of creating and managing a secure dual USB backup using the library's functions.
### Basic Usage
```python
from pathlib import Path
from pqcdualusb.storage import init_dual_usb, rotate_token, verify_dual_setup
from pqcdualusb.backup import restore_from_backup
# Define your USB drive paths
primary_usb = Path("/media/usb1") # Adjust to your system
backup_usb = Path("/media/usb2") # Adjust to your system
# Your secret data (e.g., encryption key, master password)
secret_data = b"my-super-secret-master-key"
passphrase = "a-very-strong-and-unique-passphrase"
# 1. Initialize the dual USB backup system
init_info = init_dual_usb(
token=secret_data,
primary_mount=primary_usb,
backup_mount=backup_usb,
passphrase=passphrase
)
print(f" Initialized: {init_info['primary']}, {init_info['backup']}")
# 2. Verify the backup integrity
is_valid = verify_dual_setup(
primary_mount=primary_usb,
backup_mount=backup_usb,
passphrase=passphrase
)
print(f" Backup verified: {is_valid}")
# 3. Rotate the secret (e.g., periodic key rotation)
new_secret = b"my-new-rotated-master-key"
rotate_info = rotate_token(
token=new_secret,
primary_mount=primary_usb,
backup_mount=backup_usb,
passphrase=passphrase,
prev_rotation=0 # Increment on each rotation
)
print(f" Token rotated to rotation #{rotate_info['rotation']}")
# 4. Restore from backup (disaster recovery)
restore_path = Path("/media/usb_restore")
restored_token, _ = restore_from_backup(
backup_file=Path(rotate_info['backup']),
restore_primary=restore_path,
passphrase=passphrase
)
print(f" Restored to: {restored_token}")
```
### Complete Example with Error Handling
```python
import os
from pathlib import Path
import tempfile
import shutil
# Import the necessary functions from the library
from pqcdualusb.storage import init_dual_usb, rotate_token
from pqcdualusb.backup import restore_from_backup
from pqcdualusb.crypto import verify_backup
from pqcdualusb.exceptions import (
PassphraseMismatchError,
BackupVerificationError,
DeviceNotFoundError
)
# --- Setup: Create temporary directories to simulate USB drives ---
# In a real application, these paths would point to your actual USB drives.
tmp_dir = Path(tempfile.mkdtemp(prefix="pqc_usb_demo_"))
primary_path = tmp_dir / "PRIMARY"
backup_path = tmp_dir / "BACKUP"
primary_path.mkdir()
backup_path.mkdir()
print(f" Simulating USB drives:\n Primary: {primary_path}\n Backup: {backup_path}\n")
# --- Core Variables ---
passphrase = "a-very-strong-and-unique-passphrase"
initial_secret = os.urandom(64) # 512-bit secret
try:
# 1. Initialize the Dual USB Backup
print("Step 1: Initializing the dual USB backup...")
init_info = init_dual_usb(
token=initial_secret,
primary_mount=primary_path,
backup_mount=backup_path,
passphrase=passphrase
)
print(f" Initialization complete.")
print(f" Primary: {init_info['primary']}")
print(f" Backup: {init_info['backup']}\n")
# 2. Verify the Backup Integrity
print("Step 2: Verifying the backup file...")
is_valid = verify_backup(
Path(init_info['backup_file']),
passphrase,
initial_secret
)
if is_valid:
print(" Backup integrity verified successfully.\n")
else:
raise BackupVerificationError("Backup verification failed!")
# 3. Rotate the Token with a New Secret
print("Step 3: Rotating the token with a new secret...")
new_secret = os.urandom(64)
rotate_info = rotate_token(
token=new_secret,
primary_mount=primary_path,
backup_mount=backup_path,
passphrase=passphrase,
prev_rotation=0
)
print(f" Token rotation complete.")
print(f" Rotation number: {rotate_info['rotation']}")
print(f" New backup: {rotate_info['backup']}\n")
# 4. Restore from the Latest Backup
print("Step 4: Restoring the secret from the latest backup...")
restore_path = tmp_dir / "RESTORED"
restore_path.mkdir()
restored_token_path, _ = restore_from_backup(
backup_file=Path(rotate_info['backup']),
restore_primary=restore_path,
passphrase=passphrase
)
# Verify that the restored data matches the new secret
restored_data = restored_token_path.read_bytes()
assert restored_data == new_secret, "Restored data doesn't match!"
print(f" Restore successful!")
print(f" Restored to: {restored_token_path}")
print(f" Data verified: {len(restored_data)} bytes match.\n")
except PassphraseMismatchError:
print(" Error: Incorrect passphrase provided.")
except BackupVerificationError as e:
print(f" Error: Backup verification failed - {e}")
except DeviceNotFoundError as e:
print(f" Error: USB device not found - {e}")
except Exception as e:
print(f" Unexpected error: {e}")
finally:
# --- Cleanup ---
shutil.rmtree(tmp_dir)
print(" Cleanup complete.")
```
---
## Security Properties
### Cryptographic Stack
| Component | Algorithm | Purpose |
|-----------|-----------|---------|
| **Key Derivation** | Argon2id | Protects passphrase from brute-force attacks |
| **Symmetric Encryption** | AES-256-GCM | Fast, authenticated encryption for data |
| **Post-Quantum KEM** | Kyber1024 | Quantum-resistant key encapsulation |
| **Post-Quantum Signature** | Dilithium3 | Quantum-resistant digital signatures |
| **HMAC** | HMAC-SHA256 | Additional integrity verification |
### Security Workflow
```
User Passphrase
│
▼
┌─────────────┐
│ Argon2id │ ← Memory-hard KDF
└──────┬──────┘
│
▼
Master Key (256-bit)
│
├─────────────────────┐
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ AES-256-GCM │ │ Kyber1024 │
│ Classical │ │ Post-Quantum │
└──────┬───────┘ └──────┬───────┘
│ │
└──────────┬──────────┘
│
▼
Encrypted Secret
│
▼
┌─────────────────────────────┐
│ Dilithium3 │
│ Digital Signature │
└─────────────────────────────┘
│
▼
USB Storage (Dual)
```
---
## API Reference
### Core Functions
#### `init_dual_usb(token, primary_mount, backup_mount, passphrase)`
Initialize a new dual USB backup system.
**Parameters:**
- `token` (bytes): The secret data to protect (32-128 bytes recommended)
- `primary_mount` (Path): Path to the primary USB drive
- `backup_mount` (Path): Path to the backup USB drive
- `passphrase` (str): User passphrase for encryption
**Returns:** Dictionary with initialization information
---
#### `rotate_token(token, primary_mount, backup_mount, passphrase, prev_rotation)`
Rotate the secret with a new value.
**Parameters:**
- `token` (bytes): The new secret data
- `primary_mount` (Path): Path to the primary USB drive
- `backup_mount` (Path): Path to the backup USB drive
- `passphrase` (str): User passphrase (must match initialization)
- `prev_rotation` (int): Previous rotation number
**Returns:** Dictionary with rotation information
---
#### `verify_dual_setup(primary_mount, backup_mount, passphrase)`
Verify the integrity of the dual USB setup.
**Parameters:**
- `primary_mount` (Path): Path to the primary USB drive
- `backup_mount` (Path): Path to the backup USB drive
- `passphrase` (str): User passphrase
**Returns:** `True` if verification passes, `False` otherwise
---
#### `restore_from_backup(backup_file, restore_primary, passphrase)`
Restore data from a backup file.
**Parameters:**
- `backup_file` (Path): Path to the backup file
- `restore_primary` (Path): Path where to restore the primary token
- `passphrase` (str): User passphrase
**Returns:** Tuple of (restored_token_path, state_data)
---
## Use Cases
### 1. **Cryptocurrency Wallet Protection**
Securely store master private keys across two USB devices with quantum-resistant encryption.
### 2. **Enterprise Key Management**
Manage encryption keys for organizational data with audit logging and rotation capabilities.
### 3. **Password Manager Master Key**
Protect the master encryption key for password management systems with redundant backups.
### 4. **Secure Document Storage**
Encrypt and backup sensitive documents with post-quantum security guarantees.
### 5. **Hardware Security Module (HSM) Backup**
Create offline backups of HSM keys with tamper-evident logging.
---
## Advanced Configuration
### Custom Argon2id Parameters
```python
from pqcdualusb.crypto import derive_key
# High-security settings (slower but more secure)
key = derive_key(
passphrase="my-passphrase",
salt=b"random-salt-32-bytes",
time_cost=4, # Default: 3
memory_cost=65536 # Default: 65536 (64 MB)
)
```
### Secure Memory Wiping
```python
from pqcdualusb.crypto import secure_wipe
sensitive_data = bytearray(b"secret-data")
# Use the data...
secure_wipe(sensitive_data) # Automatically wipes on deletion
```
---
## Documentation
For comprehensive documentation including:
- **Architecture diagrams** (interactive Mermaid diagrams on GitHub)
- **Detailed API reference**
- **Security analysis**
- **Contribution guidelines**
- **Threat model**
Visit the [GitHub Repository](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library).
---
## Contributing
Contributions are welcome! Please see the [CONTRIBUTING.md](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library/blob/master/CONTRIBUTING.md) file for guidelines.
---
## Security
For security vulnerabilities, please email **Johnsonajibi@gmail.com** instead of using the issue tracker.
See [SECURITY.md](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library/blob/master/SECURITY.md) for our security policy.
---
## License
This project is licensed under the MIT License. See the [LICENSE](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library/blob/master/LICENSE) file for details.
---
## Acknowledgments
- **NIST** for standardizing post-quantum cryptography algorithms
- **Open Quantum Safe (OQS)** project for the `liboqs` library
- The cryptography community for ongoing research and development
---
## Support
- **Documentation**: [GitHub Repository](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library)
- **Issues**: [GitHub Issues](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library/issues)
- **Email**: Johnsonajibi@gmail.com
Raw data
{
"_id": null,
"home_page": null,
"name": "pqcdualusb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Johnson Ajibi <Johnsonajibi@gmail.com>",
"keywords": "cryptography, post-quantum, usb, backup, security, token",
"author": null,
"author_email": "Johnson Ajibi <Johnsonajibi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/26/1d/5e75cc08517975f58d49a6f28a53336a1ec33290e1d5f57805023f25e458/pqcdualusb-0.1.4.tar.gz",
"platform": null,
"description": "# PQC Dual USB Library\r\n\r\n[](https://badge.fury.io/py/pqcdualusb)\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://en.wikipedia.org/wiki/Post-quantum_cryptography)\r\n\r\nA comprehensive **Python library** for post-quantum cryptographic dual USB backup operations with advanced hardware security features and side-channel attack countermeasures.\r\n\r\n> **NOTE:** This is a library package** designed to be imported into your applications. It provides a set of functions to manage secure backups. For the full documentation with interactive diagrams, architecture details, and contribution guidelines, please visit the [GitHub Repository](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library).\r\n\r\n---\r\n\r\n## Overview\r\n\r\nThe **PQC Dual USB Library** provides a robust, enterprise-grade solution for securing data against threats from both classical and quantum computers. It offers a functional API for developers to integrate post-quantum cryptography (PQC) into applications requiring secure data storage, especially for scenarios involving redundant backups on physical devices like USB drives.\r\n\r\nThe library is designed with a \"secure-by-default\" philosophy, automatically handling complex security operations like side-channel attack mitigation, secure memory management, and hybrid cryptographic schemes.\r\n\r\n---\r\n\r\n## \ufe0f Architecture Overview\r\n\r\n```\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502 YOUR APPLICATION \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n \u2502 Import & Use\r\n \u25bc\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502 pqcdualusb Library \u2502\r\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\r\n\u2502 storage.py \u2502 High-level API (init, rotate, verify) \u2502\r\n\u2502 backup.py \u2502 Backup creation and restoration \u2502\r\n\u2502 crypto.py \u2502 Classical crypto (AES-256-GCM, Argon2id) \u2502\r\n\u2502 pqc.py \u2502 Post-quantum crypto (Kyber, Dilithium) \u2502\r\n\u2502 device.py \u2502 USB device validation \u2502\r\n\u2502 audit.py \u2502 Tamper-evident logging \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n \u2502\r\n \u25bc\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502 Physical Storage (USB Drives) \u2502\r\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\r\n\u2502 \u2502 PRIMARY USB \u2502 \u2502 BACKUP USB \u2502 \u2502\r\n\u2502 \u2502 \u2022 Token \u2502\u25c4\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25ba\u2502 \u2022 Token \u2502 \u2502\r\n\u2502 \u2502 \u2022 State \u2502 Redundant \u2502 \u2022 State \u2502 \u2502\r\n\u2502 \u2502 \u2022 Backup \u2502 \u2502 \u2022 Backup \u2502 \u2502\r\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n```\r\n\r\n---\r\n\r\n## Key Features\r\n\r\n### Post-Quantum Security\r\n- **NIST-standardized algorithms**: Kyber1024 (KEM) and Dilithium3 (signatures)\r\n- **Hybrid encryption**: Combines classical AES-256-GCM with post-quantum KEMs\r\n- **Future-proof**: Protection against both classical and quantum computer attacks\r\n\r\n### Dual USB Architecture\r\n- **Split secret design**: Data is secured across two physical USB devices\r\n- **Redundant storage**: Automatic synchronization between primary and backup drives\r\n- **Atomic operations**: Ensures data integrity even during power failures\r\n\r\n### \ufe0f Security Features\r\n- **Secure memory**: Automatic wiping of sensitive data from RAM\r\n- **Side-channel resistance**: Constant-time operations to prevent timing attacks\r\n- **Strong KDF**: Argon2id protects passphrases against brute-force attacks\r\n- **Tamper-evident logging**: Comprehensive audit trail of all security events\r\n\r\n### Developer-Friendly\r\n- **Simple API**: Clean, functional interface with minimal boilerplate\r\n- **Type hints**: Full type annotations for better IDE support\r\n- **Comprehensive tests**: Extensive test suite ensures reliability\r\n- **Cross-platform**: Works on Windows, Linux, and macOS\r\n\r\n---\r\n\r\n## Installation\r\n\r\n```bash\r\npip install pqcdualusb\r\n```\r\n\r\n### Backend Dependencies\r\n\r\nThe library requires at least one PQC backend. Choose one:\r\n\r\n**Option 1: Python backend (Recommended for most users)**\r\n```bash\r\npip install pqcdualusb[pqc]\r\n```\r\n\r\n**Option 2: High-performance Rust backend**\r\n\r\nFor advanced users who need maximum performance. See the [GitHub README](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library#installation) for Rust setup instructions.\r\n\r\n---\r\n\r\n## Quick Start Guide\r\n\r\nThis example demonstrates the end-to-end process of creating and managing a secure dual USB backup using the library's functions.\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom pathlib import Path\r\nfrom pqcdualusb.storage import init_dual_usb, rotate_token, verify_dual_setup\r\nfrom pqcdualusb.backup import restore_from_backup\r\n\r\n# Define your USB drive paths\r\nprimary_usb = Path(\"/media/usb1\") # Adjust to your system\r\nbackup_usb = Path(\"/media/usb2\") # Adjust to your system\r\n\r\n# Your secret data (e.g., encryption key, master password)\r\nsecret_data = b\"my-super-secret-master-key\"\r\npassphrase = \"a-very-strong-and-unique-passphrase\"\r\n\r\n# 1. Initialize the dual USB backup system\r\ninit_info = init_dual_usb(\r\n token=secret_data,\r\n primary_mount=primary_usb,\r\n backup_mount=backup_usb,\r\n passphrase=passphrase\r\n)\r\nprint(f\" Initialized: {init_info['primary']}, {init_info['backup']}\")\r\n\r\n# 2. Verify the backup integrity\r\nis_valid = verify_dual_setup(\r\n primary_mount=primary_usb,\r\n backup_mount=backup_usb,\r\n passphrase=passphrase\r\n)\r\nprint(f\" Backup verified: {is_valid}\")\r\n\r\n# 3. Rotate the secret (e.g., periodic key rotation)\r\nnew_secret = b\"my-new-rotated-master-key\"\r\nrotate_info = rotate_token(\r\n token=new_secret,\r\n primary_mount=primary_usb,\r\n backup_mount=backup_usb,\r\n passphrase=passphrase,\r\n prev_rotation=0 # Increment on each rotation\r\n)\r\nprint(f\" Token rotated to rotation #{rotate_info['rotation']}\")\r\n\r\n# 4. Restore from backup (disaster recovery)\r\nrestore_path = Path(\"/media/usb_restore\")\r\nrestored_token, _ = restore_from_backup(\r\n backup_file=Path(rotate_info['backup']),\r\n restore_primary=restore_path,\r\n passphrase=passphrase\r\n)\r\nprint(f\" Restored to: {restored_token}\")\r\n```\r\n\r\n### Complete Example with Error Handling\r\n\r\n```python\r\nimport os\r\nfrom pathlib import Path\r\nimport tempfile\r\nimport shutil\r\n\r\n# Import the necessary functions from the library\r\nfrom pqcdualusb.storage import init_dual_usb, rotate_token\r\nfrom pqcdualusb.backup import restore_from_backup\r\nfrom pqcdualusb.crypto import verify_backup\r\nfrom pqcdualusb.exceptions import (\r\n PassphraseMismatchError,\r\n BackupVerificationError,\r\n DeviceNotFoundError\r\n)\r\n\r\n# --- Setup: Create temporary directories to simulate USB drives ---\r\n# In a real application, these paths would point to your actual USB drives.\r\ntmp_dir = Path(tempfile.mkdtemp(prefix=\"pqc_usb_demo_\"))\r\nprimary_path = tmp_dir / \"PRIMARY\"\r\nbackup_path = tmp_dir / \"BACKUP\"\r\nprimary_path.mkdir()\r\nbackup_path.mkdir()\r\n\r\nprint(f\" Simulating USB drives:\\n Primary: {primary_path}\\n Backup: {backup_path}\\n\")\r\n\r\n# --- Core Variables ---\r\npassphrase = \"a-very-strong-and-unique-passphrase\"\r\ninitial_secret = os.urandom(64) # 512-bit secret\r\n\r\ntry:\r\n # 1. Initialize the Dual USB Backup\r\n print(\"Step 1: Initializing the dual USB backup...\")\r\n init_info = init_dual_usb(\r\n token=initial_secret,\r\n primary_mount=primary_path,\r\n backup_mount=backup_path,\r\n passphrase=passphrase\r\n )\r\n print(f\" Initialization complete.\")\r\n print(f\" Primary: {init_info['primary']}\")\r\n print(f\" Backup: {init_info['backup']}\\n\")\r\n\r\n # 2. Verify the Backup Integrity\r\n print(\"Step 2: Verifying the backup file...\")\r\n is_valid = verify_backup(\r\n Path(init_info['backup_file']),\r\n passphrase,\r\n initial_secret\r\n )\r\n if is_valid:\r\n print(\" Backup integrity verified successfully.\\n\")\r\n else:\r\n raise BackupVerificationError(\"Backup verification failed!\")\r\n\r\n # 3. Rotate the Token with a New Secret\r\n print(\"Step 3: Rotating the token with a new secret...\")\r\n new_secret = os.urandom(64)\r\n rotate_info = rotate_token(\r\n token=new_secret,\r\n primary_mount=primary_path,\r\n backup_mount=backup_path,\r\n passphrase=passphrase,\r\n prev_rotation=0\r\n )\r\n print(f\" Token rotation complete.\")\r\n print(f\" Rotation number: {rotate_info['rotation']}\")\r\n print(f\" New backup: {rotate_info['backup']}\\n\")\r\n\r\n # 4. Restore from the Latest Backup\r\n print(\"Step 4: Restoring the secret from the latest backup...\")\r\n restore_path = tmp_dir / \"RESTORED\"\r\n restore_path.mkdir()\r\n \r\n restored_token_path, _ = restore_from_backup(\r\n backup_file=Path(rotate_info['backup']),\r\n restore_primary=restore_path,\r\n passphrase=passphrase\r\n )\r\n \r\n # Verify that the restored data matches the new secret\r\n restored_data = restored_token_path.read_bytes()\r\n assert restored_data == new_secret, \"Restored data doesn't match!\"\r\n print(f\" Restore successful!\")\r\n print(f\" Restored to: {restored_token_path}\")\r\n print(f\" Data verified: {len(restored_data)} bytes match.\\n\")\r\n\r\nexcept PassphraseMismatchError:\r\n print(\" Error: Incorrect passphrase provided.\")\r\nexcept BackupVerificationError as e:\r\n print(f\" Error: Backup verification failed - {e}\")\r\nexcept DeviceNotFoundError as e:\r\n print(f\" Error: USB device not found - {e}\")\r\nexcept Exception as e:\r\n print(f\" Unexpected error: {e}\")\r\nfinally:\r\n # --- Cleanup ---\r\n shutil.rmtree(tmp_dir)\r\n print(\" Cleanup complete.\")\r\n```\r\n\r\n---\r\n\r\n## Security Properties\r\n\r\n### Cryptographic Stack\r\n\r\n| Component | Algorithm | Purpose |\r\n|-----------|-----------|---------|\r\n| **Key Derivation** | Argon2id | Protects passphrase from brute-force attacks |\r\n| **Symmetric Encryption** | AES-256-GCM | Fast, authenticated encryption for data |\r\n| **Post-Quantum KEM** | Kyber1024 | Quantum-resistant key encapsulation |\r\n| **Post-Quantum Signature** | Dilithium3 | Quantum-resistant digital signatures |\r\n| **HMAC** | HMAC-SHA256 | Additional integrity verification |\r\n\r\n### Security Workflow\r\n\r\n```\r\nUser Passphrase\r\n \u2502\r\n \u25bc\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502 Argon2id \u2502 \u2190 Memory-hard KDF\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n \u2502\r\n \u25bc\r\n Master Key (256-bit)\r\n \u2502\r\n \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n \u2502 \u2502\r\n \u25bc \u25bc\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502 AES-256-GCM \u2502 \u2502 Kyber1024 \u2502\r\n\u2502 Classical \u2502 \u2502 Post-Quantum \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n \u2502 \u2502\r\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n \u2502\r\n \u25bc\r\n Encrypted Secret\r\n \u2502\r\n \u25bc\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502 Dilithium3 \u2502\r\n\u2502 Digital Signature \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n \u2502\r\n \u25bc\r\n USB Storage (Dual)\r\n```\r\n\r\n---\r\n\r\n## API Reference\r\n\r\n### Core Functions\r\n\r\n#### `init_dual_usb(token, primary_mount, backup_mount, passphrase)`\r\nInitialize a new dual USB backup system.\r\n\r\n**Parameters:**\r\n- `token` (bytes): The secret data to protect (32-128 bytes recommended)\r\n- `primary_mount` (Path): Path to the primary USB drive\r\n- `backup_mount` (Path): Path to the backup USB drive\r\n- `passphrase` (str): User passphrase for encryption\r\n\r\n**Returns:** Dictionary with initialization information\r\n\r\n---\r\n\r\n#### `rotate_token(token, primary_mount, backup_mount, passphrase, prev_rotation)`\r\nRotate the secret with a new value.\r\n\r\n**Parameters:**\r\n- `token` (bytes): The new secret data\r\n- `primary_mount` (Path): Path to the primary USB drive\r\n- `backup_mount` (Path): Path to the backup USB drive\r\n- `passphrase` (str): User passphrase (must match initialization)\r\n- `prev_rotation` (int): Previous rotation number\r\n\r\n**Returns:** Dictionary with rotation information\r\n\r\n---\r\n\r\n#### `verify_dual_setup(primary_mount, backup_mount, passphrase)`\r\nVerify the integrity of the dual USB setup.\r\n\r\n**Parameters:**\r\n- `primary_mount` (Path): Path to the primary USB drive\r\n- `backup_mount` (Path): Path to the backup USB drive \r\n- `passphrase` (str): User passphrase\r\n\r\n**Returns:** `True` if verification passes, `False` otherwise\r\n\r\n---\r\n\r\n#### `restore_from_backup(backup_file, restore_primary, passphrase)`\r\nRestore data from a backup file.\r\n\r\n**Parameters:**\r\n- `backup_file` (Path): Path to the backup file\r\n- `restore_primary` (Path): Path where to restore the primary token\r\n- `passphrase` (str): User passphrase\r\n\r\n**Returns:** Tuple of (restored_token_path, state_data)\r\n\r\n---\r\n\r\n## Use Cases\r\n\r\n### 1. **Cryptocurrency Wallet Protection**\r\nSecurely store master private keys across two USB devices with quantum-resistant encryption.\r\n\r\n### 2. **Enterprise Key Management**\r\nManage encryption keys for organizational data with audit logging and rotation capabilities.\r\n\r\n### 3. **Password Manager Master Key**\r\nProtect the master encryption key for password management systems with redundant backups.\r\n\r\n### 4. **Secure Document Storage**\r\nEncrypt and backup sensitive documents with post-quantum security guarantees.\r\n\r\n### 5. **Hardware Security Module (HSM) Backup**\r\nCreate offline backups of HSM keys with tamper-evident logging.\r\n\r\n---\r\n\r\n## Advanced Configuration\r\n\r\n### Custom Argon2id Parameters\r\n\r\n```python\r\nfrom pqcdualusb.crypto import derive_key\r\n\r\n# High-security settings (slower but more secure)\r\nkey = derive_key(\r\n passphrase=\"my-passphrase\",\r\n salt=b\"random-salt-32-bytes\",\r\n time_cost=4, # Default: 3\r\n memory_cost=65536 # Default: 65536 (64 MB)\r\n)\r\n```\r\n\r\n### Secure Memory Wiping\r\n\r\n```python\r\nfrom pqcdualusb.crypto import secure_wipe\r\n\r\nsensitive_data = bytearray(b\"secret-data\")\r\n# Use the data...\r\nsecure_wipe(sensitive_data) # Automatically wipes on deletion\r\n```\r\n\r\n---\r\n\r\n## Documentation\r\n\r\nFor comprehensive documentation including:\r\n- **Architecture diagrams** (interactive Mermaid diagrams on GitHub)\r\n- **Detailed API reference**\r\n- **Security analysis**\r\n- **Contribution guidelines**\r\n- **Threat model**\r\n\r\nVisit the [GitHub Repository](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library).\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please see the [CONTRIBUTING.md](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library/blob/master/CONTRIBUTING.md) file for guidelines.\r\n\r\n---\r\n\r\n## Security\r\n\r\nFor security vulnerabilities, please email **Johnsonajibi@gmail.com** instead of using the issue tracker.\r\n\r\nSee [SECURITY.md](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library/blob/master/SECURITY.md) for our security policy.\r\n\r\n---\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License. See the [LICENSE](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library/blob/master/LICENSE) file for details.\r\n\r\n---\r\n\r\n## Acknowledgments\r\n\r\n- **NIST** for standardizing post-quantum cryptography algorithms\r\n- **Open Quantum Safe (OQS)** project for the `liboqs` library\r\n- The cryptography community for ongoing research and development\r\n\r\n---\r\n\r\n## Support\r\n\r\n- **Documentation**: [GitHub Repository](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library)\r\n- **Issues**: [GitHub Issues](https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library/issues)\r\n- **Email**: Johnsonajibi@gmail.com\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Post-Quantum Cryptography Dual USB Token Library for secure backup operations",
"version": "0.1.4",
"project_urls": {
"Bug Tracker": "https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library/issues",
"Changelog": "https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library/blob/master/CHANGELOG.md",
"Documentation": "https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library/blob/master/README.md",
"Homepage": "https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library",
"Repository": "https://github.com/Johnsonajibi/PostQuantum-DualUSB-Token-Library.git"
},
"split_keywords": [
"cryptography",
" post-quantum",
" usb",
" backup",
" security",
" token"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "76db2524f2839b4ae8346ddad8cd395cfeff2b1c230c8f43649d08abf04b1abb",
"md5": "da5be44331b9ee70b069c11b306abceb",
"sha256": "ff35860d4f197362ed170b64a46148fb5d8fb90142386b990c219b0687dc4fc6"
},
"downloads": -1,
"filename": "pqcdualusb-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "da5be44331b9ee70b069c11b306abceb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 58608,
"upload_time": "2025-10-18T06:31:49",
"upload_time_iso_8601": "2025-10-18T06:31:49.471246Z",
"url": "https://files.pythonhosted.org/packages/76/db/2524f2839b4ae8346ddad8cd395cfeff2b1c230c8f43649d08abf04b1abb/pqcdualusb-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "261d5e75cc08517975f58d49a6f28a53336a1ec33290e1d5f57805023f25e458",
"md5": "06173876bbb30f7c183e211bfdae59d2",
"sha256": "a5f6a2b29c94278fc75c45daabf848e4bd0a4651d4e6b8d62d37bbbec11aa53f"
},
"downloads": -1,
"filename": "pqcdualusb-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "06173876bbb30f7c183e211bfdae59d2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 69082,
"upload_time": "2025-10-18T06:31:51",
"upload_time_iso_8601": "2025-10-18T06:31:51.108902Z",
"url": "https://files.pythonhosted.org/packages/26/1d/5e75cc08517975f58d49a6f28a53336a1ec33290e1d5f57805023f25e458/pqcdualusb-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-18 06:31:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Johnsonajibi",
"github_project": "PostQuantum-DualUSB-Token-Library",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pqcdualusb"
}
JSON
