view release on metacpan or  search on metacpan

bin/groupsecret  view on Meta::CPAN

#!perl
# PODNAME: groupsecret
# ABSTRACT: A simple tool for maintaining a shared group secret


use warnings FATAL => 'all';
use strict;

our $VERSION = '0.304'; # VERSION

use App::GroupSecret;

App::GroupSecret->new->main(@ARGV);
exit;

__END__

=pod

=encoding UTF-8

=head1 NAME

groupsecret - A simple tool for maintaining a shared group secret

=head1 VERSION

version 0.304

=head1 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]

=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
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.

=head1 OPTIONS

=head2 --version

Print the program name and version to C<STDOUT>, and exit.

Alias: C<-v>

=head2 --help

Print the synopsis to C<STDOUT>, and exit.

Alias: C<-h>

=head2 --file=path

Specify a path to a keyfile which stores a secret and keys.

Defaults to the value of the environment variable L</GROUPSECRET_KEYFILE> or F<groupsecret.yml>.

Alias: C<-f>

=head2 --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 L</GROUPSECRET_PRIVATE_KEY> or F<~/.ssh/id_rsa>.

Alias: C<-k>

=head1 COMMANDS

=head2 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 C<--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 L</GROUPSECRET_PATH>.

If the C<--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: C<add-keys>

=head2 delete-key