path: root/share/man/keyringer.1

.TH KEYRINGER 1 "Sep 10, 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 GPG and git with
custom commands to encrypt, decrypt, recrypt, create key pairs, etc.
.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.
After any manipulation, the user has to manually commit the changes
using the git wrapper action.
.PP
append <\f[I]secret\f[]> : Append contents into a secret.
.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.
To completely remove a file from a keyring, you should also rewrite the
git history by yourself.
.PP
edit <\f[I]secret\f[]> : Edits 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[]> : Open a secret using xdg-open.
.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
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
recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipient-file\f[]> : List
or edit recipient configuration.
.PP
Recipient files are lists of OpenPGP public key fingerprints which are
used by keyringer when encrypting secrets.
.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.
.SS OPTIONS
.PP
ls : List all existing recipient files.
.PP
edit : Create or edit a recipient-file.
.PP
Edition 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.
.PP
usage : Show keyringer usage information.
.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
<https://keyringer.pw>.
.SH AUTHORS
Silvio Rhatto.