Merge branch 'master' into debian

5 files changed, 212 insertions, 74 deletions

diff --git a/debian/copyright b/debian/copyright
index 0c7a7af..51157ee 100644
--- a/debian/copyright
+++ b/debian/copyright
@@ -11,29 +11,22 @@ Upstream Author(s):
     Silvio Rhatto <rhatto@riseup.net>
     Daniel Kahn Gillmor <dkg@fifthhorseman.net>
     Jamie McClelland <jm@mayfirst.org>
+    ricola <ricola@poivron.org>
 
 Copyright:
 
     <Copyright (C) 2009-2012 Silvio Rhatto>
     <Copyright (C) 2010 Daniel Kahn Gillmor>
     <Copyright (C) 2012 Jamie McClelland>
+    <Copyright (C) 2012 ricola>
 
 License:
 
-    GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007
+    GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 or greater
 
 The Debian packaging is:
 
     Copyright (C) 2012 Silvio Rhatto <rhatto@riseup.net>
 
-# Please chose a license for your packaging work. If the program you package
-# uses a mainstream license, using the same license is the safest choice.
-# Please avoid to pick license terms that are more restrictive than the
-# packaged work, as it may make Debian's contributions unacceptable upstream.
-# If you just want it to be GPL version 3, leave the following lines in.
-
 and is licensed under the GPL version 3,
 see "/usr/share/common-licenses/GPL-3".
-
-# Please also look if there are files or directories which have a
-# different copyright/license attached and list them here.
diff --git a/development.mdwn b/development.mdwn
new file mode 100644
index 0000000..874a408
--- /dev/null
+++ b/development.mdwn
@@ -0,0 +1,38 @@
+[[!meta title="Keyringer: development guidelines"]]
+
+Preparing the source code:
+
+    make build_man
+
+Commit and tag release:
+
+    git checkout master
+    git commit -m "Keyringer 0.1"
+    git tag -s
+    git checkout upstream
+    git merge master
+    git checkout debian
+    git merge master
+    git push --tags
+
+Creating the `debian/` structure:
+
+    dh_make -p keyringer_0.1 --createorig
+
+Creating a release file:
+
+    git archive --format=tar HEAD | gzip >../tarballs/keyringer-0.1.tar.gz
+
+To generate a `keyringer_0.1.orig.tar.gz`-line file:
+
+    dh_make -f ../tarballs/keyringer-0.1.tar.gz -p keyringer_0.1
+
+Building a package from the git three using the upstream branch:
+
+    git-buildpackage
+
+References:
+
+* [Using Git for Debian Packaging](http://www.eyrie.org/~eagle/notes/debian/git.html).
+* [Building packages from the Git repository](http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.building.html).
+
diff --git a/index.mdwn b/index.mdwn
index 7ed01a6..a9077c1 100644
--- a/index.mdwn
+++ b/index.mdwn
@@ -164,15 +164,12 @@ Concepts
 
 Basic idea is:
 
-  - Encrypt stuff with ppl's gpg pubkeys and push the output in a git repo.
+  - Encrypt stuff with multiple users's gpg pubkeys and push the output in a git repo.
 
-  - Let ppl keep it in sync with the repo and the keys are shared :)
+  - Let users keep it in sync with the repo and the secrets are shared :)
 
-For "key" it's meant anything as the script work with stdin and output things to
-files, so it can be passphrases, private keys or other kind of info.
-
-It's possible to share keys using an encrypted mailing list, but the main
-difficulty is to track the message where the keys are.
+For "secrets" it's meant anything as the script work with stdin and output things to
+files, so it can be passphrases, private keys or other kind of information.
 
 With theses scripts, the workflow is more or less like this:
 
@@ -185,7 +182,7 @@ With theses scripts, the workflow is more or less like this:
 
   - You manually add it to git and push it to remote repositories.
 
-  - Optionally, other ppl pulls the changes but they dont need to
+  - Optionally, other users pulls the changes but they dont need to
     decrypt anything until they need to use the keys.
 
 So it's just gpg-encrypted data atop of a git repository (one can think of a
@@ -216,3 +213,7 @@ Optional dependencies if you want to manage ssl keys:
 
   - [OpenSSL](http://www.openssl.org)
 
+Development guidelines
+----------------------
+
+See [development](development).
diff --git a/share/man/keyringer.1 b/share/man/keyringer.1
index 2eaa30d..66ed9cc 100644
--- a/share/man/keyringer.1
+++ b/share/man/keyringer.1
@@ -1,4 +1,4 @@
-.TH KEYRINGER 1 "August 17, 2013" "Keyringer User Manual"
+.TH KEYRINGER 1 "Sep 10, 2013" "Keyringer User Manual"
 .SH NAME
 .PP
 keyringer - encrypted and distributed secret sharing software
@@ -9,39 +9,55 @@ keyringer <\f[I]keyring\f[]> <\f[I]action\f[]> [\f[I]options\f[]]...
 .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
-Configuration actions.
+Repository lookup and manipulation actions.
 .IP "2." 3
 Secret manipulation actions.
 .IP "3." 3
-Repository lookup and manipulation actions.
-.SS CONFIGURATION ACTIONS
-.PP
-commands : List available actions, useful for shell completion and
-syntax check.
+Configuration actions.
+.SS REPOSITORY LOOKUP AND MANIPULATION ACTIONS
 .PP
-options <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> : List, edit or add
-miscelaneous \f[I]repository options\f[].
+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
-preferences <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> : List, edit or add
-\f[I]user options\f[] for a given repository.
+After initialization, \f[I]path\f[] will contain a folder structure for
+storing secrets and metadata (user aka recipients, groups of recipients,
+etc).
 .PP
-recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipient-file\f[]> : List
-or edit recipient configuration.
+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
-usage : Show usage information.
+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
+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
 Secret manipulation actions do not commit changes into the secret
 repository.
-After any manipulation, the user has to manually commit the changes.
+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
@@ -76,13 +92,32 @@ 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.
-.SH REPOSITORY LOOKUP AND MANIPULATION ACTIONS
+.SS CONFIGURATION ACTIONS
 .PP
-git <\f[I]action\f[]> <\f[I]options\f[]> : Git wrapper that operates
-from the toplevel keyring repository.
+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 options\f[].
+.PP
+preferences <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> : List, edit or add
+\f[I]user options\f[] for a given repository.
+.PP
+recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipient-file\f[]> : List
+or edit recipient configuration.
+.PP
+usage : Show 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[].
 .PP
-ls <\f[I]PATH\f[]> : List contents from the toplevel repository
-\f[I]keys\f[] folder or from relative \f[I]PATH\f[].
+$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
diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn
index 14ae687..3abf8b8 100644
--- a/share/man/keyringer.1.mdwn
+++ b/share/man/keyringer.1.mdwn
@@ -1,6 +1,6 @@
 % KEYRINGER(1) Keyringer User Manual
 % Silvio Rhatto
-% August 17, 2013
+% Sep 10, 2013
 
 # NAME
 
@@ -15,81 +15,152 @@ keyringer <*keyring*> <*action*> [*options*]...
 Keyringer lets you manage and share secrets using GPG and git with custom
 commands to encrypt, decrypt, recrypt, create key pairs, etc.
 
+Secrets are encrypted using GPG and added to a git tree so later then can
+be synced with remote branches.
+
 # ACTIONS
 
 Keyringer has three types of actions:
 
-1. Configuration actions.
+1. Repository lookup and manipulation actions.
 2. Secret manipulation actions.
-3. Repository lookup and manipulation actions.
+3. Configuration actions.
 
-## CONFIGURATION ACTIONS
+## REPOSITORY LOOKUP AND MANIPULATION ACTIONS
 
-commands
-:  List available actions, useful for shell completion and syntax check.
+init <*path*> [*remote*]
+:  Initialize a new keyringer repository. If a *remote* URL is specified, keyringer will
+   clone an existing repository.
 
-options <*ls*|*edit*|*add*>
-:  List, edit or add miscelaneous *repository options*.
+   After initialization, *path* will contain a folder structure for storing secrets
+   and metadata (user aka recipients, groups of recipients, etc).
 
-preferences <*ls*|*edit*|*add*>
-:  List, edit or add *user options* for a given repository.
+   Also, an entry on `$HOME/.keyringer/config` will be added allowing keyringer to
+   find the keyring by it's alias.
 
-recipients <*ls*|*edit*> <*recipient-file*>
-:  List or edit recipient configuration.
+git <*action*> <*options*>
+:  Git wrapper that operates from the toplevel keyring repository. You can issue any
+   *GIT(1)* subcommand with this action that it will be applied into the keyring repository.
 
-usage
-:  Show usage information.
+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.
 
 ## SECRET MANIPULATION ACTIONS
 
-All secret manipulation actions operates upon a *SECRET*, which is the pathname
+All secret manipulation actions operates upon a *secret* which is the pathname
 of an encrypted file relative to keyring with optional `.asc` extension.
 
+If the `.asc` extension is ommited, keyringer will add it in the end of the
+pathname.
+
 Secret manipulation actions do not commit changes into the secret repository.
-After any manipulation, the user has to manually commit the changes.
+After any manipulation, the user has to manually commit the changes using the
+git wrapper action.
 
-append <*SECRET*>
+append <*secret*>
 :  Append contents into a secret.
 
-append-batch <*SECRET*>
+append-batch <*secret*>
 :  Append contents into a secret, batch mode.
 
-decrypt <*SECRET*>
+decrypt <*secret*>
 :  Decrypts a secret into standard output.
 
-del <*SECRET*>
+del <*secret*>
 :  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.
 
-edit <*SECRET*>
-:  Edits a secret by temporarily decrypting it, opening the decrypted copy into *$EDITOR*
-   and then recrypting it again.
+edit <*secret*>
+:  Edits a secret by temporarily decrypting it, opening the decrypted copy into the 
+   text editor defined by the *$EDITOR* environment variable and then recrypting it
+   again.
 
-encrypt [*file*] <*SECRET*>
-:  Encrypts content from standard input or *file* into *SECRET*.
+encrypt [*file*] <*secret*>
+:  Encrypts content from standard input or *file* into *secret* pathname.
 
-encrypt-batch <*SECRET*>
+encrypt-batch <*secret*>
 :  Encrypt content, batch mode.
 
 genpair <*ssh*|*gpg*|*ssl*|*ssl-self*> [*options*]
 :  Wrapper to generete encryption keypairs, useful for automated key deployment.
 
-open <*SECRET*>
+open <*secret*>
 :  Open a secret using xdg-open.
 
-recrypt <*SECRET*>
+recrypt <*secret*>
 :  Recrypts a secret by decrypting it and recrypting again. Useful when users are added
-   into recipient configuration. If no *SECRET* is given, all secrets in the repository
+   into recipient configuration. If no *secret* is given, all secrets in the repository
    are re-encrypted.
 
-# REPOSITORY LOOKUP AND MANIPULATION ACTIONS
+## CONFIGURATION ACTIONS
 
-git <*action*> <*options*>
-:  Git wrapper that operates from the toplevel keyring repository. 
+commands
+:  List available actions, useful for shell completion and syntax check.
+
+options <*ls*|*edit*|*add*>
+:  List, edit or add miscelaneous *repository* options.
+
+   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 *global* configuration stanza for a given keyring.
+
+preferences <*ls*|*edit*|*add*>
+:  List, edit or add *user* preferences for a given repository.
+
+   User preferences are specific configurations for the keyring which are
+   saved into the user's keyringer folder (`$HOME/.keyringer/`) hence not
+   shared with the other users.
+
+recipients <*ls*|*edit*> <*recipient-file*>
+:  List or edit recipient configuration.
+
+   Recipient files are lists of OpenPGP public key fingerprints which are used
+   by keyringer when encrypting secrets.
+
+   Keyringer uses a default recipient file and supports custom *recipient-files* which
+   overrides the default recipient file according to it's matching pathname.
+
+   For instance, a the *recipient-file* called *accounting* will be used
+   wherever a user encrypts a secret to a file residing from the *accounting*
+   folder in the keyring repository. In that case, 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 `$KEYRING_FOLDER/config/recipients/accounting` config
+   file.
+
+### OPTIONS
+
+ls
+:  List all existing recipient files.
+
+edit
+:  Create or edit a recipient-file.
+
+   Edition happens using the editor specified by the `$EDITOR`
+   environment variable.
+
+   The required parameter *recipient-file* is taken relativelly
+   from the `$KEYRING_FOLDER/config/recipients/` folder.
+
+usage
+:  Show keyringer usage information.
+
+# 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.
 
-ls <*PATH*>
-:  List contents from the toplevel repository *keys* folder or from relative *PATH*.
+# LIMITATIONS
 
 # SEE ALSO