diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 119 |
1 files changed, 119 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..773dc35 --- /dev/null +++ b/README.md @@ -0,0 +1,119 @@ +# yubisigner-cli + +Command-line version of [yubisigner](https://github.com/Ch1ffr3punk/yubisigner) by Stefan Claas, for signing files with YubiKey PIV Ed25519 keys. + +## What is this? + +This is a CLI tool extracted from the original yubisigner GUI application. It provides the same cryptographic signing functionality but in a command-line interface suitable for scripting and automation. + +## Why CLI? + +The original yubisigner is a Fyne GUI application. To integrate YubiKey PIV signing with automated workflows like NeoMutt mail2news posting, a CLI version was needed. + +## How it was created + +This tool was created by extracting the core signing logic from the original `yubisigner.go`: + +### Extracted functions (with original line references) + +| Function | Original lines | Purpose | +|----------|---------------|---------| +| `normalizeToCRLF` | 538-544 | RFC-compliant line ending normalization | +| `ensureUTF8` | 547-552 | UTF-8 validation and sanitization | +| `calculateHashesRAM` | 1621-1640 | Calculate 4 hashes (RIPEMD-256, SHA-256, SM3, Streebog-256) | +| `formatHashes` | 1746-1766 | Format hashes with right-aligned names | +| `formatSignatureRFC` | 1996-2007 | Format signature with 64-char line breaks | +| `openYubiKey` | 2073-2092 | Open YubiKey at specified index | +| `signEd25519Data` | 1843-1862 | Sign data with Ed25519 (PIV slot 9c) | +| `signDataInternal` | 1769-1840 | Main signing workflow (Ed25519 only) | + +### Constants preserved + +- `Ed25519SignatureSize`, `Ed25519PublicKeySize`, `Ed25519CombinedSize` (lines 95-99) +- `AlgorithmED25519` (lines 69-73) + +### Changes from original + +1. **GUI removed**: All Fyne GUI code stripped out +2. **Ed25519 only**: Only Ed25519 support (original supports ECDSA/RSA too) +3. **CLI flags**: Added flag parsing for command-line arguments +4. **No PKCS#11**: Direct YubiKey PIV access only (no PKCS#11 smartcard support) +5. **Simplified output**: Direct signature file write (no GUI dialogs) + +The core cryptographic logic is **exactly the same** as the original yubisigner. All signing functions are verbatim copies with comments indicating source line numbers. + +## Requirements + +- Go 1.21+ +- YubiKey with PIV Ed25519 key in slot 9c (Signature slot) +- Dependencies: + - `github.com/go-piv/piv-go/v2/piv` + - `github.com/c0mm4nd/go-ripemd` + - `github.com/martinlindhe/gogost/gost34112012256` + - `github.com/tjfoc/gmsm/sm3` + +## Build + +```bash +go build -o yubisigner-cli main.go +``` + +## Usage + +```bash +yubisigner-cli \ + --input <file> \ + --author "Your Name" \ + --email "you@example.com" \ + --url "https://example.com" \ + --comment "Optional comment" +``` + +Output: `<file>.sig` (detached signature) + +### Optional arguments + +- `--email` (default: "n/a") +- `--url` (default: "n/a") +- `--telefax` (default: "n/a") +- `--comment` (default: "n/a") +- `--pin` (PIN will be prompted if not provided) +- `--output` (default: `<input>.sig`) + +## Signature format + +Identical to original yubisigner: + +``` +Author: Gab Virebent +Signed at: 2026-05-30 23:15:00 +0000 +Filename: message.txt +File size: 1234 bytes +Email: gabriel1@virebent.art +Telefax: n/a +URL: https://contact.virebent.art +Comment: Posted via NeoMutt mail2news +RIPEMD-256: abc123... + SHA-256: def456... + SM3: 789abc... +Streebog-256: fedcba... +-----BEGIN YUBISIGNER ED25519 SIGNATURE----- +0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef +... +-----END YUBISIGNER ED25519 SIGNATURE----- +``` + +## Integration with NeoMutt + +See [neomutt-config](https://git.virebent.art/virebent/neomutt-config) for mail2news integration with automatic YubiKey signing via the `vim-yubisigner` wrapper. + +## License + +MIT (same as original yubisigner) + +## Credits + +- **Stefan Claas** ([@Ch1ffr3punk](https://github.com/Ch1ffr3punk)): Original yubisigner GUI application +- **Gab Virebent**: CLI extraction for automation workflows + +All cryptographic logic is Stefan's work. This is purely a CLI wrapper around his signing implementation. |