20 files changed, 965 insertions, 803 deletions
diff --git a/share/keyringer/append b/share/keyringer/append
deleted file mode 100755
index bcc9e5e..0000000
--- a/share/keyringer/append
+++ /dev/null
@@ -1,41 +0,0 @@
-#!/bin/bash
-#
-# Append information into encrypted files.
-#
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
-source "$LIB" || exit 1
-
-# Get file
-keyringer_get_file "$2"
-
-OLDIFS="$IFS"
-IFS=$'\n'
-
-CONTENT=($(keyringer_exec decrypt "$BASEDIR" "$FILE"))
-
-if [ "$BASENAME" == "append" ]; then
-  # only display directions if we're running append, not append-batch
-  printf "\n%s currently has %d lines\n\n" "$FILE" "${#CONTENT[@]}"
-  printf "Now please write the content to be appended on %s, finnishing with Ctrl-D:\n" "$FILE"
-fi
-
-# FIXME: dkg doesn't know how to check that this does proper escaping
-# (2010-11-16)
-
-APPEND=($(cat -))
-
-NEW=( ${CONTENT[@]} ${APPEND[@]} )
-
-for element in $(seq 0 $((${#NEW[@]} - 1))); do
-  echo ${NEW[$element]}
-done | keyringer_exec encrypt-batch $BASEDIR $FILE
-
-err="$?"
-
-if [ "$err" != "0" ]; then
-  exit "$err"
-fi
-
-IFS="$OLDIFS"
diff --git a/share/keyringer/append-batch b/share/keyringer/append-batch
deleted file mode 120000
index 6b140f7..0000000
--- a/share/keyringer/append-batch
+++ /dev/null
@@ -1 +0,0 @@
-append
-\ No newline at end of file
diff --git a/share/keyringer/commands b/share/keyringer/commands
deleted file mode 100755
index 139725a..0000000
--- a/share/keyringer/commands
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/bin/bash
-#
-# Show available commands
-#
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
-source "$LIB" || exit 1
-
-keyringer_show_actions
diff --git a/share/keyringer/decrypt b/share/keyringer/decrypt
deleted file mode 100755
index bab9b34..0000000
--- a/share/keyringer/decrypt
+++ /dev/null
@@ -1,17 +0,0 @@
-#!/bin/bash
-#
-# Decrypt files.
-#
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
-source "$LIB" || exit 1
-
-# Get file
-keyringer_get_file "$2"
-
-# Decrypt
-$GPG --quiet --use-agent -d "$KEYDIR/$FILE"
-
-# Exit
-exit "$?"
diff --git a/share/keyringer/del b/share/keyringer/del
deleted file mode 100755
index 4eca0e3..0000000
--- a/share/keyringer/del
+++ /dev/null
@@ -1,16 +0,0 @@
-#!/bin/bash
-#
-# Remove files.
-#
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
-source "$LIB" || exit 1
-
-# Get file
-keyringer_get_file "$2"
-
-# Remove
-if [ -d "$BASEDIR/.git" ]; then
-  keyringer_exec git "$BASEDIR" rm "keys/$FILE"
-fi
diff --git a/share/keyringer/edit b/share/keyringer/edit
deleted file mode 100755
index fe05ecc..0000000
--- a/share/keyringer/edit
+++ /dev/null
@@ -1,45 +0,0 @@
-#!/bin/bash
-#
-# Edit keys.
-#
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
-source "$LIB" || exit 1
-
-# Get file
-keyringer_get_file "$2"
-
-# Set recipients file
-keyringer_set_recipients "$FILE"
-
-# Warn user
-echo "Make sure that $BASEDIR is atop of an encrypted volume."
-
-# Set a tmp file
-keyringer_set_tmpfile edit
-
-# Decrypt the information to the file
-$GPG --yes -o "$TMPWORK" --use-agent -d "$KEYDIR/$FILE"
-
-if [ "$BASENAME" == "edit" ]; then
-  APP="$EDITOR"
-elif [ "$BASENAME" == "open" ]; then
-  if which xdg-open &> /dev/null; then
-    APP="xdg-open"
-  else
-    echo "You should have xdg-open application to perform this action, aborting."
-    exit 1
-  fi
-fi
-
-# Prompt
-echo "Press any key to open the decrypted data with $APP, Ctrl-C to abort"
-read key
-$APP "$TMPWORK"
-
-# Encrypt again
-$GPG --yes -o "$KEYDIR/$FILE" --use-agent --armor -e -s $(keyringer_recipients "$RECIPIENTS_FILE") "$TMPWORK"
-
-# Remove temp file
-keyringer_unset_tmpfile "$TMPWORK"
diff --git a/share/keyringer/encrypt b/share/keyringer/encrypt
deleted file mode 100755
index ac305a4..0000000
--- a/share/keyringer/encrypt
+++ /dev/null
@@ -1,56 +0,0 @@
-#!/bin/bash
-#
-# Encrypt files to multiple recipients.
-#
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
-source "$LIB" || exit 1
-
-# Aditional parameters
-if [ ! -z "$3" ]; then
-  UNENCRYPTED_FILE="$2"
-  shift 2
-  keyringer_get_new_file "$*"
-
-  if [ ! -f "$UNENCRYPTED_FILE" ]; then
-    echo "Error: cannot encrypted $UNENCRYPTED_FILE: file not found."
-    exit 1
-  fi
-else
-  UNENCRYPTED_FILE="-"
-  shift
-  keyringer_get_new_file $*
-fi
-
-# Set recipients file
-keyringer_set_recipients "$FILE"
-
-# Encrypt
-mkdir -p "$KEYDIR/`dirname $FILE`"
-
-if [ "$BASENAME" == "encrypt" ]; then
-  # Only display directions if we're running encrypt, not encrypt-batch
-  if [ "$UNENCRYPTED_FILE" == "-" ]; then
-    echo "Type your message and finish your input with EOF (Ctrl-D)."
-  fi
-fi
-
-$GPG --use-agent --armor -e -s $(keyringer_recipients "$RECIPIENTS_FILE") --yes --output "$KEYDIR/$FILE" $UNENCRYPTED_FILE
-
-err="$?"
-
-if [ "$err" != "0" ]; then
-  exit "$err"
-fi
-
-if [ "$UNENCRYPTED_FILE" != "-" ]; then
-  echo "Now make to wipe the non-encrypted $UNENCRYPTED_FILE."
-fi
-
-# Stage
-if [ -d "$BASEDIR/.git" ]; then
-  keyringer_exec git "$BASEDIR" add "keys/$FILE"
-fi
-
-exit "$?"
diff --git a/share/keyringer/encrypt-batch b/share/keyringer/encrypt-batch
deleted file mode 120000
index 8267197..0000000
--- a/share/keyringer/encrypt-batch
+++ /dev/null
@@ -1 +0,0 @@
-encrypt
-\ No newline at end of file
diff --git a/share/keyringer/genpair b/share/keyringer/genpair
deleted file mode 100755
index f977714..0000000
--- a/share/keyringer/genpair
+++ /dev/null
@@ -1,222 +0,0 @@
-#!/bin/bash
-#
-# Generate keypairs.
-#
-# This script is just a wrapper to easily generate keys for
-# automated systems.
-# 
-
-# Generate a keypair, ssh version
-function genpair_ssh {
-  echo "Make sure that $KEYDIR is atop of an encrypted volume."
-  read -p "Hit ENTER to continue." prompt
-
-  # We're using empty passphrases
-  ssh-keygen -t rsa -P '' -f "$TMPWORK/id_rsa" -C "root@$NODE"
-
-  # Encrypt the result
-  echo "Encrypting secret key into keyringer..."
-  cat "$TMPWORK/id_rsa"     | keyringer_exec encrypt "$BASEDIR" "$FILE"
-  echo "Encrypting public key into keyringer..."
-  cat "$TMPWORK/id_rsa.pub" | keyringer_exec encrypt "$BASEDIR" "$FILE.pub"
-
-  if [ ! -z "$OUTFILE" ]; then
-    mkdir -p `dirname $OUTFILE`
-    printf "Saving copies at %s and %s.pub\n" "$OUTFILE" "$OUTFILE"
-    cat "$TMPWORK/id_rsa"     > "$OUTFILE"
-    cat "$TMPWORK/id_rsa.pub" > "$OUTFILE.pub"
-  fi
-
-  echo "Done"  
-}
-
-# Generate a keypair, gpg version
-function genpair_gpg {
-  echo "Make sure that $KEYDIR is atop of an encrypted volume."
-
-  passphrase="no"
-  passphrase_confirm="confirm"
-
-  while [ "$passphrase" != "$passphrase_confirm" ]; do
-    read -s -p "Enter password for the private key: " passphrase
-    printf "\n"
-    read -s -p "Enter password again: " passphrase_confirm
-    printf "\n"
-
-    if [ "$passphrase" != "$passphrase_confirm" ]; then
-      echo "Password don't match."
-    fi
-  done
-  
-  # TODO: insert random bytes
-  # TODO: custom Name-Comment and Name-Email
-  # TODO: allow for empty passphrases
-  $GPG --homedir "$TMPWORK" --gen-key --batch <<EOF
-    Key-Type: RSA
-    Key-Length: 4096
-    Subkey-Type: ELG-E
-    Subkey-Length: 4096
-    Name-Real: $NODE
-    Name-Email: root@$NODE
-    Expire-Date: 0
-    Passphrase: $passphrase
-    %commit
-EOF
-
-  # Encrypt the result
-  echo "Encrypting secret key into keyringer..."
-  $GPG --armor --homedir "$TMPWORK" --export-secret-keys | keyringer_exec encrypt "$BASEDIR" "$FILE"
-  echo "Encrypting public key into keyringer..."
-  $GPG --armor --homedir "$TMPWORK" --export             | keyringer_exec encrypt "$BASEDIR" "$FILE.pub"
-  echo "Encrypting passphrase into keyringer..."
-  echo "Passphrase for $FILE: $passphrase"               | keyringer_exec encrypt "$BASEDIR" "$FILE.passwd"
-
-  if [ ! -z "$OUTFILE" ]; then
-    mkdir -p `dirname $OUTFILE`
-    printf "Saving copies at %s and %s.pub\n" "$OUTFILE" "$OUTFILE"
-    $GPG --armor --homedir "$TMPWORK" --export-secret-keys > "$OUTFILE"
-    $GPG --armor --homedir "$TMPWORK" --export             > "$OUTFILE.pub"
-  fi
-
-  echo "Done"  
-}
-
-# Generate a keypair, ssl version
-function genpair_ssl {
-  echo "Make sure that $KEYDIR is atop of an encrypted volume."
-  read -p "Hit ENTER to continue." prompt
-
-  # Check for wildcard certs
-  if [ "`echo $NODE | cut -d . -f 1`" == "*" ]; then
-    WILDCARD="yes"
-    CNAME="$NODE"
-    NODE="`echo $NODE | sed -e 's/^\*\.//'`"
-  else
-    CNAME="${NODE}"
-  fi
-
-  # Setup
-  cd "$TMPWORK"
-
-  # Generate certificate
-cat <<EOF >> openssl.conf
-[ req ]
-default_keyfile         = ${NODE}_privatekey.pem
-distinguished_name      = req_distinguished_name
-encrypt_key             = no
-req_extensions          = v3_req # Extensions to add to certificate request
-string_mask             = nombstr
-
-[ req_distinguished_name ]
-commonName_default              = ${CNAME}
-organizationName                = Organization Name
-organizationalUnitName          = Organizational Unit Name
-emailAddress                    = Email Address
-localityName                    = Locality
-stateOrProvinceName             = State
-countryName                     = Country Name
-commonName                      = Common Name
-
-[ v3_req ]
-extendedKeyUsage=serverAuth,clientAuth
-EOF
-
-  # Add SubjectAltNames so wildcard certs can work correctly.
-  if [ "$WILDCARD" == "yes" ]; then
-cat <<EOF >> openssl.conf
-subjectAltName=DNS:${NODE}, DNS:${CNAME}
-EOF
-  fi
-
-  echo "Please review your OpenSSL configuration:"
-  cat openssl.conf
-  read -p "Hit ENTER to continue." prompt
-
-  openssl req -batch -nodes -config openssl.conf -newkey rsa:2048 -sha256 \
-          -keyout ${NODE}_privatekey.pem -out ${NODE}_csr.pem
-
-  openssl req -noout -text -in ${NODE}_csr.pem
-
-  # Self-sign
-  if [ "$KEYTYPE" == "ssl-self" ]; then
-    openssl x509 -in "${NODE}_csr.pem" -out "$NODE.crt" -req -signkey "${NODE}_privatekey.pem" -days 365
-    chmod 600 "${NODE}_privatekey.pem"
-  fi
-
-  # Encrypt the result
-  echo "Encrypting private key into keyringer..."
-  cat "${NODE}_privatekey.pem" | keyringer_exec encrypt "$BASEDIR" "$FILE.pem"
-  echo "Encrypting certificate request into keyringer..."
-  cat "${NODE}_csr.pem"        | keyringer_exec encrypt "$BASEDIR" "$FILE.csr"
-  
-  if [ "$KEYTYPE" == "ssl-self" ]; then
-    echo "Encrypting certificate into keyringer..."
-    cat "${NODE}.crt" | keyringer_exec encrypt "$BASEDIR" "$FILE.crt"
-  elif [ -f "$BASEDIR/keys/$FILE.crt.asc" ]; then
-    # Remove any existing crt
-    keyringer_exec del "$BASEDIR" "$FILE.crt"
-  fi
-
-  cd "$CWD"
-
-  if [ ! -z "$OUTFILE" ]; then
-    mkdir -p `dirname $OUTFILE`
-    printf "Saving copies at %s\n" "`dirname $OUTFILE`"
-    cat "$TMPWORK/${NODE}_privatekey.pem" > "$OUTFILE.pem"
-    cat "$TMPWORK/${NODE}_csr.pem"        > "$OUTFILE.csr"
-
-    if [ -f "$TMPWORK/${NODE}.crt" ]; then
-      cat "$TMPWORK/${NODE}.crt" > "$OUTFILE.crt"
-    fi
-  fi
-
-  # Show cert fingerprint
-  if [ "$KEYTYPE" == "ssl-self" ]; then
-    openssl x509 -noout -in "$TMPWORK/${NODE}.crt" -fingerprint
-  fi
-
-  echo "Done"
-}
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer"
-source "$LIB/functions" || exit 1
-
-# Aditional parameters
-KEYTYPE="$2"
-FILE="$3"
-NODE="$4"
-OUTFILE="$5"
-CWD="`pwd`"
-
-# Verify
-if [ -z "$NODE" ]; then
-  echo -e "Usage: keyringer <keyring> $BASENAME <gpg|ssh|ssl|ssl-self> <file> <hostname> [outfile]"
-  echo -e "Options:"
-  echo -e "\t gpg|ssh|ssl[-self]: key type."
-  echo -e "\t file                      : base file name for encrypted output (relative to keys folder),"
-  echo -e "\t                             without spaces"
-  echo -e "\t hostname                  : host for the key pair"
-  echo -e "\t outfile                   : optional unencrypted output file, useful for deployment,"
-  echo -e "\t                             without spaces"
-  exit 1
-elif [ ! -e "$KEYDIR" ]; then
-  echo "Folder not found: $KEYDIR, leaving"
-  exit 1
-fi
-
-# Set a tmp file
-keyringer_set_tmpfile genpair -d
-
-# Dispatch
-echo "Generating $KEYTYPE key for $NODE..."
-if [ "$KEYTYPE" == "ssl-self" ]; then
-  genpair_ssl
-else
-  genpair_"$KEYTYPE"
-fi
-
-# Cleanup
-cd "$CWD"
-rm -rf "$TMPWORK"
-trap - EXIT
diff --git a/share/keyringer/git b/share/keyringer/git
deleted file mode 100755
index cd2a188..0000000
--- a/share/keyringer/git
+++ /dev/null
@@ -1,16 +0,0 @@
-#!/bin/bash
-#
-# Git wrapper.
-#
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
-source "$LIB" || exit 1
-
-# Aditional parameters
-CWD="`pwd`"
-
-# Run git command
-shift
-mkdir -p "$BASEDIR" && cd "$BASEDIR" && git $*
-cd "$CWD"
diff --git a/share/keyringer/ls b/share/keyringer/ls
deleted file mode 100755
index 31e8805..0000000
--- a/share/keyringer/ls
+++ /dev/null
@@ -1,16 +0,0 @@
-#!/bin/bash
-#
-# List keys.
-#
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
-source "$LIB" || exit 1
-
-# Aditional parameters
-CWD="`pwd`"
-
-# Run list command
-shift
-cd "$KEYDIR" && ls $*
-cd "$CWD"
diff --git a/share/keyringer/open b/share/keyringer/open
deleted file mode 120000
index 8491ab9..0000000
--- a/share/keyringer/open
+++ /dev/null
@@ -1 +0,0 @@
-edit
-\ No newline at end of file
diff --git a/share/keyringer/options b/share/keyringer/options
deleted file mode 100755
index 3047380..0000000
--- a/share/keyringer/options
+++ /dev/null
@@ -1,30 +0,0 @@
-#!/bin/bash
-#
-# Recipient management.
-#
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer"
-source "$LIB/functions" || exit 1
-
-# Command parser
-keyringer_get_command "$2"
-
-# Create options file if old repository
-if [ ! -e "$OPTIONS" ]; then
-  echo "Creating options file..."
-  touch "$OPTIONS"
-  keyringer_exec git "$BASEDIR" add config/options
-fi
-
-if [ "$COMMAND" == "ls" ]; then
-  cat "$OPTIONS"
-elif [ "$COMMAND" == "edit" ]; then
-  "$EDITOR" "$OPTIONS"
-elif [ "$COMMAND" == "add" ]; then
-  shift 2
-  echo $* >> "$OPTIONS"
-else
-  printf "%s: No such command %s\n"  "$BASENAME" "$COMMAND"
-  exit 1
-fi
diff --git a/share/keyringer/preferences b/share/keyringer/preferences
deleted file mode 100755
index 2819b50..0000000
--- a/share/keyringer/preferences
+++ /dev/null
@@ -1,37 +0,0 @@
-#!/bin/bash
-#
-# Manipulate preferences.
-#
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
-source "$LIB" || exit 1
-
-COMMAND="$2"
-
-if [ -z "$COMMAND" ]; then
-  echo "Usage: keyringer <keyring> preferences <command> [arguments]"
-  echo "Available commands:"
-  echo "	ls"
-  echo "	edit"
-  echo "	add"
-  exit 1
-fi
-
-# Create options file if old repository
-if [ ! -e "$PREFERENCES" ]; then
-  echo "Creating preferences file..."
-  touch "$PREFERENCES"
-fi
-
-if [ "$COMMAND" == "ls" ]; then
-  cat "$PREFERENCES"
-elif [ "$COMMAND" == "edit" ]; then
-  "$EDITOR" "$PREFERENCES"
-elif [ "$COMMAND" == "add" ]; then
-  shift 2
-  [[ -n $* ]] && echo $* >> "$PREFERENCES"
-else
-  printf "%s: No such command %s\n" "$BASENAME" "$COMMAND"
-  exit 1
-fi
diff --git a/share/keyringer/recipients b/share/keyringer/recipients
deleted file mode 100755
index 0460842..0000000
--- a/share/keyringer/recipients
+++ /dev/null
@@ -1,46 +0,0 @@
-#!/bin/bash
-#
-# Recipient management.
-#
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer"
-source "$LIB/functions" || exit 1
-
-# Command parser
-keyringer_get_command "$2"
-
-# Set recipients file
-keyringer_set_new_recipients "$3"
-
-if [ "$COMMAND" == "ls" ]; then
-  if [ ! -z "$3" ]; then
-    if [ -e "$RECIPIENTS_FILE" ]; then
-      cat "$RECIPIENTS_FILE"
-    else
-      echo "Recipients file not found: $RECIPIENTS_FILE_BASE"
-      exit 1
-    fi
-  else
-    for recipients in `ls $RECIPIENTS`; do
-      echo "In recipients file $recipients:"
-      echo "-----------------------------------------------------------------------------------"
-      cat $RECIPIENTS/$recipients
-      echo ""
-    done
-  fi
-elif [ "$COMMAND" == "edit" ]; then
-  if [ ! -z "$3" ]; then
-    keyringer_create_new_recipients $RECIPIENTS_FILE
-    $EDITOR "$RECIPIENTS_FILE"
-    keyringer_check_recipients
-    keyringer_exec git "$BASEDIR" add "$RECIPIENTS_FILE_BASE"
-  else
-    echo "Please specify one recipient to edit among the available:"
-    ls $RECIPIENTS | sed -e 's/^/\t/'
-    exit 1
-  fi
-else
-  printf "%s: No such command %s\n" "$BASENAME" "$COMMAND"
-  exit 1
-fi
diff --git a/share/keyringer/recrypt b/share/keyringer/recrypt
deleted file mode 100755
index 63f7bc6..0000000
--- a/share/keyringer/recrypt
+++ /dev/null
@@ -1,45 +0,0 @@
-#!/bin/bash
-#
-# Re-encrypt files to multiple recipients.
-#
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
-source "$LIB" || exit 1
-
-function keyringer_recrypt {
-  # Get file
-  keyringer_get_file "$1"
-
-  # Set recipients file
-  keyringer_set_recipients "$FILE"
-
-  # Decrypt
-  decrypted="$($GPG --use-agent -d "$KEYDIR/$FILE" 2> /dev/null)"
-
-  if [ "$?" != "0" ]; then
-    echo "Decryption error."
-    exit 1
-  fi
-
-  # Recrypt
-  recrypted="`echo "$decrypted" | $GPG --use-agent --armor -e -s $(keyringer_recipients "$RECIPIENTS_FILE")`"
-
-  if [ "$?" != "0" ]; then
-    echo "Recryption error."
-    exit 1
-  fi
-
-  unset decrypted
-  echo "$recrypted" > "$KEYDIR/$FILE"
-}
-
-if [ ! -z "$2" ]; then
-  keyringer_recrypt $2
-else
-  cd $KEYDIR && find | while read file; do
-    if [ ! -d "$KEYDIR/$file" ]; then
-      keyringer_recrypt "$file"
-    fi
-  done
-fi
diff --git a/share/keyringer/usage b/share/keyringer/usage
deleted file mode 100755
index a4602ac..0000000
--- a/share/keyringer/usage
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/bin/bash
-#
-# Show available commands
-#
-
-# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
-source "$LIB" || exit 1
-
-keyringer_usage
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>.
diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn
index d7fb2a6..ee035e3 100644
--- a/share/man/keyringer.1.mdwn
+++ b/share/man/keyringer.1.mdwn
@@ -1,6 +1,6 @@
 % KEYRINGER(1) Keyringer User Manual
-% Silvio Rhatto
-% Sep 10, 2013
+% Silvio Rhatto <rhatto@riseup.net>
+% Oct 25, 2013
 
 # NAME
 
@@ -12,159 +12,214 @@ keyringer <*keyring*> <*action*> [*options*]...
 
 # DESCRIPTION
 
-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.
 
-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.
+
+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.
-2. Secret manipulation actions.
-3. Configuration 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
+# 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.
+:   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).
+    After initialization, *path* will contain a folder structure for storing secrets
+    and metadata (user aka recipients, groups of recipients, etc).
 
-   Also, an entry on `$HOME/.keyringer/config` will be added allowing keyringer to
-   find the keyring by it's alias.
+    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 that it will be applied into the keyring repository.
+:   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.
+:   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
+# SECRET MANIPULATION ACTIONS
 
-All secret manipulation actions operates upon a *secret* which is the pathname
-of an encrypted file relative to keyring with optional `.asc` extension.
+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 ommited, keyringer will add it in the end of the
+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.
-After any manipulation, the user has to manually commit the changes using the
-git wrapper action.
+Instead, the user has to manually commit the changes using the git wrapper
+action.
 
 append <*secret*>
-:  Append contents into a 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.
+:   Append contents into a secret, batch mode.
 
 decrypt <*secret*>
-:  Decrypts a secret into standard output.
+:   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. To completely remove a file from a keyring,
-   you should also rewrite the git history by yourself.
+:   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.
 
 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.
+:   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 [*file*] <*secret*>
-:  Encrypts content from standard input or *file* into *secret* pathname. No spaces
-   are supported in the *file* name.
+encrypt <*secret*> [*file*]
+:   Encrypts content from standard input or *file* into *secret* pathname. No spaces
+    are supported in the *secret* name.
 
 encrypt-batch <*secret*>
-:  Encrypt content, batch mode.
+:   Encrypt content, batch mode.
 
 genpair <*ssh*|*gpg*|*ssl*|*ssl-self*> [*options*]
-:  Wrapper to generete encryption keypairs, useful for automated key deployment.
+:   Wrapper to generate encryption key-pairs, useful for automated key deployment.
 
 open <*secret*>
-:  Open a secret using xdg-open.
+:   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*>
-:  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
-   are re-encrypted.
+:   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
+# CONFIGURATION ACTIONS
 
 commands
-:  List available actions, useful for shell completion and syntax check.
+:   List available actions, useful for shell completion and syntax check.
 
 options <*ls*|*edit*|*add*>
-:  List, edit or add miscelaneous *repository* options.
+:   List, edit or add miscellaneous *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.
+    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.
+:   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.
 
-   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.
+    Preferences are written using the *KEY=VALUE* syntax. All lines starting with the
+    hash (#) character are interpreted as comments.
 
-recipients <*ls*|*edit*> <*recipient-file*>
-:  List or edit recipient configuration.
+usage
+:   Show keyringer usage information.
 
-   Recipient files are lists of OpenPGP public key fingerprints which are used
-   by keyringer when encrypting secrets.
+recipients <*ls*|*edit*> <*recipients-file*>
+:   List, create or edit recipients configuration.
 
-   Keyringer uses a default recipient file and supports custom *recipient-files* which
-   overrides the default recipient file according to it's matching pathname.
+    Recipients files are lists of OpenPGP public key fingerprints which are used
+    by keyringer when encrypting secrets and associated with email aliases.
 
-   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.
+    Keyringer uses a default recipients file, but specifying a custom *recipients-file*
+    pathname will override this default.
 
-### OPTIONS
+    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`.
 
-ls
-:  List all existing recipient files.
+    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.*
 
-edit
-:  Create or edit a recipient-file.
+    All lines starting with the hash (#) character are interpreted as comments.
 
-   Edition happens using the editor specified by the `$EDITOR`
-   environment variable.
+    Parameters to the *recipients* action are:
 
-   The required parameter *recipient-file* is taken relativelly
-   from the `$KEYRING_FOLDER/config/recipients/` folder.
+      *ls*
+      :   List all existing recipients files.
 
-usage
-:  Show keyringer usage information.
+      *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.
+:  User's main configuration file used to map alias names to keyrings.
 
 $HOME/.keyringer/*keyring*
-: User preferences for the keyringer aliased *keyring* 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.
+:  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.
+
 # SEE ALSO
 
 The *README* file distributed with Keyringer contains full documentation.
diff --git a/share/man/keyringer.pot b/share/man/keyringer.pot
new file mode 100644
index 0000000..2e32952
--- /dev/null
+++ b/share/man/keyringer.pot
@@ -0,0 +1,602 @@
+# Keyringer translation source
+# Copyright (C) 2013 Keyringer Developers
+# This file is distributed under the same license as the keyringer package.
+# Silvio Rhatto <rhatto@riseup.net>, 2013.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: Keyringer\n"
+"POT-Creation-Date: 2013-11-10 23:20-0100\n"
+"PO-Revision-Date: 2013-11-10 23:20-0100\n"
+"Last-Translator: Keyringer Developers <contact@keyringer.pw>\n"
+"Language-Team: Keyringer Developers <contact@keyringer.pw>\n"
+"Language: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. type: Plain text
+#: keyringer.1.mdwn:4
+msgid ""
+"% KEYRINGER(1) Keyringer User Manual % Silvio Rhatto <rhatto@riseup.net> % "
+"Oct 25, 2013"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:6
+msgid "# NAME"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:8
+msgid "keyringer - encrypted and distributed secret sharing software"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:10
+msgid "# SYNOPSIS"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:12
+msgid "keyringer <*keyring*> <*action*> [*options*]..."
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:14
+msgid "# DESCRIPTION"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:17
+msgid ""
+"Keyringer lets you manage and share secrets using GnuPG and Git in a "
+"distributed fashion."
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:22
+msgid ""
+"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."
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:25
+msgid ""
+"Secrets are encrypted using GPG and added to a Git tree so that they can be "
+"synced with remote branches later."
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:27
+msgid "# ACTIONS"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:29
+msgid "Keyringer has three types of actions:"
+msgstr ""
+
+#. type: Bullet: '1. '
+#: keyringer.1.mdwn:32
+msgid ""
+"Repository lookup and manipulation actions, which handle repository "
+"initialization, content tracking and navigation."
+msgstr ""
+
+#. type: Bullet: '2. '
+#: keyringer.1.mdwn:35
+msgid ""
+"Secret manipulation actions, which take care of encrypting, decrypting and "
+"other read/write operations on secrets."
+msgstr ""
+
+#. type: Bullet: '3. '
+#: keyringer.1.mdwn:37
+msgid "Configuration actions, handling repository metadata."
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:39
+msgid "# REPOSITORY LOOKUP AND MANIPULATION ACTIONS"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:43
+#, no-wrap
+msgid ""
+"init <*path*> [*remote*]\n"
+":   Initialize a new keyringer repository. If a *remote* URL is specified, "
+"keyringer will\n"
+"    clone an existing repository.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:46
+#, no-wrap
+msgid ""
+"    After initialization, *path* will contain a folder structure for storing "
+"secrets\n"
+"    and metadata (user aka recipients, groups of recipients, etc).\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:49
+#, no-wrap
+msgid ""
+"    Also, an entry will be added to `$HOME/.keyringer/config` allowing "
+"keyringer to\n"
+"    find the keyring by its alias.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:53
+#, no-wrap
+msgid ""
+"git <*action*> <*options*>\n"
+":   Git wrapper that operates from the toplevel keyring repository. You can "
+"issue any\n"
+"    *GIT(1)* subcommand with this action to have it applied in the keyring "
+"repository.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:58
+#, no-wrap
+msgid ""
+"ls <*path*>\n"
+":   List contents from the toplevel repository *keys* folder or from "
+"relative paths\n"
+"    if *path* is specified. Like the git wrapper, this is a wrapper around "
+"the *LS(1)*\n"
+"    command.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:60
+msgid "# SECRET MANIPULATION ACTIONS"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:63
+msgid ""
+"All secret manipulation actions operate upon a *secret* which is the "
+"pathname of an encrypted file relative to the keyring with optional `.asc` "
+"extension."
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:66
+msgid ""
+"If the `.asc` extension is omitted, keyringer will add it at the end of the "
+"pathname."
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:68
+msgid "No spaces are allowed in the secret name."
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:72
+msgid ""
+"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."
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:76
+#, no-wrap
+msgid ""
+"append <*secret*>\n"
+":   Append contents into a secret by decrypting the secret, appending lines "
+"read\n"
+"    from the standard input and encrypting again.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:79
+#, no-wrap
+msgid ""
+"append-batch <*secret*>\n"
+":   Append contents into a secret, batch mode.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:82
+#, no-wrap
+msgid ""
+"decrypt <*secret*>\n"
+":   Decrypts a secret into standard output.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:86
+#, no-wrap
+msgid ""
+"del <*secret*>\n"
+":   Removes a secret using Git. After deleting a secret a git commit and "
+"push is still\n"
+"    needed to update remote repositories.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:90
+#, no-wrap
+msgid ""
+"    Please note that this command **does not remove the secret from the Git "
+"history.**\n"
+"    To completely remove a file from a keyring, you should also rewrite the "
+"Git\n"
+"    history yourself.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:94
+#, no-wrap
+msgid ""
+"edit <*secret*>\n"
+":   Edit a secret by temporarily decrypting it, opening the decrypted copy "
+"into the \n"
+"    text editor defined by the *$EDITOR* environment variable and then "
+"re-encrypting it.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:98
+#, no-wrap
+msgid ""
+"encrypt <*secret*> [*file*]\n"
+":   Encrypts content from standard input or *file* into *secret* "
+"pathname. No spaces\n"
+"    are supported in the *secret* name.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:101
+#, no-wrap
+msgid ""
+"encrypt-batch <*secret*>\n"
+":   Encrypt content, batch mode.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:104
+#, no-wrap
+msgid ""
+"genpair <*ssh*|*gpg*|*ssl*|*ssl-self*> [*options*]\n"
+":   Wrapper to generate encryption key-pairs, useful for automated key "
+"deployment.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:108
+#, no-wrap
+msgid ""
+"open <*secret*>\n"
+":   Decrypt a secret into a temporary folder and open it using xdg-open, "
+"which\n"
+"    tries to figure out the file type and then calls the associated "
+"application.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:111
+#, no-wrap
+msgid ""
+"    After the application exits, keyringer encrypts the temporary decrypted "
+"file\n"
+"    again into the secret file and deletes the temporary file.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:116
+#, no-wrap
+msgid ""
+"recrypt <*secret*>\n"
+":   Re-encrypts a secret by decrypting it and encrypting it again. Useful "
+"when users are added\n"
+"    into the recipient configuration. If no *secret* is given, all secrets "
+"in the repository\n"
+"    are re-encrypted.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:118
+msgid "# CONFIGURATION ACTIONS"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:121
+#, no-wrap
+msgid ""
+"commands\n"
+":   List available actions, useful for shell completion and syntax check.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:124
+#, no-wrap
+msgid ""
+"options <*ls*|*edit*|*add*>\n"
+":   List, edit or add miscellaneous *repository* options.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:128
+#, no-wrap
+msgid ""
+"    Repository options are settings which are saved in the repository as a "
+"*global*\n"
+"    configuration stanza for a given keyring, shared by all users with "
+"access to\n"
+"    the repository.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:131
+#, no-wrap
+msgid ""
+"    Options are written using the *KEY=VALUE* syntax. All lines starting "
+"with the\n"
+"    hash (#) character are interpreted as comments.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:134
+#, no-wrap
+msgid ""
+"preferences <*ls*|*edit*|*add*>\n"
+":   List, edit or add *user* preferences for a given repository.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:137
+#, no-wrap
+msgid ""
+"    User preferences are settings which are saved in the user's keyringer "
+"folder\n"
+"    (`$HOME/.keyringer/`), and not shared with the other users.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:140
+#, no-wrap
+msgid ""
+"    Preferences are written using the *KEY=VALUE* syntax. All lines starting "
+"with the\n"
+"    hash (#) character are interpreted as comments.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:143
+#, no-wrap
+msgid ""
+"usage\n"
+":   Show keyringer usage information.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:146
+#, no-wrap
+msgid ""
+"recipients <*ls*|*edit*> <*recipients-file*>\n"
+":   List, create or edit recipients configuration.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:149
+#, no-wrap
+msgid ""
+"    Recipients files are lists of OpenPGP public key fingerprints which are "
+"used\n"
+"    by keyringer when encrypting secrets and associated with email "
+"aliases.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:152
+#, no-wrap
+msgid ""
+"    Keyringer uses a default recipients file, but specifying a custom "
+"*recipients-file*\n"
+"    pathname will override this default.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:158
+#, no-wrap
+msgid ""
+"    For instance, if a user encrypts a secret to a file in the keyring "
+"repository's\n"
+"    *accounting* folder, a *recipients-file* under *accounting* will be "
+"used.\n"
+"    Encrypting a secret into *accounting/bank-accounts* will result in a "
+"file\n"
+"   `$KEYRING_FOLDER/keys/accounting/bank-accounts.asc` encrypted using the "
+"public\n"
+"    keys listed in the config "
+"file`$KEYRING_FOLDER/config/recipients/accounting`.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:163
+#, no-wrap
+msgid ""
+"    Each line in a recipients file has entries in the format\n"
+"    'john@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', where "
+"*john@doe.com*\n"
+"    is an alias for the GPG public key whose fingerprint is\n"
+"    *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.*\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:165
+#, no-wrap
+msgid ""
+"    All lines starting with the hash (#) character are interpreted as "
+"comments.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:167
+#, no-wrap
+msgid "    Parameters to the *recipients* action are:\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:170
+#, no-wrap
+msgid ""
+"      *ls*\n"
+"      :   List all existing recipients files.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:173
+#, no-wrap
+msgid ""
+"      *edit*\n"
+"      :   Create or edit a recipients file.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:176
+#, no-wrap
+msgid ""
+"          Editing happens using the editor specified by the `$EDITOR`\n"
+"          environment variable.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:179
+#, no-wrap
+msgid ""
+"          The required parameter *recipients-file* is interpreted relative\n"
+"          to the `$KEYRING_FOLDER/config/recipients/` folder.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:181
+msgid "# FILES"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:184
+msgid ""
+"$HOME/.keyringer/config : User's main configuration file used to map alias "
+"names to keyrings."
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:187
+msgid ""
+"$HOME/.keyringer/*keyring* : User preferences for the keyringer aliased "
+"*keyring* keyring."
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:191
+#, no-wrap
+msgid ""
+"$KEYRING_FOLDER/config/options\n"
+":  Custom keyring options which will be applied for all users that use\n"
+"   the keyringer repository.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:193
+msgid "# LIMITATIONS"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:195
+msgid "Keyringer currently has the following limitations:"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:201
+#, no-wrap
+msgid ""
+"1. Metadata is not encrypted, meaning that an attacker with access to a "
+"keyringer\n"
+"  repository can discover all public key IDs used for encryption, and which "
+"secrets\n"
+"  are encrypted to which keys. This can be improved in the future by "
+"encrypting\n"
+"  the repository configuration with support for the *--hidden-recipient* "
+"GnuPG\n"
+"  option.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:206
+#, no-wrap
+msgid ""
+"2. History is not rewritten by default when secrets are removed from a "
+"keyringer\n"
+"  repository. After a secret is removed with the *del* action, it will still "
+"be\n"
+"  available in the repository history even after a commit. This is by "
+"design\n"
+"  for the following reasons:\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:211
+#, no-wrap
+msgid ""
+"  - It's the default behavior of the Git content tracker. Forcing the\n"
+"     deletion by default could break the expected behavior and hence limit\n"
+"     the repository's backup features, which can be helpful if someone\n"
+"     mistakenly overwrites a secret.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:215
+#, no-wrap
+msgid ""
+"  - History rewriting cannot be considered a security measure against the\n"
+"     unauthorized access to a secret as it doesn't automatically update "
+"all\n"
+"     working copies of the repository.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:219
+#, no-wrap
+msgid ""
+"     In the case that the secret is a passphrase, the recommended measure\n"
+"     against such attacks is to change the passphrase, making useless the\n"
+"     knowledge of the previous secret.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:222
+#, no-wrap
+msgid ""
+"     Users wishing to edit their repository history should proceed "
+"manually\n"
+"     using the *git* action.\n"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:224
+msgid "# SEE ALSO"
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:226
+msgid "The *README* file distributed with Keyringer contains full documentation."
+msgstr ""
+
+#. type: Plain text
+#: keyringer.1.mdwn:228
+msgid ""
+"The Keyringer source code and all documentation may be downloaded from "
+"<https://keyringer.pw>."
+msgstr ""