Imported Upstream version 0.2.7upstream_keyringer_0.2.7

1 files changed, 225 insertions, 110 deletions

diff --git a/share/man/keyringer.1 b/share/man/keyringer.1
index 9b6a2f5..c3fbc54 100644
--- a/share/man/keyringer.1
+++ b/share/man/keyringer.1
@@ -1,4 +1,4 @@
-.TH KEYRINGER 1 "Sep 10, 2013" "Keyringer User Manual"
+.TH KEYRINGER 1 "Oct 25, 2013" "Keyringer User Manual"
 .SH NAME
 .PP
 keyringer - encrypted and distributed secret sharing software
@@ -7,145 +7,227 @@ keyringer - encrypted and distributed secret sharing software
 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.
+Keyringer lets you manage and share secrets using GnuPG and Git in a
+distributed fashion.
 .PP
-Secrets are encrypted using GPG and added to a git tree so later then
-can be synced with remote branches.
+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.
+.PP
+Secrets are encrypted using GPG and added to a Git tree so that they can
+be synced with remote branches later.
 .SH ACTIONS
 .PP
 Keyringer has three types of actions:
 .IP "1." 3
-Repository lookup and manipulation actions.
+Repository lookup and manipulation actions, which handle repository
+initialization, content tracking and navigation.
 .IP "2." 3
-Secret manipulation actions.
+Secret manipulation actions, which take care of encrypting, decrypting
+and other read/write operations on secrets.
 .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.
+Configuration actions, handling repository metadata.
+.SH REPOSITORY LOOKUP AND MANIPULATION ACTIONS
+.TP
+.B 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.
+.RS
 .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.
+Also, an entry will be added to \f[C]$HOME/.keyringer/config\f[]
+allowing keyringer to find the keyring by its alias.
+.RE
+.TP
+.B 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 to have it
+applied in the keyring repository.
+.RS
+.RE
+.TP
+.B 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
+.RS
+.RE
+.SH 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
+All secret manipulation actions operate upon a \f[I]secret\f[] which is
+the pathname of an encrypted file relative to the keyring with optional
 \f[C]\&.asc\f[] extension.
 .PP
-If the \f[C]\&.asc\f[] extension is ommited, keyringer will add it in
+If the \f[C]\&.asc\f[] extension is omitted, keyringer will add it at
 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.
+Instead, the user has to manually commit the changes using the git
+wrapper action.
+.TP
+.B append <\f[I]secret\f[]>
+Append contents into a secret by decrypting the secret, appending lines
+read from the standard input and encrypting again.
+.RS
+.RE
+.TP
+.B append-batch <\f[I]secret\f[]>
+Append contents into a secret, batch mode.
+.RS
+.RE
+.TP
+.B decrypt <\f[I]secret\f[]>
+Decrypts a secret into standard output.
+.RS
+.RE
+.TP
+.B 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.
+.RS
+.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 yourself.
+.RE
+.TP
+.B 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 re-encrypting it.
+.RS
+.RE
+.TP
+.B encrypt <\f[I]secret\f[]> [\f[I]file\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]secret\f[] name.
+.RS
+.RE
+.TP
+.B encrypt-batch <\f[I]secret\f[]>
+Encrypt content, batch mode.
+.RS
+.RE
+.TP
+.B genpair <\f[I]ssh\f[]|\f[I]gpg\f[]|\f[I]ssl\f[]|\f[I]ssl-self\f[]>
+[\f[I]options\f[]]
+Wrapper to generate encryption key-pairs, useful for automated key
+deployment.
+.RS
+.RE
+.TP
+.B open <\f[I]secret\f[]>
+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.
+.RS
+.PP
+After the application exits, keyringer encrypts the temporary decrypted
+file again into the secret file and deletes the temporary file.
+.RE
+.TP
+.B recrypt <\f[I]secret\f[]>
+Re-encrypts a secret by decrypting it and encrypting it again.
+Useful when users are added into the 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.
+.RS
+.RE
+.SH CONFIGURATION ACTIONS
+.TP
+.B commands
+List available actions, useful for shell completion and syntax check.
+.RS
+.RE
+.TP
+.B options <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]>
+List, edit or add miscellaneous \f[I]repository\f[] options.
+.RS
+.PP
+Repository options are settings which are saved in the repository as a
+\f[I]global\f[] configuration stanza for a given keyring, shared by all
+users with access to the repository.
+.PP
+Options are written using the \f[I]KEY=VALUE\f[] syntax.
+All lines starting with the hash (#) character are interpreted as
+comments.
+.RE
+.TP
+.B 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.
+.RS
+.PP
+User preferences are settings which are saved in the user\[aq]s
+keyringer folder (\f[C]$HOME/.keyringer/\f[]), and 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.
+.RE
+.TP
+.B usage
+Show keyringer usage information.
+.RS
+.RE
+.TP
+.B recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipients-file\f[]>
+List, create or edit recipients configuration.
+.RS
+.PP
+Recipients 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 recipients file, but specifying a custom
+\f[I]recipients-file\f[] pathname will override this default.
+For instance, if a user encrypts a secret to a file in the keyring
+repository\[aq]s \f[I]accounting\f[] folder, a \f[I]recipients-file\f[]
+under \f[I]accounting\f[] will be used.
+Encrypting a secret into \f[I]accounting/bank-accounts\f[] will result
+in a file
+.RE
 .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.
+using the public keys listed in the config
+file\f[C]$KEYRING_FOLDER/config/recipients/accounting\f[].
+.IP
+.nf
+\f[C]
+Each\ line\ in\ a\ recipients\ file\ has\ entries\ in\ the\ format
+\[aq]john\@doe.com\ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\[aq],\ 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.
+\f[]
+.fi
 .SH FILES
 .PP
 $HOME/.keyringer/config : User\[aq]s main configuration file used to map
@@ -157,6 +239,39 @@ aliased \f[I]keyring\f[] keyring.
 $KEYRING_FOLDER/config/options : Custom keyring options which will be
 applied for all users that use the keyringer repository.
 .SH LIMITATIONS
+.PP
+Keyringer currently has the following limitations:
+.IP "1." 3
+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 \f[I]--hidden-recipient\f[] GnuPG
+option.
+.IP "2." 3
+History is not rewritten by default when secrets are removed from a
+keyringer repository.
+After a secret is removed with the \f[I]del\f[] action, it will still be
+available in the repository history even after a commit.
+This is by design for the following reasons:
+.IP \[bu] 2
+It\[aq]s the default behavior of the Git content tracker.
+Forcing the deletion by default could break the expected behavior and
+hence limit the repository\[aq]s backup features, which can be helpful
+if someone mistakenly overwrites a secret.
+.IP \[bu] 2
+History rewriting cannot be considered a security measure against the
+unauthorized access to a secret as it doesn\[aq]t automatically update
+all working copies of the repository.
+.RS 2
+.PP
+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.
+.PP
+Users wishing to edit their repository history should proceed manually
+using the \f[I]git\f[] action.
+.RE
 .SH SEE ALSO
 .PP
 The \f[I]README\f[] file distributed with Keyringer contains full
@@ -165,4 +280,4 @@ documentation.
 The Keyringer source code and all documentation may be downloaded from
 <https://keyringer.pw>.
 .SH AUTHORS
-Silvio Rhatto.
+Silvio Rhatto <rhatto@riseup.net>.