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

       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.

       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.

       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.

       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.

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.

rm <secret>
Alias for del action.

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.

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.

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

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.

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.

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.

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

       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.

AUTHORS

       Silvio Rhatto <rhatto@riseup.net>.

Keyringer User Manual                             Oct 25, 2013                                      KEYRINGER(1)