man what a clusterfuck
This commit is contained in:
122
README.md
122
README.md
@@ -22,7 +22,7 @@ Build from source:
|
||||
```bash
|
||||
git clone <repository>
|
||||
cd secret
|
||||
make build
|
||||
go build -o secret ./cmd/secret
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
@@ -106,15 +106,15 @@ Lists all unlock keys in the current vault with their metadata.
|
||||
Creates a new unlock key of the specified type:
|
||||
|
||||
**Types:**
|
||||
- `passphrase`: Password-protected unlock key
|
||||
- `keychain`: macOS Keychain unlock key (Touch ID/Face ID)
|
||||
- `pgp`: GPG/PGP key unlock key
|
||||
- `passphrase`: Traditional passphrase-protected unlock key
|
||||
- `keychain`: macOS Keychain-protected unlock key (macOS only)
|
||||
- `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 from the current vault.
|
||||
Removes an unlock key.
|
||||
|
||||
#### `secret key select <key-id>`
|
||||
Selects an unlock key as the current default for operations.
|
||||
@@ -127,9 +127,6 @@ Imports a secret from a file and stores it in the current vault under the given
|
||||
#### `secret vault import [vault-name]`
|
||||
Imports a mnemonic phrase into the specified vault (defaults to "default").
|
||||
|
||||
#### `secret enroll`
|
||||
Enrolls a macOS Keychain unlock key for biometric authentication.
|
||||
|
||||
### Encryption Operations
|
||||
|
||||
#### `secret encrypt <secret-name> [--input=file] [--output=file]`
|
||||
@@ -143,43 +140,23 @@ Decrypts data using an Age key stored as a secret.
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
$BASE/ # ~/.config/berlin.sneak.pkg.secret (Linux) or ~/Library/Application Support/berlin.sneak.pkg.secret (macOS)
|
||||
├── configuration.json # Global configuration
|
||||
├── currentvault -> vaults.d/default # Symlink to current vault
|
||||
└── vaults.d/
|
||||
├── default/ # Default vault
|
||||
│ ├── vault-metadata.json # Vault metadata
|
||||
│ ├── pub.age # Long-term public key
|
||||
│ ├── current-unlock-key -> unlock.d/passphrase # Current unlock key symlink
|
||||
│ ├── unlock.d/ # Unlock keys directory
|
||||
│ │ ├── passphrase/ # Passphrase unlock key
|
||||
│ │ │ ├── unlock-metadata.json # Unlock key metadata
|
||||
│ │ │ ├── pub.age # Unlock key public key
|
||||
│ │ │ ├── priv.age # Unlock key private key (encrypted)
|
||||
│ │ │ └── longterm.age # Long-term private key (encrypted to this unlock key)
|
||||
│ │ ├── keychain/ # Keychain unlock key
|
||||
│ │ │ ├── unlock-metadata.json
|
||||
│ │ │ ├── pub.age
|
||||
│ │ │ ├── priv.age
|
||||
│ │ │ └── longterm.age
|
||||
│ │ └── pgp/ # PGP unlock key
|
||||
│ │ ├── unlock-metadata.json
|
||||
│ │ ├── pub.age
|
||||
│ │ ├── priv.asc # PGP-encrypted private key
|
||||
│ │ └── longterm.age
|
||||
│ └── secrets.d/ # Secrets directory
|
||||
│ ├── my-service%password/ # Secret directory (slashes encoded as %)
|
||||
│ │ ├── value.age # Encrypted secret value
|
||||
│ │ ├── pub.age # Secret-specific public key
|
||||
│ │ ├── priv.age # Secret-specific private key (encrypted to long-term key)
|
||||
│ │ └── secret-metadata.json # Secret metadata
|
||||
│ └── api%keys%production/
|
||||
│ ├── value.age
|
||||
│ ├── pub.age
|
||||
│ ├── priv.age
|
||||
│ └── secret-metadata.json
|
||||
└── work/ # Additional vault
|
||||
└── ... (same structure as default)
|
||||
~/.local/share/secret/
|
||||
├── vaults.d/
|
||||
│ ├── default/
|
||||
│ │ ├── unlock-keys.d/
|
||||
│ │ │ ├── passphrase/ # Passphrase unlock key
|
||||
│ │ │ ├── keychain/ # Keychain unlock key (macOS)
|
||||
│ │ │ └── pgp/ # PGP unlock key
|
||||
│ │ ├── secrets.d/
|
||||
│ │ │ ├── api%key/ # Secret: api/key
|
||||
│ │ │ └── database%password/ # Secret: database/password
|
||||
│ │ └── current-unlock-key -> ../unlock-keys.d/passphrase
|
||||
│ └── work/
|
||||
│ ├── unlock-keys.d/
|
||||
│ ├── secrets.d/
|
||||
│ └── current-unlock-key
|
||||
├── currentvault -> vaults.d/default
|
||||
└── configuration.json
|
||||
```
|
||||
|
||||
### Key Management and Encryption Flow
|
||||
@@ -192,19 +169,22 @@ $BASE/ # ~/.config/berlin.sneak.pkg.secret
|
||||
#### Unlock Keys
|
||||
Unlock keys provide different authentication methods to access the long-term keys:
|
||||
|
||||
1. **Passphrase Unlock Keys**:
|
||||
- Private key encrypted using a user-provided passphrase
|
||||
- Stored as encrypted Age identity in `priv.age`
|
||||
1. **Passphrase Keys**:
|
||||
- Encrypted with user-provided passphrase
|
||||
- Stored as encrypted Age keys
|
||||
- Cross-platform compatible
|
||||
|
||||
2. **macOS Keychain Keys**:
|
||||
- Private key stored in the macOS Keychain
|
||||
- Requires biometric authentication (Touch ID/Face ID)
|
||||
- Provides hardware-backed security
|
||||
2. **Keychain Keys** (macOS only):
|
||||
- Uses macOS Keychain for secure storage
|
||||
- Provides seamless authentication on macOS systems
|
||||
- Age private key encrypted with random passphrase stored in Keychain
|
||||
|
||||
3. **PGP Unlock Keys**:
|
||||
- Private key encrypted using an existing GPG key
|
||||
- Compatible with hardware tokens (YubiKey, etc.)
|
||||
- Stored as PGP-encrypted data in `priv.asc`
|
||||
3. **PGP Keys**:
|
||||
- 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.
|
||||
|
||||
#### Secret-specific Keys
|
||||
- Each secret has its own encryption key pair
|
||||
@@ -234,9 +214,9 @@ Unlock keys provide different authentication methods to access the long-term key
|
||||
- Per-secret encryption keys limit exposure if compromised
|
||||
- Long-term keys protected by multiple unlock key layers
|
||||
|
||||
### Hardware Integration
|
||||
- macOS Keychain support for biometric authentication
|
||||
- Hardware token support via PGP/GPG integration
|
||||
### Platform Integration
|
||||
- macOS Keychain integration for seamless authentication
|
||||
- GPG integration for existing key management workflows
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -266,7 +246,7 @@ secret vault create personal
|
||||
# Work with work vault
|
||||
secret vault select work
|
||||
echo "work-db-pass" | secret add database/password
|
||||
secret keys add keychain # Add Touch ID authentication
|
||||
secret keys add passphrase # Add passphrase authentication
|
||||
|
||||
# Switch to personal vault
|
||||
secret vault select personal
|
||||
@@ -280,7 +260,7 @@ secret vault list
|
||||
```bash
|
||||
# Add multiple unlock methods
|
||||
secret keys add passphrase # Password-based
|
||||
secret keys add keychain # Touch ID (macOS only)
|
||||
secret keys add keychain # macOS Keychain (macOS only)
|
||||
secret keys add pgp --keyid ABCD1234 # GPG key
|
||||
|
||||
# List unlock keys
|
||||
@@ -325,11 +305,11 @@ secret decrypt encryption/mykey --input document.txt.age --output document.txt
|
||||
### Threat Model
|
||||
- Protects against unauthorized access to secret values
|
||||
- Provides defense against compromise of individual components
|
||||
- Supports hardware-backed authentication where available
|
||||
- Supports platform-specific authentication where available
|
||||
|
||||
### Best Practices
|
||||
1. Use strong, unique passphrases for unlock keys
|
||||
2. Enable hardware authentication (Keychain, hardware tokens) when available
|
||||
2. Enable platform-specific authentication (Keychain) when available
|
||||
3. Regularly audit unlock keys and remove unused ones
|
||||
4. Keep mnemonic phrases securely backed up offline
|
||||
5. Use separate vaults for different security contexts
|
||||
@@ -337,15 +317,15 @@ secret decrypt encryption/mykey --input document.txt.age --output document.txt
|
||||
### Limitations
|
||||
- Requires access to unlock keys for secret retrieval
|
||||
- Mnemonic phrases must be securely stored and backed up
|
||||
- Hardware features limited to supported platforms
|
||||
- Platform-specific features limited to supported platforms
|
||||
|
||||
## Development
|
||||
|
||||
### Building
|
||||
```bash
|
||||
make build # Build binary
|
||||
make test # Run tests
|
||||
make lint # Run linter
|
||||
go build -o secret ./cmd/secret # Build binary
|
||||
go test ./... # Run tests
|
||||
go vet ./... # Run static analysis
|
||||
```
|
||||
|
||||
### Testing
|
||||
@@ -355,3 +335,11 @@ The project includes comprehensive tests:
|
||||
go test ./... # Unit tests
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
- **Multiple Authentication Methods**: Supports passphrase-based, keychain-based (macOS), and PGP-based unlock keys
|
||||
- **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
|
||||
- **Cross-Platform**: Works on macOS, Linux, and other Unix-like systems
|
||||
|
||||
|
||||
Reference in New Issue
Block a user