view release on metacpan or  search on metacpan

bin/groupsecret  view on Meta::CPAN

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 L</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 C<STDOUT>. Create a file named F<vault-password> with the
following script, and make it executable (C<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 F<vault-password> and F<vault-password.yml> to your repository.

Now use L<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 C<--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 L<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 F<vault-password> which executes groupsecret to print the secret contained
in the F<vault-password.yml> file (which is actually the Vault password) to C<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.

=head1 BUGS

Please report any bugs or feature requests on the bugtracker website
L<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.

=head1 AUTHOR

Charles McGarvey <chazmcgarvey@brokenzipper.com>

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2017 by Charles McGarvey.

This is free software, licensed under:

  The MIT (X11) License

=cut