A command line based secrets manager.
secrets SUBCOMMAND [OPTIONS]
secrets (-V | --version)
secrets (-h | --help)
The -h
or --help
option can be used against any subcommand for
details.
The following options are common to all subcommands and can be placed anywhere within the command line arguments:
--secrets FILE Secrets file [~/.secrets]
--gpg FILE Alternative GnuPG binary [auto-detected]
By default, the latest version of GnuPG within your path (i.e., binaries
named gpg
and gpg2
) is used.
secrets keep [OPTIONS] SECRET_ID [SECRET]
Keep a secret with the identifier of SECRET_ID
. The secret can be
specified with the plaintext given in SECRET
, read through stdin
, or
generated following the rule policy provided by the options.
Options:
--force Overwrite the secret if it already exists
--length LENGTH Length [16]
--allowed CLASS Class of allowed characters [a-zA-Z0-9!?$%&=+_-]
--must-include CLASS Class of characters that must be included (this
option can be provided multiple times)
--expire SECONDS Delete the secret from the clipboard, if used,
after a time limit [30]
--reveal Write the secret to stdout, rather than to the
clipboard
The default policy will generate a secret with over 98 bits of entropy.
If the secrets file has not yet been created, you will be prompted for your GnuPG encryption and signing key IDs.
You mustn't supply more --must-include
arguments than the --length
,
otherwise an error will be raised. Also note that the --allowed
and
--must-include
classes may be mutually exclusive.
Warning Specifying the secret in the command line is dangerous, as
it will be preserved in your shell history. If you must do this, rather
than generating a random password or reading from stdin
, then you're
advised to add a layer of indirection. For example, in Bash:
secrets keep [OPTIONS] SECRET_ID "$(read -rsp "Secret: " X && echo -n "$X")"
Warning You should not recycle secrets, even those that are no longer in use. You will be warned and advised to keep a different secret if any duplication is detected.
secrets tell [OPTIONS] SECRET_ID
Tell the secret with the identifier of SECRET_ID
.
Options:
--expire SECONDS Delete the secret from the clipboard, if used,
after a time limit [30]
--reveal Write the secret to stdout, rather than to the
clipboard
secrets expose [OPTIONS]
Expose the list of all the available secret IDs.
Options:
--with-date Include the date the secret was kept
secrets forget [OPTIONS] SECRET_ID
Forget the secret with the identifier of SECRET_ID
.
Just copy or symlink secrets
to somewhere in your PATH
.
The following dependencies are required:
- Bash 4.2, or newer
- GnuPG (tested with 1.4, 2.0, 2.1 and 2.2)
- A means of calculating SHA256 digests (either
sha256sum
or OpenSSL)
You will need at least one valid encryption and signing key. Note that,
with GnuPG 2 (and later), your pinentry
program will be invoked to
acquire the key passphrase; this may not work correctly with a
terminal-based pinentry
.
For clipboard support, the following dependencies are needed:
- macOS:
pbcopy
andpbpaste
- Linux:
xclip
Every time a secret is kept, told or forgotten, it is logged in the secrets blockchain. In time, this can cause the database to become large and unwieldy. Moreover, if you have a need to revoke the GnuPG keys with which you signed or encrypted your database, you'll face similar problems. To this end, you can transfer just the kept secrets from one blockchain to another with the following command:
secrets expose --secrets OLD_BLOCKCHAIN | \
tee >(wc -l | xargs -I{} echo "Transferring {} secrets..." >&2) | \
xargs -n1 -I{} bash -c "secrets keep --secrets NEW_BLOCKCHAIN
'{}' \"\$(secrets tell --secrets OLD_BLOCKCHAIN --reveal '{}' 2>/dev/null)\"
>/dev/null"
Note that this process will take some time to complete (O(n) on the
number of secrets you have) and GnuPG may prompt you for various key
passphrases, throughout. The status of the new blockchain calculation
will be written to stderr
; it is important that this is not
redirected to /dev/null
, in case secrets
asks you to choose new
encryption or signing keys.
n.b., The term "blockchain" is used somewhat liberally!
secrets
was inspired by Jason A. Donenfeld's pass
,
but with several key differences:
-
Secrets are stored in a single database, so no metadata (from the secret IDs, for instance) is leaked.
pass-tomb
provides a similar function forpass
, but at the expense of complexity. -
secrets
has a much simpler interface, yet it provides all the useful functionality ofpass
, plus a few neat tricks of its own. -
The secrets database is structured as a self-validating blockchain audit log, for additional security.
-
No automatic Git integration, so you can use a VCS of your choice and/or manage the version control of your database how you prefer (if you wish).
Think of secrets
as pass-lite
!