3 # ABSTRACT: A simple tool for maintaining a shared group secret
7 groupsecret [--version] [--help] [-f <filepath>] [-k <privatekey_path>]
10 groupsecret add-key [--embed] [--update] <publickey_path> ...
12 groupsecret delete-key <fingerprint>|<publickey_path> ...
16 groupsecret set-secret [--keep-passphrase] <path>|-|rand:<num_bytes>
18 groupsecret [print-secret] [--no-decrypt]
22 L<groupsecret> is a program that makes it easy for groups to share a secret between themselves
23 without exposing the secret to anyone else. It could be used, for example, by a team to share an
24 L<ansible-vault(1)> password.
26 The goal of this program is to be easy to use and have few dependencies (or only have dependencies
27 users are likely to already have installed).
29 L<groupsecret> works by encrypting a secret with a symmetric cipher protected by a secure random
30 passphrase which is itself encrypted by one or more SSH2 RSA public keys. Only those who have access
31 to one of the corresponding private keys are able to decrypt the passphrase and access the secret.
33 The encrypted secret and passphrase are stored in a single keyfile. You can even commit the keyfile
34 in a public repo or in a private repo where some untrusted users may have read access; the secret is
35 locked away to all except those with a private key to a corresponding public key that has been added
38 The keyfile is just a YAML file, so it's human-readable (except of course for the encrypted parts).
39 This make it easy to add to version control and work with diffs. You can edit the keyfile by hand if
40 you learn its very simple structure, but this program makes it even easier to manage the keyfile.
46 Print the program name and version to C<STDOUT>, and exit.
52 Print the synopsis to C<STDOUT>, and exit.
58 Specify a path to a keyfile which stores a secret and keys.
60 Defaults to the value of the environment variable C<GROUPSECRET_KEYFILE> or F<groupsecret.yml>.
64 =head2 --private-key=path
66 Specify a path to a PEM private key. This is used by some commands to decrypt the passphrase that
67 protects the secret and is ignored by commands that don't need it.
69 Defaults to the value of the environment variable L</GROUPSECRET_PRIVATE_KEY>. If that is unset, it
70 defaults to F<~/.ssh/id_rsa>.
78 groupsecret add-key path/to/mykey_rsa.pub
80 Adds one or more SSH2 RSA public keys to a keyfile. This allows the secret contained within the
81 keyfile to be accessed by whoever has the corresponding private key.
83 If the C<--embed> option is used, the public keys will be embeded in the keyfile. This may be
84 a useful way to make sure the actual keys are available in the future since they could be needed to
85 encrypt a new passphrase if it ever needs to be changed. Keys that are not embedded will be searched
86 for in the filesystem; see L</GROUPSECRET_PATH>.
88 If the C<--update> option is used and a key with the same fingerprint is added, the new key will
89 replaced the existing key. The default behavior is to skip existing keys.
91 If the keyfile is storing a secret, the passphrase protecting the secret will need to be decrypted
92 so that access to the secret can be shared with the new key(s).
98 groupsecret delete-key MD5:89:b3:fb:76:6c:f9:56:8e:a8:1a:df:ba:1c:ba:7d:05
99 groupsecret delete-key path/to/mykey_rsa.pub
101 Deletes one or more keys from a keyfile. This prevents the secret contained within the keyfile from
102 being accessed by whoever has the corresponding private key.
104 Of course, if the owners of the key(s) being removed have already had access to the keyfile prior to
105 their keys being removed, the secret is already exposed to them. It usually makes sense to follow up
106 this command with a L</set-secret> command in order to change the secret.
108 Aliases: C<delete-keys>, C<remove-key>, C<remove-keys>
112 groupsecret list-keys
114 Prints the keys that have access to the secret contained in the keyfile to C<STDOUT>, one per line
115 in the following format:
117 <fingerprint> <comment>
121 groupsecret set-secret path/to/secretfile.txt
122 groupsecret set-secret - <<END
123 > it's a secret to everybody
125 groupsecret set-secret rand:48
127 Set or update the secret contained in a keyfile. The argument allows you to add a secret from
128 a file, from <STDIN>, or from a stream of secure random bytes.
130 If the keyfile already contains a secret, it will be replaced by the new secret. A keyfile can only
131 contain one secret at a time. If you think you want to store more than one secret at a time, store
134 By default, this will also change the passphrase protecting the secret and re-encrypt the passphrase
135 for each key currently in the keyfile. This requires all of the public keys to be available (see
136 L</GROUPSECRET_PATH>). If for some reason you want to protect the new secret with the current
137 passphrase, use the C<--keep-passphrase> option; this can be done without the public keys being
138 available, but it will require a private key to decrypt the passphrase.
140 Aliases: C<change-secret>, C<update-secret>
144 groupsecret print-secret
145 groupsecret print-secret --no-decrypt
147 Print the secret contained in the keyfile to C<STDOUT>.
149 If the C<--no-decrypt> option is used, the secret will be printed in its encrypted form.
151 This requires a private key.
153 Aliases: (no command), C<show-secret>
158 * L<OpenSSH|https://www.openssh.com> (commands: L<ssh-keygen(1)>)
159 * L<OpenSSL|https://www.openssl.org> (commands: L<openssl(1)>)
163 There are a few ways to install groupsecret to your system. First, make sure you first have the
164 L</REQUIREMENTS> installed.
168 You can install groupsecret using L<cpanm>. If you have a local perl (plenv, perlbrew, etc.), you
171 cpanm App::GroupSecret
173 to install the F<groupsecret> executable and its Perl module dependencies. The executable will be
174 installed to your perl's bin path, like F<~/perl5/perlbrew/bin/groupsecret>.
176 If you're installing to your system perl, you can do:
178 cpanm --sudo App::GroupSecret
180 to install the F<groupsecret> executable to a system directory, like F</usr/local/bin/groupsecret>
181 (depending on your perl).
183 =head2 For developers
185 If you're a developer and want to hack on the source, clone the repository and pull the
188 git clone https://github.com/chazmcgarvey/groupsecret.git
191 dzil authordeps --missing | cpanm
192 dzil listdeps --author --develop --missing | cpanm
196 =head2 GROUPSECRET_KEYFILE
198 If set, this program will use the value as a path to the keyfile. The L</--file=path> option takes
199 precedence if it is used.
201 =head2 GROUPSECRET_PRIVATE_KEY
203 If set, this program will use the value as a path to the keyfile. The L</--private-key=path> option
204 takes precedence if it is used.
206 =head2 GROUPSECRET_PATH
208 The value of this variable should be a colon-separated list of directories in which to search for
209 public keys. By default, the actual keys are not embedded in keyfiles, but they may be needed to
210 encrypt a new passphrase if it ever needs to be changed. Keys that are not embedded will be searched
211 for in the filesystem based on the value of this environment variable.
213 Defaults to C<.:keys:$HOME/.ssh>.
217 use warnings FATAL => 'all';
220 our $VERSION = '9999.999'; # VERSION
222 use App::GroupSecret;
224 App::GroupSecret->new->main(@ARGV);