.TH KEYRINGER 1 "Oct 24, 2013" "Keyringer User Manual" .SH NAME .PP keyringer - encrypted and distributed secret sharing software .SH SYNOPSIS .PP keyringer <\f[I]keyring\f[]> <\f[I]action\f[]> [\f[I]options\f[]]... .SH DESCRIPTION .PP Keyringer lets you manage and share secrets using GnuPG and Git in a distributed fashion. .PP It has custom commands to encrypt, decrypt and recrypt secrets as well as create key pairs and supports encryption to multiple recipients and groups of different recipients to ensure the same repository can be shared with a workgroup but allowing to keep some secrets available just to subsets of that group. .PP Secrets are encrypted using GPG and added to a git tree so later then can be synced with remote branches. .SH ACTIONS .PP Keyringer has three types of actions: .IP "1." 3 Repository lookup and manipulation actions. .IP "2." 3 Secret manipulation actions. .IP "3." 3 Configuration actions. .SS REPOSITORY LOOKUP AND MANIPULATION ACTIONS .PP init <\f[I]path\f[]> [\f[I]remote\f[]] : Initialize a new keyringer repository. If a \f[I]remote\f[] URL is specified, keyringer will clone an existing repository. .PP After initialization, \f[I]path\f[] will contain a folder structure for storing secrets and metadata (user aka recipients, groups of recipients, etc). .PP Also, an entry on \f[C]$HOME/.keyringer/config\f[] will be added allowing keyringer to find the keyring by it\[aq]s alias. .PP git <\f[I]action\f[]> <\f[I]options\f[]> : Git wrapper that operates from the toplevel keyring repository. You can issue any \f[I]GIT(1)\f[] subcommand with this action that it will be applied into the keyring repository. .PP ls <\f[I]path\f[]> : List contents from the toplevel repository \f[I]keys\f[] folder or from relative paths if \f[I]path\f[] is specified. Like the git wrapper, this is a wrapper around the \f[I]LS(1)\f[] command. .SS SECRET MANIPULATION ACTIONS .PP All secret manipulation actions operates upon a \f[I]secret\f[] which is the pathname of an encrypted file relative to keyring with optional \f[C]\&.asc\f[] extension. .PP If the \f[C]\&.asc\f[] extension is ommited, keyringer will add it in the end of the pathname. .PP No spaces are allowed in the secret name. .PP 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. .PP append <\f[I]secret\f[]> : Append contents into a secret by decrypting the secret, appending lines read from the standard input and encrypting again. .PP append-batch <\f[I]secret\f[]> : Append contents into a secret, batch mode. .PP decrypt <\f[I]secret\f[]> : Decrypts a secret into standard output. .PP del <\f[I]secret\f[]> : Removes a secret using git. After deleting a secret a git commit and push is still needed to update remote repositories. .PP Please note that this command \f[B]does not remove the secret from the git history.\f[] To completely remove a file from a keyring, you should also rewrite the git history by yourself. .PP edit <\f[I]secret\f[]> : Edit a secret by temporarily decrypting it, opening the decrypted copy into the text editor defined by the \f[I]$EDITOR\f[] environment variable and then recrypting it again. .PP encrypt [\f[I]file\f[]] <\f[I]secret\f[]> : Encrypts content from standard input or \f[I]file\f[] into \f[I]secret\f[] pathname. No spaces are supported in the \f[I]file\f[] name. .PP encrypt-batch <\f[I]secret\f[]> : Encrypt content, batch mode. .PP genpair <\f[I]ssh\f[]|\f[I]gpg\f[]|\f[I]ssl\f[]|\f[I]ssl-self\f[]> [\f[I]options\f[]] : Wrapper to generete encryption keypairs, useful for automated key deployment. .PP open <\f[I]secret\f[]> : Decrypt a secret into a temporary folder and opening it using xdg-open which then tries to figure out the file type and calling the associated application. .PP After the application exits, keyringer encrypts the temporary decrypted file again into the secret file. .PP recrypt <\f[I]secret\f[]> : Recrypts a secret by decrypting it and recrypting again. Useful when users are added into recipient configuration. If no \f[I]secret\f[] is given, all secrets in the repository are re-encrypted. .SS CONFIGURATION ACTIONS .PP commands : List available actions, useful for shell completion and syntax check. .PP options <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> : List, edit or add miscelaneous \f[I]repository\f[] options. .PP Repository options are specific configurations for the keyring which are saved into the repository, making it available for all users with access to the repository and hence is a \f[I]global\f[] configuration stanza for a given keyring. .PP Options are written using the \f[I]KEY=VALUE\f[] syntax. All lines starting with the hash (#) character are interpreted as comments. .PP preferences <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> : List, edit or add \f[I]user\f[] preferences for a given repository. .PP User preferences are specific configurations for the keyring which are saved into the user\[aq]s keyringer folder (\f[C]$HOME/.keyringer/\f[]) hence not shared with the other users. .PP Preferences are written using the \f[I]KEY=VALUE\f[] syntax. All lines starting with the hash (#) character are interpreted as comments. .PP usage : Show keyringer usage information. .PP recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipient-file\f[]> : List, create or edit recipient configuration. .PP Recipient files are lists of OpenPGP public key fingerprints which are used by keyringer when encrypting secrets and associated with email aliases. .PP Keyringer uses a default recipient file and supports custom \f[I]recipient-files\f[] which overrides the default recipient file according to it\[aq]s matching pathname. .PP For instance, a the \f[I]recipient-file\f[] called \f[I]accounting\f[] will be used wherever a user encrypts a secret to a file residing from the \f[I]accounting\f[] folder in the keyring repository. In that case, encrypting a secret into \f[I]accounting/bank-accounts\f[] will result in a file \f[C]$KEYRING_FOLDER/keys/accounting/bank-accounts.asc\f[] encrypted using the public keys listed in \f[C]$KEYRING_FOLDER/config/recipients/accounting\f[] config file. .PP Each line in a recipients file has entries in the form of \[aq]john\@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\[aq], where \f[I]john\@doe.com\f[] is an alias for the GPG public key whose fingerprint is \f[I]XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.\f[] .PP All lines starting with the hash (#) character are interpreted as comments. .SS OPTIONS .PP ls : List all existing recipient files. .PP edit : Create or edit a recipient-file. .PP Editing happens using the editor specified by the \f[C]$EDITOR\f[] environment variable. .PP The required parameter \f[I]recipient-file\f[] is taken relativelly from the \f[C]$KEYRING_FOLDER/config/recipients/\f[] folder. .SH FILES .PP $HOME/.keyringer/config : User\[aq]s main configuration file used to map alias names to keyrings. .PP $HOME/.keyringer/\f[I]keyring\f[] : User preferences for the keyringer aliased \f[I]keyring\f[] keyring. .PP $KEYRING_FOLDER/config/options : Custom keyring options which will be applied for all users that use the keyringer repository. .SH LIMITATIONS .SH SEE ALSO .PP The \f[I]README\f[] file distributed with Keyringer contains full documentation. .PP The Keyringer source code and all documentation may be downloaded from . .SH AUTHORS Silvio Rhatto.