App-GroupSecret

 view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    
        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.

README  view on Meta::CPAN

    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

bin/groupsecret  view on Meta::CPAN

    groupsecret list-keys

    groupsecret set-secret [--keep-passphrase] <path>|-|rand:<num_bytes>

    groupsecret [print-secret] [--no-decrypt]

=head1 DESCRIPTION

L<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
L<ansible-vault(1)> password; see L</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

bin/groupsecret  view on Meta::CPAN

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 C<.:keys:$HOME/.ssh>.

=head1 EXAMPLES

=head2 ansible-vault

L<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 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>