{"id":51043739,"url":"https://github.com/floatpane/go-secretbox","last_synced_at":"2026-06-22T12:02:23.910Z","repository":{"id":361669909,"uuid":"1255234326","full_name":"floatpane/go-secretbox","owner":"floatpane","description":"Password-based encryption for data at rest, in Go. Argon2id + AES-256-GCM","archived":false,"fork":false,"pushed_at":"2026-06-19T10:53:15.000Z","size":102,"stargazers_count":2,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-19T12:27:44.657Z","etag":null,"topics":["aead","authenticated-encryption","cipher","crypto","cryptography","data-protection","data-security","decryption","encryption","go","golang","golang-library","kdf","key-derivation","nacl","secret-management","secretbox","secrets-management","security","vault"],"latest_commit_sha":null,"homepage":"https://secretbox.floatpane.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/floatpane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"floatpane"}},"created_at":"2026-05-31T15:21:03.000Z","updated_at":"2026-06-05T17:03:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/floatpane/go-secretbox","commit_stats":null,"previous_names":["floatpane/go-secretbox"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/floatpane/go-secretbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floatpane%2Fgo-secretbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floatpane%2Fgo-secretbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floatpane%2Fgo-secretbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floatpane%2Fgo-secretbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/floatpane","download_url":"https://codeload.github.com/floatpane/go-secretbox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floatpane%2Fgo-secretbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34647750,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aead","authenticated-encryption","cipher","crypto","cryptography","data-protection","data-security","decryption","encryption","go","golang","golang-library","kdf","key-derivation","nacl","secret-management","secretbox","secrets-management","security","vault"],"created_at":"2026-06-22T12:02:23.151Z","updated_at":"2026-06-22T12:02:23.899Z","avatar_url":"https://github.com/floatpane.png","language":"Go","funding_links":["https://github.com/sponsors/floatpane"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# go-secretbox\n\n**Password-based encryption for data at rest, in Go. Argon2id + AES-256-GCM, done right.**\n\n[![Go Version](https://img.shields.io/github/go-mod/go-version/floatpane/go-secretbox)](https://golang.org)\n[![Go Reference](https://pkg.go.dev/badge/github.com/floatpane/go-secretbox.svg)](https://pkg.go.dev/github.com/floatpane/go-secretbox)\n[![GitHub release (latest by date)](https://img.shields.io/github/v/release/floatpane/go-secretbox)](https://github.com/floatpane/go-secretbox/releases)\n[![CI](https://github.com/floatpane/go-secretbox/actions/workflows/ci.yml/badge.svg)](https://github.com/floatpane/go-secretbox/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n\u003c/div\u003e\n\n`go-secretbox` is the boring, correct version of the encryption code everyone ends up writing once: stretch a password with a slow KDF, encrypt with an authenticated cipher, prepend the nonce, store a salt, verify the password without storing it. It gets the parts that are easy to get wrong — nonce generation, constant-time checks, key zeroing, self-describing formats — out of your codebase.\n\nIt was extracted from [matcha](https://github.com/floatpane/matcha)'s \"secure mode,\" which encrypts a mail client's config and caches behind a master password.\n\n## Features\n\n- **Two layers, one set of primitives.**\n  - `Seal` / `Unseal` — one-shot, self-describing blobs. The salt and KDF parameters travel *inside* the ciphertext, so a blob is decryptable years later with only the password.\n  - `Vault` — the long-lived \"secure mode\" pattern: a metadata file with a salt + encrypted sentinel, an in-memory session key, transparent file encryption, password change, and key rotation.\n- **Sentinel password verification.** No password, and no hash of it, is ever stored. `Unlock` decrypts a known sentinel and compares in constant time.\n- **Pluggable KDF and cipher.** Argon2id + AES-256-GCM by default; swap in XChaCha20-Poly1305 (or your own `KDF`/`Cipher`) via options. The choice is recorded in metadata, so `Unlock`/`Unseal` always reconstruct the right algorithm.\n- **Key hygiene.** Derived keys are zeroed after use and on `Lock`. `Rekey` decrypts-all-then-rotates so a failure can't leave files stranded.\n- **Small surface, single dependency.** Just `golang.org/x/crypto`.\n\n## Install\n\n```bash\ngo get github.com/floatpane/go-secretbox\n```\n\nRequires Go 1.26+.\n\n## Usage\n\n### One-shot: encrypt a blob with a password\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"log\"\n\n    \"github.com/floatpane/go-secretbox\"\n)\n\nfunc main() {\n    blob, err := secretbox.Seal([]byte(\"attack at dawn\"), \"correct horse battery staple\")\n    if err != nil {\n        log.Fatal(err)\n    }\n    // blob is safe to write to disk — it carries its own salt + KDF params.\n\n    plain, err := secretbox.Unseal(blob, \"correct horse battery staple\")\n    if err != nil {\n        log.Fatal(err) // ErrDecrypt on wrong password or tampering\n    }\n    fmt.Println(string(plain)) // attack at dawn\n}\n```\n\n### Vault: \"secure mode\" with a master password\n\n```go\nv := secretbox.NewVault(\"/home/me/.config/app/secure.meta\")\n\n// First run — turn secure mode on.\nif !v.Initialized() {\n    if err := v.Init(masterPassword); err != nil {\n        log.Fatal(err)\n    }\n}\n\n// Later runs — unlock with the master password.\nif err := v.Unlock(masterPassword); err != nil {\n    log.Fatal(err) // ErrWrongPassword\n}\ndefer v.Lock() // zeroes the session key\n\n// Transparent file encryption while unlocked.\nv.WriteFile(\"/home/me/.config/app/config.json\", configBytes, 0o600)\ndata, _ := v.ReadFile(\"/home/me/.config/app/config.json\")\n```\n\n### Rotate the master password (and migrate files)\n\n```go\n// Decrypts every file with the old key, rotates the vault, re-encrypts with\n// the new key. Phase-ordered so a crash can't strand your data.\nerr := v.Rekey(newPassword, []string{\n    \"/home/me/.config/app/config.json\",\n    \"/home/me/.config/app/cache.db\",\n})\n```\n\n### Choose a different cipher\n\n```go\nv := secretbox.NewVault(metaPath,\n    secretbox.WithCipher(secretbox.ChaCha20Poly1305{}),\n    secretbox.WithKDF(secretbox.NewArgon2id(secretbox.Argon2idParams{\n        Time: 4, Memory: 128 * 1024, Threads: 4,\n    })),\n)\n```\n\n## Defaults\n\n| Knob | Default | Notes |\n|------|---------|-------|\n| KDF | Argon2id | `Time=3, Memory=64 MiB, Threads=4` (interactive-login baseline) |\n| Cipher | AES-256-GCM | 32-byte key, 12-byte random nonce, prepended to ciphertext |\n| Salt | 16 random bytes | fresh per `Init`/`Seal`/`Rekey` |\n| Sentinel | `secretbox-verified` | encrypted under the key, compared constant-time on `Unlock` |\n\n## What this is not\n\n- **Not key management.** It protects data *with a password*. If the password leaks, so does the data.\n- **Not memory-hardened against root.** While unlocked, the key lives in process memory. A privileged local attacker (or a core dump) can read it. `Lock` shortens that window; it does not close it against an attacker with `ptrace`.\n- **Not a replacement for an OS keyring.** It's complementary — matcha uses the keyring when secure mode is off and a `Vault` when it's on.\n\n## Documentation\n\nFull API reference: [pkg.go.dev/github.com/floatpane/go-secretbox](https://pkg.go.dev/github.com/floatpane/go-secretbox)\n\nGuides and diagrams: see [`docs/`](docs/).\n\n## Sister projects\n\n| Project | Role |\n|---------|------|\n| [floatpane/matcha](https://github.com/floatpane/matcha) | Reference consumer — uses this library for its config/cache \"secure mode.\" |\n| [floatpane/go-uds-jsonrpc](https://github.com/floatpane/go-uds-jsonrpc) | Sibling extraction — local daemon JSON-RPC over Unix sockets. |\n\n## Contributing\n\nPRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Security\n\nReport vulnerabilities privately via [SECURITY.md](SECURITY.md).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloatpane%2Fgo-secretbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffloatpane%2Fgo-secretbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloatpane%2Fgo-secretbox/lists"}