Dogcows Code - chaz/groupsecret/blob - README.md

   1 # NAME
   2
   3 groupsecret - A simple tool for maintaining a shared group secret
   4
   5 # VERSION
   6
   7 version 0.301
   8
   9 # SYNOPSIS
  10
  11     groupsecret [--version] [--help] [-f <filepath>] [-k <privatekey_path>]
  12                 <command> [<args>]
  13
  14     groupsecret add-key [--embed] [--update] <publickey_path> ...
  15
  16     groupsecret delete-key <fingerprint>|<publickey_path> ...
  17
  18     groupsecret list-keys
  19
  20     groupsecret set-secret [--keep-passphrase] <path>|-|rand:<num_bytes>
  21
  22     groupsecret [print-secret] [--no-decrypt]
  23
  24 # DESCRIPTION
  25
  26 [groupsecret](https://metacpan.org/pod/groupsecret) is a program that makes it easy for groups to share a secret between themselves
  27 without exposing the secret to anyone else. It could be used, for example, by a team to share an
  28 [ansible-vault(1)](http://man.he.net/man1/ansible-vault) password.
  29
  30 The goal of this program is to be easy to use and have few dependencies (or only have dependencies
  31 users are likely to already have installed).
  32
  33 [groupsecret](https://metacpan.org/pod/groupsecret) works by encrypting a secret with a symmetric cipher protected by a secure random
  34 passphrase which is itself encrypted by one or more SSH2 RSA public keys. Only those who have access
  35 to one of the corresponding private keys are able to decrypt the passphrase and access the secret.
  36
  37 The encrypted secret and passphrase are stored in a single keyfile. You can even commit the keyfile
  38 in a public repo or in a private repo where some untrusted users may have read access; the secret is
  39 locked away to all except those with a private key to a corresponding public key that has been added
  40 to the keyfile.
  41
  42 The keyfile is just a YAML file, so it's human-readable (except of course for the encrypted parts).
  43 This make it easy to add to version control and work with diffs. You can edit the keyfile by hand if
  44 you learn its very simple structure, but this program makes it even easier to manage the keyfile.
  45
  46 # OPTIONS
  47
  48 ## --version
  49
  50 Print the program name and version to `STDOUT`, and exit.
  51
  52 Alias: `-v`
  53
  54 ## --help
  55
  56 Print the synopsis to `STDOUT`, and exit.
  57
  58 Alias: `-h`
  59
  60 ## --file=path
  61
  62 Specify a path to a keyfile which stores a secret and keys.
  63
  64 Defaults to the value of the environment variable `GROUPSECRET_KEYFILE` or `groupsecret.yml`.
  65
  66 Alias: `-f`
  67
  68 ## --private-key=path
  69
  70 Specify a path to a PEM private key. This is used by some commands to decrypt the passphrase that
  71 protects the secret and is ignored by commands that don't need it.
  72
  73 Defaults to the value of the environment variable ["GROUPSECRET\_PRIVATE\_KEY"](#groupsecret_private_key). If that is unset, it
  74 defaults to `~/.ssh/id_rsa`.
  75
  76 Alias: `-k`
  77
  78 # COMMANDS
  79
  80 ## add-key
  81
  82     groupsecret add-key path/to/mykey_rsa.pub
  83
  84 Adds one or more SSH2 RSA public keys to a keyfile. This allows the secret contained within the
  85 keyfile to be accessed by whoever has the corresponding private key.
  86
  87 If the `--embed` option is used, the public keys will be embeded in the keyfile. This may be
  88 a useful way to make sure the actual keys are available in the future since they could be needed to
  89 encrypt a new passphrase if it ever needs to be changed. Keys that are not embedded will be searched
  90 for in the filesystem; see ["GROUPSECRET\_PATH"](#groupsecret_path).
  91
  92 If the `--update` option is used and a key with the same fingerprint is added, the new key will
  93 replaced the existing key. The default behavior is to skip existing keys.
  94
  95 If the keyfile is storing a secret, the passphrase protecting the secret will need to be decrypted
  96 so that access to the secret can be shared with the new key(s).
  97
  98 Alias: `add-keys`
  99
 100 ## delete-key
 101
 102     groupsecret delete-key MD5:89:b3:fb:76:6c:f9:56:8e:a8:1a:df:ba:1c:ba:7d:05
 103     groupsecret delete-key path/to/mykey_rsa.pub
 104
 105 Deletes one or more keys from a keyfile. This prevents the secret contained within the keyfile from
 106 being accessed by whoever has the corresponding private key.
 107
 108 Of course, if the owners of the key(s) being removed have already had access to the keyfile prior to
 109 their keys being removed, the secret is already exposed to them. It usually makes sense to follow up
 110 this command with a ["set-secret"](#set-secret) command in order to change the secret.
 111
 112 Aliases: `delete-keys`, `remove-key`, `remove-keys`
 113
 114 ## list-keys
 115
 116     groupsecret list-keys
 117
 118 Prints the keys that have access to the secret contained in the keyfile to `STDOUT`, one per line
 119 in the following format:
 120
 121     <fingerprint> <comment>
 122
 123 ## set-secret
 124
 125     groupsecret set-secret path/to/secretfile.txt
 126     groupsecret set-secret - <<END
 127     > it's a secret to everybody
 128     > END
 129     groupsecret set-secret rand:48
 130
 131 Set or update the secret contained in a keyfile. The argument allows you to add a secret from
 132 a file, from <STDIN>, or from a stream of secure random bytes.
 133
 134 If the keyfile already contains a secret, it will be replaced by the new secret. A keyfile can only
 135 contain one secret at a time. If you think you want to store more than one secret at a time, store
 136 a tarball instead.
 137
 138 By default, this will also change the passphrase protecting the secret and re-encrypt the passphrase
 139 for each key currently in the keyfile. This requires all of the public keys to be available (see
 140 ["GROUPSECRET\_PATH"](#groupsecret_path)). If for some reason you want to protect the new secret with the current
 141 passphrase, use the `--keep-passphrase` option; this can be done without the public keys being
 142 available, but it will require a private key to decrypt the passphrase.
 143
 144 Aliases: `change-secret`, `update-secret`
 145
 146 ## print-secret
 147
 148     groupsecret print-secret
 149     groupsecret print-secret --no-decrypt
 150
 151 Print the secret contained in the keyfile to `STDOUT`.
 152
 153 If the `--no-decrypt` option is used, the secret will be printed in its encrypted form.
 154
 155 This requires a private key.
 156
 157 Aliases: (no command), `show-secret`
 158
 159 # REQUIREMENTS
 160
 161 - [OpenSSH](https://www.openssh.com) (commands: [ssh-keygen(1)](http://man.he.net/man1/ssh-keygen))
 162 - [OpenSSL](https://www.openssl.org) (commands: [openssl(1)](http://man.he.net/man1/openssl))
 163
 164 # INSTALL
 165
 166 There are a few ways to install groupsecret to your system. First, make sure you first have the
 167 ["REQUIREMENTS"](#requirements) installed.
 168
 169 ## Using cpanm
 170
 171 You can install groupsecret using [cpanm](https://metacpan.org/pod/cpanm). If you have a local perl (plenv, perlbrew, etc.), you
 172 can just do this:
 173
 174     cpanm App::GroupSecret
 175
 176 to install the `groupsecret` executable and its Perl module dependencies. The executable will be
 177 installed to your perl's bin path, like `~/perl5/perlbrew/bin/groupsecret`.
 178
 179 If you're installing to your system perl, you can do:
 180
 181     cpanm --sudo App::GroupSecret
 182
 183 to install the `groupsecret` executable to a system directory, like `/usr/local/bin/groupsecret`
 184 (depending on your perl).
 185
 186 ## For developers
 187
 188 If you're a developer and want to hack on the source, clone the repository and pull the
 189 dependencies:
 190
 191     git clone https://github.com/chazmcgarvey/groupsecret.git
 192     cd groupsecret
 193     cpanm Dist::Zilla
 194     dzil authordeps --missing | cpanm
 195     dzil listdeps --author --develop --missing | cpanm
 196
 197 # ENVIRONMENT
 198
 199 ## GROUPSECRET\_KEYFILE
 200
 201 If set, this program will use the value as a path to the keyfile. The ["--file=path"](#file-path) option takes
 202 precedence if it is used.
 203
 204 ## GROUPSECRET\_PRIVATE\_KEY
 205
 206 If set, this program will use the value as a path to the keyfile. The ["--private-key=path"](#private-key-path) option
 207 takes precedence if it is used.
 208
 209 ## GROUPSECRET\_PATH
 210
 211 The value of this variable should be a colon-separated list of directories in which to search for
 212 public keys. By default, the actual keys are not embedded in keyfiles, but they may be needed to
 213 encrypt a new passphrase if it ever needs to be changed. Keys that are not embedded will be searched
 214 for in the filesystem based on the value of this environment variable.
 215
 216 Defaults to `.:keys:$HOME/.ssh`.
 217
 218 # BUGS
 219
 220 Please report any bugs or feature requests on the bugtracker website
 221 [https://github.com/chazmcgarvey/groupsecret/issues](https://github.com/chazmcgarvey/groupsecret/issues)
 222
 223 When submitting a bug or request, please include a test-file or a
 224 patch to an existing test-file that illustrates the bug or desired
 225 feature.
 226
 227 # AUTHOR
 228
 229 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 230
 231 # COPYRIGHT AND LICENSE
 232
 233 This software is Copyright (c) 2017 by Charles McGarvey.
 234
 235 This is free software, licensed under:
 236
 237     The MIT (X11) License