227 lines
6.6 KiB
Markdown
227 lines
6.6 KiB
Markdown
# PassAGE
|
|
|
|
A modern password manager using AGE encryption.
|
|
|
|
**Quick Links:** [Installation](#installation) • [Quick Start](#quick-start) • [Commands](#usage) • [Security](#security) • [Contributing](CONTRIBUTING.md)
|
|
|
|
## Features
|
|
|
|
- **AGE encryption**: Uses AGE (Actually Good Encryption) for secure password storage
|
|
- **Master password model**: Single password protects all stored passwords
|
|
- **Git integration**: Optional git repository support for version control
|
|
- **Command-line interface**: Simple, intuitive commands
|
|
- **Cross-platform**: Works on Linux, macOS, and other Unix-like systems
|
|
- **Clipboard support**: X11 and Wayland clipboard integration
|
|
- **Secure password generation**: Cryptographically secure random password generation
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
- **Go 1.21 or later** - Required for building
|
|
- **Git** - For cloning the repository
|
|
- **pandoc** or **go-md2man** (optional) - For building manpages
|
|
|
|
### Build from Source
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://git.fraggle.lol/fraggle/PassAGE.git
|
|
cd PassAGE
|
|
|
|
# Download dependencies
|
|
go mod download
|
|
|
|
# Build
|
|
go build -o passage .
|
|
|
|
# Or use Makefile
|
|
make build
|
|
```
|
|
|
|
**Installation:**
|
|
|
|
```bash
|
|
# System-wide installation
|
|
sudo make install
|
|
|
|
# User installation (no sudo required)
|
|
make install-user
|
|
```
|
|
|
|
**Or install directly with go:**
|
|
|
|
```bash
|
|
go install git.fraggle.lol/fraggle/PassAGE@latest
|
|
```
|
|
|
|
#### Build Options
|
|
|
|
For production builds, you may want to use additional flags:
|
|
|
|
```bash
|
|
# Build with version information
|
|
go build -ldflags "-X main.version=$(git describe --tags --always --dirty)" -o passage
|
|
|
|
# Build with trimmed paths (for reproducible builds)
|
|
go build -trimpath -o passage
|
|
|
|
# Build with race detector (for testing)
|
|
go build -race -o passage
|
|
|
|
# Build optimized binary (smaller, faster)
|
|
go build -ldflags "-s -w" -trimpath -o passage
|
|
```
|
|
|
|
**Build flags explained:**
|
|
- `-ldflags "-X main.version=..."` - Inject version information at build time
|
|
- `-trimpath` - Remove file system paths for reproducible builds
|
|
- `-race` - Enable race detector (for debugging concurrency issues)
|
|
- `-ldflags "-s -w"` - Strip debug symbols and disable DWARF generation (smaller binary)
|
|
|
|
### Install Binary
|
|
|
|
Pre-built binaries may be available from the [releases page](https://git.fraggle.lol/fraggle/PassAGE/releases).
|
|
|
|
## Quick Start
|
|
|
|
### 1. Initialize the password store
|
|
|
|
Initialize the password store with a master password:
|
|
|
|
```bash
|
|
passage init
|
|
```
|
|
|
|
This will prompt you to:
|
|
- Enter a master password (used to encrypt/decrypt all passwords)
|
|
- Confirm the master password
|
|
|
|
The master password is required for all operations.
|
|
|
|
### 2. Add a password
|
|
|
|
```bash
|
|
passage insert example.com
|
|
```
|
|
|
|
### 3. Retrieve a password
|
|
|
|
```bash
|
|
passage show example.com
|
|
```
|
|
|
|
### 4. Generate a password
|
|
|
|
```bash
|
|
passage generate example.com 32
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Commands
|
|
|
|
- `passage init [--path=subfolder]` - Initialize password store with master password
|
|
- `passage [ls] [subfolder]` - List passwords
|
|
- `passage find pass-names...` - Find passwords by name
|
|
- `passage [show] [--clip[=line-number]] pass-name` - Show password
|
|
- `passage grep search-string` - Search within passwords
|
|
- `passage insert [--multiline] [--force] pass-name` - Insert password
|
|
- `passage edit pass-name` - Edit password
|
|
- `passage generate [--no-symbols] [--clip] [--in-place | --force] pass-name [pass-length]` - Generate password
|
|
- `passage rm [--recursive] [--force] pass-name` - Remove password
|
|
- `passage mv [--force] old-path new-path` - Move/rename password
|
|
- `passage cp [--force] old-path new-path` - Copy password
|
|
- `passage git git-command-args...` - Run git commands
|
|
- `passage help` - Show help
|
|
- `passage version` - Show version
|
|
|
|
### Environment Variables
|
|
|
|
passage respects the following environment variables:
|
|
|
|
- **PASSAGE_DIR** - Path to password store (default: `~/.passage-store`)
|
|
```bash
|
|
export PASSAGE_DIR=~/my-passwords
|
|
```
|
|
|
|
- **PASSAGE_CLIP_TIME** - Time in seconds to keep password in clipboard before auto-clearing (default: 10)
|
|
```bash
|
|
export PASSAGE_CLIP_TIME=30 # Keep in clipboard for 30 seconds
|
|
```
|
|
|
|
- **PASSAGE_GENERATED_LENGTH** - Default length for generated passwords (default: 25)
|
|
```bash
|
|
export PASSAGE_GENERATED_LENGTH=32 # Generate 32-character passwords by default
|
|
```
|
|
|
|
- **EDITOR** - Editor to use for `passage edit` command (default: `vi`)
|
|
```bash
|
|
export EDITOR=nano # Use nano instead of vi
|
|
```
|
|
|
|
**Note:** For complete documentation of all environment variables, see the [manpage](#manpage) or run `man passage` after installation.
|
|
|
|
## Git Integration
|
|
|
|
Initialize git repository:
|
|
|
|
```bash
|
|
passage git init
|
|
```
|
|
|
|
All password operations automatically commit to git (if initialized).
|
|
|
|
## Security
|
|
|
|
**IMPORTANT**: PassAGE uses a master password model. Every operation requires the master password set during `passage init`.
|
|
|
|
### Quick Security Overview
|
|
|
|
- **Master password**: Single password protects all stored passwords (never stored in plaintext)
|
|
- **AGE Scrypt encryption**: Industry-standard passphrase encryption
|
|
- **Argon2id verification**: Master password verified using Argon2id hash (memory-hard, resistant to brute force)
|
|
- **File permissions**: Store directory uses 0700, sensitive files use 0600
|
|
|
|
### Best Practices
|
|
|
|
1. Choose a strong master password (it cannot be recovered if forgotten)
|
|
2. Use full disk encryption
|
|
3. Back up your password store directory
|
|
4. See [SECURITY.md](SECURITY.md) for detailed security information
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
|
|
## Documentation
|
|
|
|
- **[INSTALL.md](INSTALL.md)** - Detailed installation instructions and troubleshooting
|
|
- **[SECURITY.md](SECURITY.md)** - Security implementation details
|
|
- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes
|
|
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute to the project
|
|
- **Manpage** - Run `man passage` after installation (source: `passage.1.md`)
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
PassAGE/
|
|
├── main.go # Entry point, command routing
|
|
├── commands.go # Command implementations
|
|
├── store.go # Core store operations
|
|
├── security.go # Security utilities (path validation, etc.)
|
|
├── memory.go # Secure memory management
|
|
├── clipboard.go # Clipboard operations
|
|
├── backup.go # Backup/restore functionality
|
|
├── go.mod # Go module definition
|
|
├── Makefile # Build and install targets
|
|
├── passage.1.md # Manpage source
|
|
└── *.md # Documentation files
|
|
```
|
|
|
|
For detailed code structure, see [CODE_STRUCTURE.md](CODE_STRUCTURE.md).
|
|
|
|
## License
|
|
|
|
This project uses AGE encryption. See LICENSE file for details.
|