'unlock keys' renamed to 'unlockers'
This commit is contained in:
74
README.md
74
README.md
@@ -9,12 +9,12 @@ Secret is a modern, secure command-line secret manager that implements a hierarc
|
||||
Secret implements a sophisticated three-layer key architecture:
|
||||
|
||||
1. **Long-term Keys**: Derived from BIP39 mnemonic phrases, these provide the foundation for all encryption
|
||||
2. **Unlock Keys**: Short-term keys that encrypt the long-term keys, supporting multiple authentication methods
|
||||
2. **Unlockers**: Short-term keys that encrypt the long-term keys, supporting multiple authentication methods
|
||||
3. **Secret-specific Keys**: Per-secret keys that encrypt individual secret values
|
||||
|
||||
### Vault System
|
||||
|
||||
Vaults provide logical separation of secrets, each with its own long-term key and unlock key set. This allows for complete isolation between different contexts (work, personal, projects).
|
||||
Vaults provide logical separation of secrets, each with its own long-term key and unlocker set. This allows for complete isolation between different contexts (work, personal, projects).
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -97,26 +97,26 @@ Generates and stores a random secret.
|
||||
- `--type, -t`: Type of secret (`base58`, `alnum`)
|
||||
- `--force, -f`: Overwrite existing secret
|
||||
|
||||
### Unlock Key Management
|
||||
### Unlocker Management
|
||||
|
||||
#### `secret keys list [--json]`
|
||||
Lists all unlock keys in the current vault with their metadata.
|
||||
#### `secret unlockers list [--json]`
|
||||
Lists all unlockers in the current vault with their metadata.
|
||||
|
||||
#### `secret keys add <type> [options]`
|
||||
Creates a new unlock key of the specified type:
|
||||
#### `secret unlockers add <type> [options]`
|
||||
Creates a new unlocker of the specified type:
|
||||
|
||||
**Types:**
|
||||
- `passphrase`: Traditional passphrase-protected unlock key
|
||||
- `passphrase`: Traditional passphrase-protected unlocker
|
||||
- `pgp`: Uses an existing GPG key for encryption/decryption
|
||||
|
||||
**Options:**
|
||||
- `--keyid <id>`: GPG key ID (required for PGP type)
|
||||
|
||||
#### `secret keys rm <key-id>`
|
||||
Removes an unlock key.
|
||||
#### `secret unlockers rm <unlocker-id>`
|
||||
Removes an unlocker.
|
||||
|
||||
#### `secret key select <key-id>`
|
||||
Selects an unlock key as the current default for operations.
|
||||
#### `secret unlocker select <unlocker-id>`
|
||||
Selects an unlocker as the current default for operations.
|
||||
|
||||
### Import Operations
|
||||
|
||||
@@ -142,17 +142,17 @@ Decrypts data using an Age key stored as a secret.
|
||||
~/.local/share/secret/
|
||||
├── vaults.d/
|
||||
│ ├── default/
|
||||
│ │ ├── unlock.d/
|
||||
│ │ │ ├── passphrase/ # Passphrase unlock key
|
||||
│ │ │ └── pgp/ # PGP unlock key
|
||||
│ │ ├── unlockers.d/
|
||||
│ │ │ ├── passphrase/ # Passphrase unlocker
|
||||
│ │ │ └── pgp/ # PGP unlocker
|
||||
│ │ ├── secrets.d/
|
||||
│ │ │ ├── api%key/ # Secret: api/key
|
||||
│ │ │ └── database%password/ # Secret: database/password
|
||||
│ │ └── current-unlock-key -> ../unlock.d/passphrase
|
||||
│ │ └── current-unlocker -> ../unlockers.d/passphrase
|
||||
│ └── work/
|
||||
│ ├── unlock.d/
|
||||
│ ├── unlockers.d/
|
||||
│ ├── secrets.d/
|
||||
│ └── current-unlock-key
|
||||
│ └── current-unlocker
|
||||
├── currentvault -> vaults.d/default
|
||||
└── configuration.json
|
||||
```
|
||||
@@ -162,22 +162,22 @@ Decrypts data using an Age key stored as a secret.
|
||||
#### Long-term Keys
|
||||
- **Source**: Derived from BIP39 mnemonic phrases using hierarchical deterministic (HD) key derivation
|
||||
- **Purpose**: Master keys for each vault, used to encrypt secret-specific keys
|
||||
- **Storage**: Public key stored as `pub.age`, private key encrypted by unlock keys
|
||||
- **Storage**: Public key stored as `pub.age`, private key encrypted by unlockers
|
||||
|
||||
#### Unlock Keys
|
||||
Unlock keys provide different authentication methods to access the long-term keys:
|
||||
#### Unlockers
|
||||
Unlockers provide different authentication methods to access the long-term keys:
|
||||
|
||||
1. **Passphrase Keys**:
|
||||
1. **Passphrase Unlockers**:
|
||||
- Encrypted with user-provided passphrase
|
||||
- Stored as encrypted Age keys
|
||||
- Cross-platform compatible
|
||||
|
||||
2. **PGP Keys**:
|
||||
2. **PGP Unlockers**:
|
||||
- Uses existing GPG key infrastructure
|
||||
- Leverages existing key management workflows
|
||||
- Strong authentication through GPG
|
||||
|
||||
Each vault maintains its own set of unlock keys and one long-term key. The long-term key is encrypted to each unlock key, allowing any authorized unlock key to access vault secrets.
|
||||
Each vault maintains its own set of unlockers and one long-term key. The long-term key is encrypted to each unlocker, allowing any authorized unlocker to access vault secrets.
|
||||
|
||||
#### Secret-specific Keys
|
||||
- Each secret has its own encryption key pair
|
||||
@@ -189,7 +189,7 @@ Each vault maintains its own set of unlock keys and one long-term key. The long-
|
||||
- `SB_SECRET_STATE_DIR`: Custom state directory location
|
||||
- `SB_SECRET_MNEMONIC`: Pre-set mnemonic phrase (avoids interactive prompt)
|
||||
- `SB_UNLOCK_PASSPHRASE`: Pre-set unlock passphrase (avoids interactive prompt)
|
||||
- `SB_GPG_KEY_ID`: GPG key ID for PGP unlock keys
|
||||
- `SB_GPG_KEY_ID`: GPG key ID for PGP unlockers
|
||||
|
||||
## Security Features
|
||||
|
||||
@@ -205,7 +205,7 @@ Each vault maintains its own set of unlock keys and one long-term key. The long-
|
||||
|
||||
### Forward Secrecy
|
||||
- Per-secret encryption keys limit exposure if compromised
|
||||
- Long-term keys protected by multiple unlock key layers
|
||||
- Long-term keys protected by multiple unlocker layers
|
||||
|
||||
### Hardware Integration
|
||||
- Hardware token support via PGP/GPG integration
|
||||
@@ -238,7 +238,7 @@ secret vault create personal
|
||||
# Work with work vault
|
||||
secret vault select work
|
||||
echo "work-db-pass" | secret add database/password
|
||||
secret keys add passphrase # Add passphrase authentication
|
||||
secret unlockers add passphrase # Add passphrase authentication
|
||||
|
||||
# Switch to personal vault
|
||||
secret vault select personal
|
||||
@@ -251,14 +251,14 @@ secret vault list
|
||||
### Advanced Authentication
|
||||
```bash
|
||||
# Add multiple unlock methods
|
||||
secret keys add passphrase # Password-based
|
||||
secret keys add pgp --keyid ABCD1234 # GPG key
|
||||
secret unlockers add passphrase # Password-based
|
||||
secret unlockers add pgp --keyid ABCD1234 # GPG key
|
||||
|
||||
# List unlock keys
|
||||
secret keys list
|
||||
# List unlockers
|
||||
secret unlockers list
|
||||
|
||||
# Select a specific unlock key
|
||||
secret key select <key-id>
|
||||
# Select a specific unlocker
|
||||
secret unlocker select <unlocker-id>
|
||||
```
|
||||
|
||||
### Encryption/Decryption with Age Keys
|
||||
@@ -299,14 +299,14 @@ secret decrypt encryption/mykey --input document.txt.age --output document.txt
|
||||
- Supports hardware-backed authentication where available
|
||||
|
||||
### Best Practices
|
||||
1. Use strong, unique passphrases for unlock keys
|
||||
1. Use strong, unique passphrases for unlockers
|
||||
2. Enable hardware authentication (Keychain, hardware tokens) when available
|
||||
3. Regularly audit unlock keys and remove unused ones
|
||||
3. Regularly audit unlockers and remove unused ones
|
||||
4. Keep mnemonic phrases securely backed up offline
|
||||
5. Use separate vaults for different security contexts
|
||||
|
||||
### Limitations
|
||||
- Requires access to unlock keys for secret retrieval
|
||||
- Requires access to unlockers for secret retrieval
|
||||
- Mnemonic phrases must be securely stored and backed up
|
||||
- Hardware features limited to supported platforms
|
||||
|
||||
@@ -328,7 +328,7 @@ go test ./... # Unit tests
|
||||
|
||||
## Features
|
||||
|
||||
- **Multiple Authentication Methods**: Supports passphrase-based and PGP-based unlock keys
|
||||
- **Multiple Authentication Methods**: Supports passphrase-based and PGP-based unlockers
|
||||
- **Vault Isolation**: Complete separation between different vaults
|
||||
- **Per-Secret Encryption**: Each secret has its own encryption key
|
||||
- **BIP39 Mnemonic Support**: Keyless operation using mnemonic phrases
|
||||
|
||||
Reference in New Issue
Block a user