Ubuntu Manpage: keyringer - encrypted and distributed secret sharing software

NAME

       keyringer - encrypted and distributed secret sharing software

SYNOPSIS

       keyringer <keyring> <action> [options]...

DESCRIPTION

       Keyringer lets you manage and share secrets using GnuPG and Git in a distributed fashion.

       It has custom commands to create key-pairs and to encrypt, decrypt and re-encrypt secrets.
       It also supports encryption to multiple recipients and groups of recipients,  to  allow  a
       workgroup to share access to a single repository while restricting some secrets to subsets
       of the group.

       Secrets are encrypted using OpenPGP and added to a Git tree so that  they  can  be  synced
       with remote branches later.

ACTIONS

       Keyringer has three types of actions:

       1. Repository  lookup  and  manipulation  actions, which handle repository initialization,
          content tracking and navigation.

       2. Secret manipulation actions, which  take  care  of  encrypting,  decrypting  and  other
          read/write operations on secrets.

       3. Configuration actions, handling repository metadata.

REPOSITORY LOOKUP AND MANIPULATION ACTIONS

find <expression>
Find secrets in the repository.

init <path> [remote]
Initialize a new keyringer repository. If a remote URL is specified, keyringer
will clone an existing repository.

After initialization, path will contain a folder structure for storing secrets and
metadata (user aka recipients, groups of recipients, etc).

Also, an entry will be added to $HOME/.keyringer/config allowing keyringer to find
the keyring by its alias.

destroy
Alias for teardown action.

git <action> <options>
Git wrapper that operates from the toplevel keyring repository. You can issue any
GIT(1) subcommand with this action to have it applied in the keyring repository.

commit [arguments]
Alias to “git commit”.

ls <path>
List contents from the toplevel repository keys folder or from relative paths if
path is specified. Like the git wrapper, this is a wrapper around the LS(1)
command.

mkdir <path>
Create a directory inside the repository keys folder.

rmdir <path>
Remove an empty folder inside the repository keys folder.

tree <path>
List contents from the toplevel repository keys folder or from relative paths if
path is specified using a tree-like format. Like the ls wrapper, this is a wrapper
around the TREE(1) command.

shell Run keyringer on interactive mode from a built-in command-line prompt where all
other actions can be called and are operated from the current selected keyring.

An additional “cd” internal command is available for directory navigation.

All <secret> parameters from actions invoked from the shell are called relatively
from the current selected directory.

teardown
Remove permanently a local copy of a repository, very dangerous if you have just a
single copy.

check Run maintenance checks in a keyring.

SECRET MANIPULATION ACTIONS

All secret manipulation actions operate upon a secret which is the pathname of an
encrypted file relative to the keyring with optional .asc extension.

If the .asc extension is omitted, keyringer will add it at the end of the pathname.

No spaces are allowed in the secret name.

Secret manipulation actions do not commit changes into the secret repository. Instead,
the user has to manually commit the changes using the git wrapper action.

append <secret>
Append contents into a secret by decrypting the secret, appending lines read from
the standard input and encrypting again.

append-batch <secret>
Append contents into a secret, batch mode.

decrypt <secret>
Decrypts a secret into standard output.

del <secret>
Removes a secret using Git. After deleting a secret a git commit and push is still
needed to update remote repositories.

Please note that this command does not remove the secret from the Git history. To
completely remove a file from a keyring, you should also rewrite the Git history
yourself.

delete <secret>
Alias for del action.

rm <secret>
Alias for del action.

cp <secret> <dest>
Copy a secret.

mv <secret> <dest>
Rename a secret.

edit <secret>
Edit a secret by temporarily decrypting it, opening the decrypted copy into the
text editor defined by the $EDITOR environment variable and then re-encrypting it.

Please make sure to use an
EDITOR * whichdoesnotleakdatalikehistorybuffers.Keyringertriestodetectif*EDITOR is
set to VIM and disables the .viminfo file.

encrypt <secret> [file]
Encrypts content from standard input or file into secret pathname. No spaces are
supported in the secret name. If file is actually a folder, keyringer will
recursivelly encrypt all it’s contents.

encrypt-batch <secret> [file]
Encrypt content, batch mode. Behavior is identical to encrypt action, but less
verbose. Useful inside scripts.

genkeys <ssh|gpg|x509|x509-self|ssl|ssl-self> [options]
Wrapper to generate encryption key-pairs, useful for automated key deployment.

genpair <ssh|gpg|x509|x509-self|ssl|ssl-self> [options]
Alias for genkeys action.

open <secret>
Decrypt a secret into a temporary folder and open it using xdg-open, which tries to
figure out the file type and then calls the associated application.

After the application exits, keyringer encrypts the temporary decrypted file again
into the secret file and deletes the temporary file.

pwgen <secret> [size]
Generates a random passphrase and stores into secret pathname with optional entropy
size in bytes. Default size is 20.

Passphrases will be slightly bigger than size due to base64 conversion.

With this action you can generate and store a passphrase without need to see it.
Combined with clip or sclip action provides an hygienic way to handle secrets.

recrypt <secret>
Re-encrypts a secret by decrypting it and encrypting it again. Useful when users
are added into the recipient configuration. If no secret is given, all secrets in
the repository are re-encrypted.

clip <secret>
Copy the first line of a secret to the clipboard, following password-store
convention.

xclip <secret>
Alias to clip action.

sclip <secret>
Same as clip action, but sleeps five seconds, overwrite clipboard and exit. If
xdotool is available, it also switches to the next window using the alt+Tab
shortcut. This action is useful to be invoked by a custom key combo in a window
manager so it becomes easy to provide keyringer managed passphrases to other
applications such as a web browser.

CONFIGURATION ACTIONS

       commands
              List available actions, useful for shell completion and syntax check.

       options <ls|edit|add>
              List, edit or add miscellaneous repository options.

              Repository  options  are  settings  which  are  saved in the repository as a global
              configuration stanza for a given keyring, shared by all users with  access  to  the
              repository.

              Options  are  written using the KEY=VALUE syntax.  All lines starting with the hash
              (#) character are interpreted as comments.

       preferences <ls|edit|add>
              List, edit or add user preferences for a given repository.

              User preferences are settings which  are  saved  in  the  user’s  keyringer  folder
              ($HOME/.keyringer/), and not shared with the other users.

              Preferences  are  written  using the KEY=VALUE syntax.  All lines starting with the
              hash (#) character are interpreted as comments.

       usage  Show keyringer usage information.

       help   Alias for usage action.

       recipients <ls|edit> <recipients-file>
              List, create or edit recipients configuration.

              Recipients files are lists of OpenPGP public key fingerprints  which  are  used  by
              keyringer when encrypting secrets and associated with email aliases.

              Keyringer  uses  a default recipients file, but specifying a custom recipients-file
              pathname will override this default.

              For instance, if a user encrypts a secret to a file  in  the  keyring  repository’s
              accounting  folder,  a recipients-file under accounting will be used.  Encrypting a
              secret    into    accounting/bank-accounts    will     result     in     a     file
              $KEYRING_FOLDER/keys/accounting/bank-accounts.asc  encrypted  using the public keys
              listed in the config file$KEYRING_FOLDER/config/recipients/accounting.

              Each  line  in  a  recipients  file  has  entries  in  the   format   `john@doe.com
              XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',  where  john@doe.com is an alias for the
              OpenPGP public key whose fingerprint is XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.

              All lines starting with the hash (#) character are interpreted as comments.

              Parameters to the recipients action are:

              ls     List all existing recipients files.

              edit   Create or edit a recipients file.

                     Editing happens using  the  editor  specified  by  the  $EDITOR  environment
                     variable.

                     The  required  parameter  recipients-file  is  interpreted  relative  to the
                     $KEYRING_FOLDER/config/recipients/ folder.

FILES

       $HOME/.keyringer/config
              User’s main configuration file used to map alias names to keyrings.

       $HOME/.keyringer/keyring
              User preferences for the keyringer aliased keyring keyring.

       $KEYRING_FOLDER/config/options
              Custom keyring options which will be applied for all users that use  the  keyringer
              repository.

LIMITATIONS

Keyringer currently has the following limitations:

1. Metadata is not encrypted, meaning that an attacker with access to a keyringer
repository can discover all public key IDs used for encryption, and which secrets are
encrypted to which keys. This can be improved in the future by encrypting the
repository configuration with support for the –hidden-recipient GnuPG option and
encrypted repository options.

To mitigate that, it’s possible to keep the repo just atop of an encrypted and non-
public place.

2. History is not rewritten by default when secrets are removed from a keyringer
repository. After a secret is removed with the del action, it will still be available
in the repository history even after a commit. This is by design for the following
reasons:

• It’s the default behavior of the Git content tracker. Forcing the deletion by default
could break the expected behavior and hence limit the repository’s backup features,
which can be helpful if someone mistakenly overwrites a secret.

• History rewriting cannot be considered a security measure against the unauthorized
access to a secret as it doesn’t automatically update all working copies of the
repository.

In the case that the secret is a passphrase, the recommended measure against such
attacks is to change the passphrase, making useless the knowledge of the previous
secret.

Users wishing to edit their repository history should proceed manually using the git
action.

3. Keyringer does not protect data which were not encrypted to a keyring, so be careful
when decrypting secrets and writing them to the disk or other storage media.

Pay special attention that keyringer outputs data to stdout, which could be easily
spotted by any agent looking directly at you computer screen.

The xclip action even copies secret data to the X11 clipboard, which can be accessed
by any application running in the user’s X11 session, so use this feature carefully.

AUTHORS

       Silvio Rhatto <rhatto@riseup.net>.