3 groupsecret - A simple tool for maintaining a shared group secret
11 groupsecret [--version] [--help] [-f <filepath>] [-k <privatekey_path>]
14 groupsecret add-key [--embed] [--update] <publickey_path> ...
16 groupsecret delete-key <fingerprint>|<publickey_path> ...
20 groupsecret set-secret [--keep-passphrase] <path>|-|rand:<num_bytes>
22 groupsecret [print-secret] [--no-decrypt]
26 groupsecret is a program that makes it easy for groups to share a
27 secret between themselves without exposing the secret to anyone else.
28 It could be used, for example, by a team to share an ansible-vault(1)
29 password; see "ansible-vault" for more about this particular use case.
31 The goal of this program is to be easy to use and have few dependencies
32 (or only have dependencies users are likely to already have installed).
34 groupsecret works by encrypting a secret with a symmetric cipher
35 protected by a secure random passphrase which is itself encrypted by
36 one or more SSH2 RSA public keys. Only those who have access to one of
37 the corresponding private keys are able to decrypt the passphrase and
40 The encrypted secret and passphrase are stored in a single keyfile. You
41 can even commit the keyfile in a public repo or in a private repo where
42 some untrusted users may have read access; the secret is locked away to
43 all except those with a private key to a corresponding public key that
44 has been added to the keyfile.
46 The keyfile is just a YAML file, so it's human-readable (except of
47 course for the encrypted parts). This make it easy to add to version
48 control and work with diffs. You can edit the keyfile by hand if you
49 learn its very simple structure, but this program makes it even easier
50 to manage the keyfile.
56 Print the program name and version to STDOUT, and exit.
62 Print the synopsis to STDOUT, and exit.
68 Specify a path to a keyfile which stores a secret and keys.
70 Defaults to the value of the environment variable "GROUPSECRET_KEYFILE"
77 Specify a path to a PEM private key. This is used by some commands to
78 decrypt the passphrase that protects the secret and is ignored by
79 commands that don't need it.
81 Defaults to the value of the environment variable
82 "GROUPSECRET_PRIVATE_KEY" or ~/.ssh/id_rsa.
90 groupsecret add-key path/to/mykey_rsa.pub
92 Adds one or more SSH2 RSA public keys to a keyfile. This allows the
93 secret contained within the keyfile to be accessed by whoever has the
94 corresponding private key.
96 If the --embed option is used, the public keys will be embeded in the
97 keyfile. This may be a useful way to make sure the actual keys are
98 available in the future since they could be needed to encrypt a new
99 passphrase if it ever needs to be changed. Keys that are not embedded
100 will be searched for in the filesystem; see "GROUPSECRET_PATH".
102 If the --update option is used and a key with the same fingerprint is
103 added, the new key will replace the existing key. The default behavior
104 is to skip existing keys.
106 If the keyfile is storing a secret, the passphrase protecting the
107 secret will need to be decrypted so that access to the secret can be
108 shared with the new key(s).
114 groupsecret delete-key MD5:89:b3:fb:76:6c:f9:56:8e:a8:1a:df:ba:1c:ba:7d:05
115 groupsecret delete-key path/to/mykey_rsa.pub
117 Deletes one or more keys from a keyfile. This prevents the secret
118 contained within the keyfile from being accessed by whoever has the
119 corresponding private key.
121 Of course, if the owners of the key(s) being removed have already had
122 access to the keyfile prior to their keys being removed, the secret is
123 already exposed to them. It usually makes sense to follow up this
124 command with a "set-secret" command in order to change the secret.
126 Aliases: delete-keys, remove-key, remove-keys
130 groupsecret list-keys
132 Prints the keys that have access to the secret contained in the keyfile
133 to STDOUT, one per line in the following format:
135 <fingerprint> <comment>
139 groupsecret set-secret path/to/secretfile.txt
140 groupsecret set-secret - <<END
141 > it's a secret to everybody
143 groupsecret set-secret rand:48
145 Set or update the secret contained in a keyfile. The argument allows
146 you to add a secret from a file, from <STDIN>, or from a stream of
149 If the keyfile already contains a secret, it will be replaced by the
150 new secret. A keyfile can only contain one secret at a time. If you
151 think you want to store more than one secret at a time, store a tarball
154 By default, this will also change the passphrase protecting the secret
155 and re-encrypt the passphrase for each key currently in the keyfile.
156 This requires all of the public keys to be available (see
157 "GROUPSECRET_PATH"). If for some reason you want to protect the new
158 secret with the current passphrase, use the --keep-passphrase option;
159 this can be done without the public keys being available, but it will
160 require a private key to decrypt the passphrase.
162 Aliases: change-secret, update-secret
166 groupsecret print-secret
167 groupsecret print-secret --no-decrypt
169 Print the secret contained in the keyfile to STDOUT.
171 If the --no-decrypt option is used, the secret will be printed in its
174 This requires a private key.
176 Aliases: (no command), show-secret
180 * OpenSSH <https://www.openssh.com> (commands: ssh-keygen(1))
182 * OpenSSL <https://www.openssl.org> (commands: openssl(1))
186 There are a few ways to install groupsecret to your system. First, make
187 sure you first have the "REQUIREMENTS" installed.
191 You can install groupsecret using cpanm. If you have a local perl
192 (plenv, perlbrew, etc.), you can just do this:
194 cpanm App::GroupSecret
196 to install the groupsecret executable and its Perl module dependencies.
197 The executable will be installed to your perl's bin path, like
198 ~/perl5/perlbrew/bin/groupsecret.
200 If you're installing to your system perl, you can do:
202 cpanm --sudo App::GroupSecret
204 to install the groupsecret executable to a system directory, like
205 /usr/local/bin/groupsecret (depending on your perl).
209 If you're a developer and want to hack on the source, clone the
210 repository and pull the dependencies:
212 git clone https://github.com/chazmcgarvey/groupsecret.git
215 dzil authordeps --missing | cpanm
216 dzil listdeps --author --develop --missing | cpanm
222 If set, this program will use the value as a path to the keyfile. The
223 "--file=path" option takes precedence if used.
225 GROUPSECRET_PRIVATE_KEY
227 If set, this program will use the value as a path to private key used
228 for decryption. The "--private-key=path" option takes precedence if
233 The value of this variable should be a colon-separated list of
234 directories in which to search for public keys. By default, the actual
235 keys are not embedded in keyfiles, but they may be needed to encrypt a
236 new passphrase if it ever needs to be changed. Keys that are not
237 embedded will be searched for in the filesystem based on the value of
238 this environment variable.
240 Defaults to .:keys:$HOME/.ssh.
246 Ansible Vault <http://docs.ansible.com/ansible/latest/vault.html> is a
247 great way to securely store secret configuration variables for use in
248 your playbooks. Vaults are secured using a password, which is okay if
249 you're the only one who will need to unlock the Vault, but as soon as
250 you add team members who also need to access the Vault you are then
251 faced with how to manage knowledge of the password. When a team member
252 leaves, you'll also need to change the Vault password which means
253 you'll need a way to communicate the change to other team members who
254 also have access. This becomes a burden to manage.
256 You can use groupsecret to manage this very easily by storing the Vault
257 password in a groupsecret keyfile. That way, you can add or remove keys
258 and change the secret (the Vault password) at any time without
259 affecting the team members that still have access. Team members always
260 use their own SSH2 RSA keys to unlock the Vault, so no new password
261 ever needs to be communicated out.
263 To set this up, first create a keyfile with the public keys of everyone
266 groupsecret -f vault-password.yml add-keys keys/*_rsa.pub
268 Then set the secret in the keyfile to a long random number:
270 groupsecret -f vault-password.yml set-secret rand:48
272 This will be the Ansible Vault password. You can see it if you want
273 using the "print-secret" command, but you don't need to.
275 Then we'll take advantage of the fact that an Ansible Vault password
276 file can be an executable program that prints the Vault password to
277 STDOUT. Create a file named vault-password with the following script,
278 and make it executable (chmod +x vault-password):
281 # Use groupsecret <https://github.com/chazmcgarvey/groupsecret> to access the Vault password
282 exec ${GROUPSECRET:-groupsecret} -f vault-password.yml print-secret
284 Commit both vault-password and vault-password.yml to your repository.
286 Now use ansible-vault(1) to add files to the Vault:
288 ansible-vault --vault-id=vault-password encrypt foo.yml bar.yml baz.yml
290 These examples show the Ansible 2.4+ syntax, but it can be adapted for
291 earlier versions. The significant part of this command is
292 --vault-id=vault-password which refers to the executable script we
293 created earlier. You can use that argument with other ansible-vault
294 commands to view or edit the encrypted files.
296 You can also pass that same argument to ansible-playbook(1) in order to
297 use the Vault in playbooks that refer to the encrypted variables:
299 ansible-playbook -i myinventory --vault-id=vault-password site.yml
301 What this does is execute vault-password which executes groupsecret to
302 print the secret contained in the vault-password.yml file (which is
303 actually the Vault password) to STDOUT. In order to do this,
304 groupsecret will decrypt the keyfile passphrase using any one of the
305 private keys that have associated public keys added to the keyfile.
307 That's it! Pretty easy.
309 If and when you need to change the Vault password (such as when a team
310 member leaves), you can follow this procedure which is probably mostly
313 groupsecret -f vault-password.yml delete-key keys/revoked/jdoe_rsa.pub
314 groupsecret -f vault-password.yml print-secret >old-vault-password.txt
315 groupsecret -f vault-password.yml set-secret rand:48
316 echo "New Vault password: $(groupsecret -f vault-password.yml)"
317 ansible-vault --vault-id=old-vault-password.txt rekey foo.yml bar.yml baz.yml
318 # You will be prompted for the new Vault password which you can copy from the output above.
319 rm -f old-vault-password.txt
321 This removes access to the keyfile secret and to the Ansible Vault.
322 Don't forget that you may also want to change the variables being
323 protected by the Vault. After all, those secrets are the actual things
324 we're protecting by doing all of this, and an exiting team member may
325 have decided to take a copy of those variables for himself before
330 Please report any bugs or feature requests on the bugtracker website
331 https://github.com/chazmcgarvey/groupsecret/issues
333 When submitting a bug or request, please include a test-file or a patch
334 to an existing test-file that illustrates the bug or desired feature.
338 Charles McGarvey <chazmcgarvey@brokenzipper.com>
340 COPYRIGHT AND LICENSE
342 This software is Copyright (c) 2017 by Charles McGarvey.
344 This is free software, licensed under:
346 The MIT (X11) License