+NAME
+
+ groupsecret - A simple tool for maintaining a shared group secret
+
+VERSION
+
+ version 0.303
+
+SYNOPSIS
+
+ groupsecret [--version] [--help] [-f <filepath>] [-k <privatekey_path>]
+ <command> [<args>]
+
+ groupsecret add-key [--embed] [--update] <publickey_path> ...
+
+ groupsecret delete-key <fingerprint>|<publickey_path> ...
+
+ groupsecret list-keys
+
+ groupsecret set-secret [--keep-passphrase] <path>|-|rand:<num_bytes>
+
+ groupsecret [print-secret] [--no-decrypt]
+
+DESCRIPTION
+
+ groupsecret is a program that makes it easy for groups to share a
+ secret between themselves without exposing the secret to anyone else.
+ It could be used, for example, by a team to share an ansible-vault(1)
+ password; see "ansible-vault" for more about this particular use case.
+
+ The goal of this program is to be easy to use and have few dependencies
+ (or only have dependencies users are likely to already have installed).
+
+ groupsecret works by encrypting a secret with a symmetric cipher
+ protected by a secure random passphrase which is itself encrypted by
+ one or more SSH2 RSA public keys. Only those who have access to one of
+ the corresponding private keys are able to decrypt the passphrase and
+ access the secret.
+
+ The encrypted secret and passphrase are stored in a single keyfile. You
+ can even commit the keyfile in a public repo or in a private repo where
+ some untrusted users may have read access; the secret is locked away to
+ all except those with a private key to a corresponding public key that
+ has been added to the keyfile.
+
+ The keyfile is just a YAML file, so it's human-readable (except of
+ course for the encrypted parts). This make it easy to add to version
+ control and work with diffs. You can edit the keyfile by hand if you
+ learn its very simple structure, but this program makes it even easier
+ to manage the keyfile.
+
+OPTIONS
+
+ --version
+
+ Print the program name and version to STDOUT, and exit.
+
+ Alias: -v
+
+ --help
+
+ Print the synopsis to STDOUT, and exit.
+
+ Alias: -h
+
+ --file=path
+
+ Specify a path to a keyfile which stores a secret and keys.
+
+ Defaults to the value of the environment variable "GROUPSECRET_KEYFILE"
+ or groupsecret.yml.
+
+ Alias: -f
+
+ --private-key=path
+
+ Specify a path to a PEM private key. This is used by some commands to
+ decrypt the passphrase that protects the secret and is ignored by
+ commands that don't need it.
+
+ Defaults to the value of the environment variable
+ "GROUPSECRET_PRIVATE_KEY" or ~/.ssh/id_rsa.
+
+ Alias: -k
+
+COMMANDS
+
+ add-key
+
+ groupsecret add-key path/to/mykey_rsa.pub
+
+ Adds one or more SSH2 RSA public keys to a keyfile. This allows the
+ secret contained within the keyfile to be accessed by whoever has the
+ corresponding private key.
+
+ If the --embed option is used, the public keys will be embeded in the
+ keyfile. This may be a useful way to make sure the actual keys are
+ available in the future since they could be needed to encrypt a new
+ passphrase if it ever needs to be changed. Keys that are not embedded
+ will be searched for in the filesystem; see "GROUPSECRET_PATH".
+
+ If the --update option is used and a key with the same fingerprint is
+ added, the new key will replace the existing key. The default behavior
+ is to skip existing keys.
+
+ If the keyfile is storing a secret, the passphrase protecting the
+ secret will need to be decrypted so that access to the secret can be
+ shared with the new key(s).
+
+ Alias: add-keys
+
+ delete-key
+
+ groupsecret delete-key MD5:89:b3:fb:76:6c:f9:56:8e:a8:1a:df:ba:1c:ba:7d:05
+ groupsecret delete-key path/to/mykey_rsa.pub
+
+ Deletes one or more keys from a keyfile. This prevents the secret
+ contained within the keyfile from being accessed by whoever has the
+ corresponding private key.
+
+ Of course, if the owners of the key(s) being removed have already had
+ access to the keyfile prior to their keys being removed, the secret is
+ already exposed to them. It usually makes sense to follow up this
+ command with a "set-secret" command in order to change the secret.
+
+ Aliases: delete-keys, remove-key, remove-keys
+
+ list-keys
+
+ groupsecret list-keys
+
+ Prints the keys that have access to the secret contained in the keyfile
+ to STDOUT, one per line in the following format:
+
+ <fingerprint> <comment>
+
+ set-secret
+
+ groupsecret set-secret path/to/secretfile.txt
+ groupsecret set-secret - <<END
+ > it's a secret to everybody
+ > END
+ groupsecret set-secret rand:48
+
+ Set or update the secret contained in a keyfile. The argument allows
+ you to add a secret from a file, from <STDIN>, or from a stream of
+ secure random bytes.
+
+ If the keyfile already contains a secret, it will be replaced by the
+ new secret. A keyfile can only contain one secret at a time. If you
+ think you want to store more than one secret at a time, store a tarball
+ instead.
+
+ By default, this will also change the passphrase protecting the secret
+ and re-encrypt the passphrase for each key currently in the keyfile.
+ This requires all of the public keys to be available (see
+ "GROUPSECRET_PATH"). If for some reason you want to protect the new
+ secret with the current passphrase, use the --keep-passphrase option;
+ this can be done without the public keys being available, but it will
+ require a private key to decrypt the passphrase.
+
+ Aliases: change-secret, update-secret
+
+ print-secret
+
+ groupsecret print-secret
+ groupsecret print-secret --no-decrypt
+
+ Print the secret contained in the keyfile to STDOUT.
+
+ If the --no-decrypt option is used, the secret will be printed in its
+ encrypted form.
+
+ This requires a private key.
+
+ Aliases: (no command), show-secret
+
+REQUIREMENTS
+
+ * OpenSSH <https://www.openssh.com> (commands: ssh-keygen(1))
+
+ * OpenSSL <https://www.openssl.org> (commands: openssl(1))
+
+INSTALL
+
+ There are a few ways to install groupsecret to your system. First, make
+ sure you first have the "REQUIREMENTS" installed.
+
+ Using cpanm
+
+ You can install groupsecret using cpanm. If you have a local perl
+ (plenv, perlbrew, etc.), you can just do this:
+
+ cpanm App::GroupSecret
+
+ to install the groupsecret executable and its Perl module dependencies.
+ The executable will be installed to your perl's bin path, like
+ ~/perl5/perlbrew/bin/groupsecret.
+
+ If you're installing to your system perl, you can do:
+
+ cpanm --sudo App::GroupSecret
+
+ to install the groupsecret executable to a system directory, like
+ /usr/local/bin/groupsecret (depending on your perl).
+
+ For developers
+
+ If you're a developer and want to hack on the source, clone the
+ repository and pull the dependencies:
+
+ git clone https://github.com/chazmcgarvey/groupsecret.git
+ cd groupsecret
+ cpanm Dist::Zilla
+ dzil authordeps --missing | cpanm
+ dzil listdeps --author --develop --missing | cpanm
+
+ENVIRONMENT
+
+ GROUPSECRET_KEYFILE
+
+ If set, this program will use the value as a path to the keyfile. The
+ "--file=path" option takes precedence if used.
+
+ GROUPSECRET_PRIVATE_KEY
+
+ If set, this program will use the value as a path to private key used
+ for decryption. The "--private-key=path" option takes precedence if
+ used.
+
+ GROUPSECRET_PATH
+
+ The value of this variable should be a colon-separated list of
+ directories in which to search for public keys. By default, the actual
+ keys are not embedded in keyfiles, but they may be needed to encrypt a
+ new passphrase if it ever needs to be changed. Keys that are not
+ embedded will be searched for in the filesystem based on the value of
+ this environment variable.
+
+ Defaults to .:keys:$HOME/.ssh.
+
+EXAMPLES
+
+ ansible-vault
+
+ Ansible Vault <http://docs.ansible.com/ansible/latest/vault.html> is a
+ great way to securely store secret configuration variables for use in
+ your playbooks. Vaults are secured using a password, which is okay if
+ you're the only one who will need to unlock the Vault, but as soon as
+ you add team members who also need to access the Vault you are then
+ faced with how to manage knowledge of the password. When a team member
+ leaves, you'll also need to change the Vault password which means
+ you'll need a way to communicate the change to other team members who
+ also have access. This becomes a burden to manage.
+
+ You can use groupsecret to manage this very easily by storing the Vault
+ password in a groupsecret keyfile. That way, you can add or remove keys
+ and change the secret (the Vault password) at any time without
+ affecting the team members that still have access. Team members always
+ use their own SSH2 RSA keys to unlock the Vault, so no new password
+ ever needs to be communicated out.
+
+ To set this up, first create a keyfile with the public keys of everyone
+ on your team:
+
+ groupsecret -f vault-password.yml add-keys keys/*_rsa.pub
+
+ Then set the secret in the keyfile to a long random number:
+
+ groupsecret -f vault-password.yml set-secret rand:48
+
+ This will be the Ansible Vault password. You can see it if you want
+ using the "print-secret" command, but you don't need to.
+
+ Then we'll take advantage of the fact that an Ansible Vault password
+ file can be an executable program that prints the Vault password to
+ STDOUT. Create a file named vault-password with the following script,
+ and make it executable (chmod +x vault-password):
+
+ #!/bin/sh
+ # Use groupsecret <https://github.com/chazmcgarvey/groupsecret> to access the Vault password
+ exec ${GROUPSECRET:-groupsecret} -f vault-password.yml print-secret
+
+ Commit both vault-password and vault-password.yml to your repository.
+
+ Now use ansible-vault(1) to add files to the Vault:
+
+ ansible-vault --vault-id=vault-password encrypt foo.yml bar.yml baz.yml
+
+ These examples show the Ansible 2.4+ syntax, but it can be adapted for
+ earlier versions. The significant part of this command is
+ --vault-id=vault-password which refers to the executable script we
+ created earlier. You can use that argument with other ansible-vault
+ commands to view or edit the encrypted files.
+
+ You can also pass that same argument to ansible-playbook(1) in order to
+ use the Vault in playbooks that refer to the encrypted variables:
+
+ ansible-playbook -i myinventory --vault-id=vault-password site.yml
+
+ What this does is execute vault-password which executes groupsecret to
+ print the secret contained in the vault-password.yml file (which is
+ actually the Vault password) to STDOUT. In order to do this,
+ groupsecret will decrypt the keyfile passphrase using any one of the
+ private keys that have associated public keys added to the keyfile.
+
+ That's it! Pretty easy.
+
+ If and when you need to change the Vault password (such as when a team
+ member leaves), you can follow this procedure which is probably mostly
+ self-explanatory:
+
+ groupsecret -f vault-password.yml delete-key keys/revoked/jdoe_rsa.pub
+ groupsecret -f vault-password.yml print-secret >old-vault-password.txt
+ groupsecret -f vault-password.yml set-secret rand:48
+ echo "New Vault password: $(groupsecret -f vault-password.yml)"
+ ansible-vault --vault-id=old-vault-password.txt rekey foo.yml bar.yml baz.yml
+ # You will be prompted for the new Vault password which you can copy from the output above.
+ rm -f old-vault-password.txt
+
+ This removes access to the keyfile secret and to the Ansible Vault.
+ Don't forget that you may also want to change the variables being
+ protected by the Vault. After all, those secrets are the actual things
+ we're protecting by doing all of this, and an exiting team member may
+ have decided to take a copy of those variables for himself before
+ leaving.
+
+BUGS
+
+ Please report any bugs or feature requests on the bugtracker website
+ https://github.com/chazmcgarvey/groupsecret/issues
+
+ When submitting a bug or request, please include a test-file or a patch
+ to an existing test-file that illustrates the bug or desired feature.
+
+AUTHOR
+
+ Charles McGarvey <chazmcgarvey@brokenzipper.com>
+
+COPYRIGHT AND LICENSE
+
+ This software is Copyright (c) 2017 by Charles McGarvey.
+
+ This is free software, licensed under:
+
+ The MIT (X11) License
+