aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSilvio Rhatto <rhatto@riseup.net>2013-11-14 18:39:49 -0200
committerSilvio Rhatto <rhatto@riseup.net>2013-11-14 18:39:49 -0200
commitf978a7fcc7917df39a64800838e814927971469e (patch)
treef896cbdf16d66610b9eb070d9e640090f3e9a2cc
parent1b1197728cfd029deb46ebbe6ac0a70bcee58510 (diff)
parent9cd7165a5a63a5824a327920b428eeed8aec528e (diff)
downloadkeyringer-f978a7fcc7917df39a64800838e814927971469e.tar.gz
keyringer-f978a7fcc7917df39a64800838e814927971469e.tar.bz2
Imported Upstream version 0.2.7upstream_keyringer_0.2.7
-rw-r--r--ChangeLog22
-rw-r--r--Makefile8
-rw-r--r--development.mdwn48
-rw-r--r--index.mdwn16
-rwxr-xr-xkeyringer18
-rwxr-xr-xlib/keyringer/actions/append (renamed from share/keyringer/append)5
l---------lib/keyringer/actions/append-batch (renamed from share/keyringer/append-batch)0
-rwxr-xr-xlib/keyringer/actions/commands (renamed from share/keyringer/commands)2
-rwxr-xr-xlib/keyringer/actions/decrypt (renamed from share/keyringer/decrypt)2
-rwxr-xr-xlib/keyringer/actions/del (renamed from share/keyringer/del)2
-rwxr-xr-xlib/keyringer/actions/edit (renamed from share/keyringer/edit)10
-rwxr-xr-xlib/keyringer/actions/encrypt87
l---------lib/keyringer/actions/encrypt-batch (renamed from share/keyringer/encrypt-batch)0
-rwxr-xr-xlib/keyringer/actions/genpair (renamed from share/keyringer/genpair)4
-rwxr-xr-xlib/keyringer/actions/git (renamed from share/keyringer/git)2
-rwxr-xr-xlib/keyringer/actions/ls (renamed from share/keyringer/ls)2
l---------lib/keyringer/actions/open (renamed from share/keyringer/open)0
-rwxr-xr-xlib/keyringer/actions/options (renamed from share/keyringer/options)4
-rwxr-xr-xlib/keyringer/actions/preferences (renamed from share/keyringer/preferences)2
-rwxr-xr-xlib/keyringer/actions/recipients (renamed from share/keyringer/recipients)4
-rwxr-xr-xlib/keyringer/actions/recrypt (renamed from share/keyringer/recrypt)2
-rwxr-xr-xlib/keyringer/actions/usage (renamed from share/keyringer/usage)2
-rw-r--r--lib/keyringer/completions/bash/keyringer18
-rw-r--r--lib/keyringer/completions/zsh/_keyringer3
-rwxr-xr-xlib/keyringer/functions121
-rwxr-xr-xshare/keyringer/encrypt56
-rw-r--r--share/man/keyringer.1335
-rw-r--r--share/man/keyringer.1.mdwn221
-rw-r--r--share/man/keyringer.pot602
29 files changed, 1287 insertions, 311 deletions
diff --git a/ChangeLog b/ChangeLog
index 7e946d4..b66f924 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,25 @@
+2013-11-14 - 0.2.7 Silvio Rhatto <rhatto@riseup.net>
+
+ Ramdisk check for temporary folders (closes #13)
+
+ Shred of temporary files (closes #27)
+
+ Encrypt/open improvements (closes #9)
+
+ Initialization now asks user to edit the default preferences file
+
+ Usage improvements
+
+ Added keyringer.pot for easy manpage translation (closes #5)
+
+ Changed encrypt syntax
+
+ Fix handing of file names with spaces (#20)
+
+ Manpage enhancements and english review (#5)
+
+ Strict FHS compliance (closes #18)
+
2013-10-04 - 0.2.6 Silvio Rhatto <rhatto@riseup.net>
Removing debian specifics from the master branch (#1)
diff --git a/Makefile b/Makefile
index 374579c..7d734ff 100644
--- a/Makefile
+++ b/Makefile
@@ -24,10 +24,8 @@ clean:
install_lib:
$(INSTALL) -D --mode=0755 lib/keyringer/functions $(DESTDIR)/$(PREFIX)/lib/$(PACKAGE)/functions
-
-install_share:
- $(INSTALL) -D --mode=0755 -d share/keyringer $(DESTDIR)/$(PREFIX)/share/$(PACKAGE)
- $(INSTALL) -D --mode=0755 share/keyringer/* $(DESTDIR)/$(PREFIX)/share/$(PACKAGE)
+ $(INSTALL) -D --mode=0755 -d lib/keyringer/actions $(DESTDIR)/$(PREFIX)/lib/$(PACKAGE)/actions
+ $(INSTALL) -D --mode=0755 lib/keyringer/actions/* $(DESTDIR)/$(PREFIX)/lib/$(PACKAGE)/actions
install_bin:
$(INSTALL) -D --mode=0755 keyringer $(DESTDIR)/$(PREFIX)/bin/keyringer
@@ -44,7 +42,7 @@ install_completion:
$(INSTALL) -D --mode=0644 lib/keyringer/completions/zsh/_keyringer $(DESTDIR)/$(PREFIX)/share/zsh/vendor-completions/_keyringer
install: clean
- @make install_lib install_share install_bin install_doc install_man install_completion
+ @make install_lib install_bin install_doc install_man install_completion
build_man:
pandoc -s -w man share/man/keyringer.1.mdwn -o share/man/keyringer.1
diff --git a/development.mdwn b/development.mdwn
index d312bf2..26a865c 100644
--- a/development.mdwn
+++ b/development.mdwn
@@ -1,9 +1,14 @@
[[!meta title="Keyringer: development guidelines and workflow"]]
+Index
+-----
+
+[[!toc levels=4]]
+
Development environment
-----------------------
-The following steps needs to be run just once.
+The following steps needs to be run just once for each arch and distro version.
### Create the `debian/` structure
@@ -13,7 +18,7 @@ The following steps needs to be run just once.
### Setup a sid pbuilder chroot
- DIST=sid sudo pbuilder create --debootstrapopts --variant=buildd
+ DIST=sid git-pbuilder create
### Setup a sid cowbuilder chroot
@@ -26,7 +31,7 @@ These steps should be run once in a while to ensure we have an up to date packag
### Pbuilder
- DIST=sid sudo pbuilder update
+ DIST=sid git-pbuilder update
### Cowbuilder
@@ -46,6 +51,7 @@ Prepare the source code:
Commit and tag a release:
+ VERSION="X.Y.Z"
git commit -a -m "Keyringer $VERSION"
git tag -s $VERSION -m "Keyringer $VERSION"
@@ -60,7 +66,7 @@ Sign the release ([see backupninja development guidelines](https://labs.riseup.n
Upload the release:
- scp keyringer-$VERSION.tar.bz2* server:/var/sites/keyringer/releases/
+ scp keyringer-$VERSION.tar.bz2* keyringer:/var/sites/keyringer/releases/
cd -
Update the debian branch:
@@ -82,19 +88,45 @@ Run lintian (or [add it to your pbuilder hooks](http://askubuntu.com/questions/1
lintian --info --display-info --pedantic --color auto \
../build-area/keyringer_$VERSION*.changes
+Create a signed tag in the debian branch:
+
+ git-buildpackage --git-tag-only --git-sign-tags
+
Notes:
* `git-import-orig` takes care of running `pristine-tar commit`, of merging of the tag and orig tarball into the upstream branch, and then it merges the result into the debian branch. With the above configuration, it also runs git-dch to do the bulk of the work in `debian/changelog`.
* To build a development package, checkout the debian branch, merge master, run `git-dch --auto --snapshot` and build.
-Adding a subcommand
--------------------
+Adding or changing a subcommand
+-------------------------------
-When adding a new subcommand, ensure:
+When adding a new subcommand or changing subcommand behavior, ensure:
+* Documentation is updated.
* Manpage is updated.
* Shell completions are updated.
+Test environment
+----------------
+
+Setup:
+
+ keyringer test init ~/code/tests/keyringer
+
+Teardown:
+
+ rm -rf ~/code/tests/keyringer
+ rm ~/.keyringer/test
+ sed -i -e '/^test=/d' ~/.keyringer/config
+
+Translation
+-----------
+
+Run just once:
+
+ cd share/man
+ po4a-gettextize -f text -m keyringer.1.mdwn -p keyringer.pot
+
References
----------
@@ -104,3 +136,5 @@ References
* [git-pbuilder](https://wiki.debian.org/git-pbuilder).
* [PackagingWithGit - Debian Wiki](https://wiki.debian.org/PackagingWithGit).
* [Generating pristine tarballs from git repositories](http://joeyh.name/blog/entry/generating_pristine_tarballs_from_git_repositories/).
+* [Debian Packaging](https://wiki.debian.org/Packaging).
+* [Debian Upstream Guide](https://wiki.debian.org/UpstreamGuide).
diff --git a/index.mdwn b/index.mdwn
index 5985cf6..148da07 100644
--- a/index.mdwn
+++ b/index.mdwn
@@ -4,6 +4,8 @@ Keyringer lets you manage and share secrets using GPG and git with custom
commands to encrypt, decrypt, recrypt, create key pairs, etc.
- Project page: [https://keyringer.pw](https://keyringer.pw)
+- Manpage: [keyringer.1](share/man/keyringer.1)
+- License: [GPLv3+](LICENSE)
- Issue tracker: [https://keyringer.pw/trac](https://keyringer.pw/trac)
- Tor hidden service: [http://y6ntvl5bzs3c7ffa.onion](http://y6ntvl5bzs3c7ffa.onion)
- Releases: [https://keyringer.pw/releases](releases)
@@ -84,28 +86,28 @@ secrets with lines such as:
emma - /dev/hda : : secret2
Or you may also have a different encrypted file for each secret, e.g. a file called
-emma.root that contains the root passphrase for the server named emma and
-another called emma.hda with the passphrase to decrypt /dev/hda on emma.
+emma.root that contains the root passphrase for the server named `emma` and
+another called emma.hda with the passphrase to decrypt `/dev/hda` on `emma`.
Encrypting a secret
- keyringer <keyring> encrypt <file>
+ keyringer <keyring> encrypt <secret>
Encrypting a secret from a file
- keyringer <keyring> encrypt <plaintext-file> <file>
+ keyringer <keyring> encrypt <secret> <plaintext-file>
Decrypting a secret (only to stdout)
- keyringer <keyring> decrypt <file>
+ keyringer <keyring> decrypt <secret>
Re-encrypting a secret or the whole repository
- keyringer <keyring> recrypt [file]
+ keyringer <keyring> recrypt [secret]
Appending information to a secret
- keyringer <keyring> append <file>
+ keyringer <keyring> append <secret>
Editing a secret
diff --git a/keyringer b/keyringer
index a4e8b2c..7aad6a0 100755
--- a/keyringer
+++ b/keyringer
@@ -68,7 +68,7 @@ function keyringer_init {
touch "$OPTIONS"
# Setup README
- echo "Keyring repository powered by http://git.sarava.org/?p=keyringer.git;a=summary" > "$BASEDIR/README"
+ echo "Keyring repository powered by https://keyringer.pw" > "$BASEDIR/README"
echo "" >> "$BASEDIR/README"
# Set config version
@@ -90,8 +90,16 @@ function keyringer_init {
# Init
if ! keyringer_is_git "$BASEDIR"; then
keyringer_exec git "$BASEDIR" init
+
+ # Edit default recipients
+ echo "Now you have to edit the default recipient configuration to be able to encrypt secrets."
+ echo "Press any key to proceed editing..."
+ read key
+ keyringer $KEYRING recipients edit default
+
+ # Stage and commit
keyringer_exec git "$BASEDIR" add .
- keyringer_exec git "$BASEDIR" commit -m Importing
+ keyringer_exec git "$BASEDIR" commit -m Initializing
fi
}
@@ -137,12 +145,12 @@ else
fi
# Set actions location
-if [ -e "`dirname $(readlink -f $0)`/share/$NAME" ]; then
+if [ -e "`dirname $(readlink -f $0)`/lib/$NAME/actions" ]; then
# Development or local installation layout
- ACTIONS="`dirname $(readlink -f $0)`/share/$NAME"
+ ACTIONS="`dirname $(readlink -f $0)`/lib/$NAME/actions"
else
# System installation layout
- ACTIONS="`dirname $(readlink -f $0)`/../share/$NAME"
+ ACTIONS="`dirname $(readlink -f $0)`/../lib/$NAME/actions"
fi
# Load functions
diff --git a/share/keyringer/append b/lib/keyringer/actions/append
index bcc9e5e..e945bff 100755
--- a/share/keyringer/append
+++ b/lib/keyringer/actions/append
@@ -4,7 +4,7 @@
#
# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
+LIB="`dirname $0`/../functions"
source "$LIB" || exit 1
# Get file
@@ -21,9 +21,6 @@ if [ "$BASENAME" == "append" ]; then
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[@]} )
diff --git a/share/keyringer/append-batch b/lib/keyringer/actions/append-batch
index 6b140f7..6b140f7 120000
--- a/share/keyringer/append-batch
+++ b/lib/keyringer/actions/append-batch
diff --git a/share/keyringer/commands b/lib/keyringer/actions/commands
index 139725a..2605666 100755
--- a/share/keyringer/commands
+++ b/lib/keyringer/actions/commands
@@ -4,7 +4,7 @@
#
# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
+LIB="`dirname $0`/../functions"
source "$LIB" || exit 1
keyringer_show_actions
diff --git a/share/keyringer/decrypt b/lib/keyringer/actions/decrypt
index bab9b34..2b1401c 100755
--- a/share/keyringer/decrypt
+++ b/lib/keyringer/actions/decrypt
@@ -4,7 +4,7 @@
#
# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
+LIB="`dirname $0`/../functions"
source "$LIB" || exit 1
# Get file
diff --git a/share/keyringer/del b/lib/keyringer/actions/del
index 4eca0e3..babd212 100755
--- a/share/keyringer/del
+++ b/lib/keyringer/actions/del
@@ -4,7 +4,7 @@
#
# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
+LIB="`dirname $0`/../functions"
source "$LIB" || exit 1
# Get file
diff --git a/share/keyringer/edit b/lib/keyringer/actions/edit
index fe05ecc..9a3e488 100755
--- a/share/keyringer/edit
+++ b/lib/keyringer/actions/edit
@@ -4,7 +4,7 @@
#
# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
+LIB="`dirname $0`/../functions"
source "$LIB" || exit 1
# Get file
@@ -13,11 +13,13 @@ keyringer_get_file "$2"
# Set recipients file
keyringer_set_recipients "$FILE"
-# Warn user
-echo "Make sure that $BASEDIR is atop of an encrypted volume."
+# Get original file EXTENSION
+FILENAME="$(basename "$FILE" .asc)"
+FILENAME="$(basename "$FILENAME")"
+EXTENSION="${FILENAME##*.}"
# Set a tmp file
-keyringer_set_tmpfile edit
+keyringer_set_tmpfile $BASENAME.$EXTENSION
# Decrypt the information to the file
$GPG --yes -o "$TMPWORK" --use-agent -d "$KEYDIR/$FILE"
diff --git a/lib/keyringer/actions/encrypt b/lib/keyringer/actions/encrypt
new file mode 100755
index 0000000..aadb9fa
--- /dev/null
+++ b/lib/keyringer/actions/encrypt
@@ -0,0 +1,87 @@
+#!/bin/bash
+#
+# Encrypt files to multiple recipients.
+#
+
+# Load functions
+LIB="`dirname $0`/../functions"
+source "$LIB" || exit 1
+
+# Usage
+function keyringer_usage_encrypt {
+ echo "Usage: keyringer <keyring> $BASENAME <secret> [file]"
+}
+
+# Alias for keyringer_usage_encrypt
+function keyringer_usage_encrypt_batch {
+ keyringer_usage_encrypt $*
+}
+
+# Usage
+if [ -z "$2" ]; then
+ keyringer_action_usage
+ exit 1
+fi
+
+# Aditional parameters
+if [ ! -z "$3" ]; then
+ # Set secret name and original file
+ FILE="$2"
+ shift 2
+ UNENCRYPTED_FILE="$*"
+
+ # Get original file EXTENSION
+ FILENAME="$(basename "$UNENCRYPTED_FILE")"
+ EXTENSION="${FILENAME##*.}"
+
+ # Append file extension in the secret name
+ #
+ # Useful when opening files and the application needs the
+ # extension to guess the file type.
+ if ! echo $FILE | grep -q -e "\.$EXTENSION$"; then
+ FILE="$FILE.$EXTENSION"
+ fi
+
+ keyringer_get_new_file $FILE
+
+ if [ ! -f "$UNENCRYPTED_FILE" ]; then
+ echo "Error: cannot encrypt $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 "Done. PLEASE 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/lib/keyringer/actions/encrypt-batch
index 8267197..8267197 120000
--- a/share/keyringer/encrypt-batch
+++ b/lib/keyringer/actions/encrypt-batch
diff --git a/share/keyringer/genpair b/lib/keyringer/actions/genpair
index f977714..f048bc7 100755
--- a/share/keyringer/genpair
+++ b/lib/keyringer/actions/genpair
@@ -179,8 +179,8 @@ EOF
}
# Load functions
-LIB="`dirname $0`/../../lib/keyringer"
-source "$LIB/functions" || exit 1
+LIB="`dirname $0`/../functions"
+source "$LIB" || exit 1
# Aditional parameters
KEYTYPE="$2"
diff --git a/share/keyringer/git b/lib/keyringer/actions/git
index cd2a188..3c4f435 100755
--- a/share/keyringer/git
+++ b/lib/keyringer/actions/git
@@ -4,7 +4,7 @@
#
# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
+LIB="`dirname $0`/../functions"
source "$LIB" || exit 1
# Aditional parameters
diff --git a/share/keyringer/ls b/lib/keyringer/actions/ls
index 31e8805..ec8080b 100755
--- a/share/keyringer/ls
+++ b/lib/keyringer/actions/ls
@@ -4,7 +4,7 @@
#
# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
+LIB="`dirname $0`/../functions"
source "$LIB" || exit 1
# Aditional parameters
diff --git a/share/keyringer/open b/lib/keyringer/actions/open
index 8491ab9..8491ab9 120000
--- a/share/keyringer/open
+++ b/lib/keyringer/actions/open
diff --git a/share/keyringer/options b/lib/keyringer/actions/options
index 3047380..8508aea 100755
--- a/share/keyringer/options
+++ b/lib/keyringer/actions/options
@@ -4,8 +4,8 @@
#
# Load functions
-LIB="`dirname $0`/../../lib/keyringer"
-source "$LIB/functions" || exit 1
+LIB="`dirname $0`/../functions"
+source "$LIB" || exit 1
# Command parser
keyringer_get_command "$2"
diff --git a/share/keyringer/preferences b/lib/keyringer/actions/preferences
index 2819b50..e82848d 100755
--- a/share/keyringer/preferences
+++ b/lib/keyringer/actions/preferences
@@ -4,7 +4,7 @@
#
# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
+LIB="`dirname $0`/../functions"
source "$LIB" || exit 1
COMMAND="$2"
diff --git a/share/keyringer/recipients b/lib/keyringer/actions/recipients
index 0460842..7093a6b 100755
--- a/share/keyringer/recipients
+++ b/lib/keyringer/actions/recipients
@@ -4,8 +4,8 @@
#
# Load functions
-LIB="`dirname $0`/../../lib/keyringer"
-source "$LIB/functions" || exit 1
+LIB="`dirname $0`/../functions"
+source "$LIB" || exit 1
# Command parser
keyringer_get_command "$2"
diff --git a/share/keyringer/recrypt b/lib/keyringer/actions/recrypt
index 63f7bc6..014fef7 100755
--- a/share/keyringer/recrypt
+++ b/lib/keyringer/actions/recrypt
@@ -4,7 +4,7 @@
#
# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
+LIB="`dirname $0`/../functions"
source "$LIB" || exit 1
function keyringer_recrypt {
diff --git a/share/keyringer/usage b/lib/keyringer/actions/usage
index a4602ac..f4ac0fa 100755
--- a/share/keyringer/usage
+++ b/lib/keyringer/actions/usage
@@ -4,7 +4,7 @@
#
# Load functions
-LIB="`dirname $0`/../../lib/keyringer/functions"
+LIB="`dirname $0`/../functions"
source "$LIB" || exit 1
keyringer_usage
diff --git a/lib/keyringer/completions/bash/keyringer b/lib/keyringer/completions/bash/keyringer
index 875e6ab..7bfa62f 100644
--- a/lib/keyringer/completions/bash/keyringer
+++ b/lib/keyringer/completions/bash/keyringer
@@ -42,6 +42,15 @@ _keyringer_git_complete() {
fi
}
+# Path completion
+function _keyringer_path_complete() {
+ # Thanks http://unix.stackexchange.com/questions/55520/create-bash-completion-script-to-autocomplete-paths-after-is-equal-sign
+ cur=${1//\\ / }
+ [[ ${cur} == "~/"* ]] && cur=${cur/\~/$HOME}
+
+ echo ${cur}
+}
+
_keyringer() {
# Standard stuff
local cur prev command config path keyrings instances instance opts
@@ -94,10 +103,7 @@ _keyringer() {
opts="$(_keyringer_git_complete ${cur})"
;;
init)
- # Thanks http://unix.stackexchange.com/questions/55520/create-bash-completion-script-to-autocomplete-paths-after-is-equal-sign
- cur=${cur//\\ / }
- [[ ${cur} == "~/"* ]] && cur=${cur/\~/$HOME}
-
+ cur="$(_keyringer_path_complete ${cur})"
opts="$(compgen -o dirnames ${cur})"
;;
*)
@@ -115,6 +121,10 @@ _keyringer() {
# TODO
opts="$(_keyringer_git_complete ${prev} ${cur})"
;;
+ encrypt|encrypt-batch)
+ cur="$(_keyringer_path_complete ${cur})"
+ opts="$(compgen -o dirnames ${cur})"
+ ;;
*)
;;
esac
diff --git a/lib/keyringer/completions/zsh/_keyringer b/lib/keyringer/completions/zsh/_keyringer
index 119d26d..50ff433 100644
--- a/lib/keyringer/completions/zsh/_keyringer
+++ b/lib/keyringer/completions/zsh/_keyringer
@@ -77,6 +77,9 @@ _keyringer() {
git)
compadd "$@" $(_keyringer_git_complete $words[4] $words[5])
;;
+ encrypt|encrypt-batch)
+ _files
+ ;;
*)
;;
esac
diff --git a/lib/keyringer/functions b/lib/keyringer/functions
index 66a23df..7570a94 100755
--- a/lib/keyringer/functions
+++ b/lib/keyringer/functions
@@ -111,20 +111,71 @@ function keyringer_is_git {
fi
}
+# Check the security of a temporary folder
+function keyringer_check_tmp {
+ local path="$1"
+ local minor
+ local mode
+
+ if [ -z "$path" ]; then
+ return
+ fi
+
+ # Mode check
+ if [ "`stat -c "%A" $path`" != "drwxrwxrwt" ]; then
+ return 1
+ fi
+
+ # Ramdisk check
+ if [ -x "/sbin/udevadm" ]; then
+ minor="$(/sbin/udevadm info --device-id-of-file "$path" | cut -d : -f 1)"
+ elif which mountpoint &> /dev/null; then
+ minor="$(mountpoint -d $(df "$path" | sed -n '$p' | awk '{print $NF}') | cut -d : -f 1)"
+ fi
+
+ if [ ! -z "$minor" ]; then
+ return $minor
+ else
+ return 1
+ fi
+}
+
# Setup a temporary file
function keyringer_set_tmpfile {
+ local tmp
+ local candidate
+ local candidates="/tmp /run/shm $TMP"
+
if [ -z "$BASEDIR" ]; then
echo "Please set BASEDIR before creating a tmp file"
exit 1
fi
+ # Ramdisk check
+ for candidate in $candidates; do
+ if keyringer_check_tmp $candidate; then
+ tmp="$candidate/keyringer.`whoami`"
+ break
+ fi
+ done
+
+ # Set base temp folder
+ if [ -z "$tmp" ]; then
+ echo "WARNING: neither one of $candidates is mounted in a tmpfs/ramdisk, using $BASEDIR/tmp as fallback."
+ echo "Make sure that $BASEDIR is atop of an encrypted volume."
+ echo "Press any key to continue, Ctrl-C to abort"
+ read key
+ tmp="$BASEDIR/tmp"
+ fi
+
+ # Determine template
if [ -z "$1" ]; then
- template="$BASEDIR/tmp/keyringer.XXXXXXXXXX"
+ template="$tmp/keyringer.XXXXXXXXXX"
else
- template="$BASEDIR/tmp/$1.XXXXXXXXXX"
+ template="$tmp/XXXXXXXXXX.$1"
fi
- mkdir -p "$BASEDIR/tmp"
+ mkdir -p "$tmp"
keyringer_git_ignore 'tmp/*'
if [ "$2" == "-d" ]; then
@@ -141,13 +192,46 @@ function keyringer_set_tmpfile {
trap "keyringer_unset_tmpfile $TMPWORK; exit" INT TERM EXIT
}
+# Shred files
+function keyringer_shred {
+ local path="$1"
+ local tool
+ local message="Removing"
+
+ if [ -z "$path" ]; then
+ return
+ elif [ ! -e "$path" ]; then
+ return
+ fi
+
+ # Get shred implementation
+ if which wipe &> /dev/null; then
+ tool="wipe"
+ elif which shred &> /dev/null; then
+ tool="shred"
+ else
+ # Worst implementation
+ message="WARNING $message"
+ tool="rm"
+ fi
+
+ echo "$message $path using $tool..."
+
+ if [ -d "$path" ]; then
+ find $path -exec $tool -f {} \;
+ rmdir $path
+ else
+ $tool -f "$path"
+ fi
+}
+
# Remove a temporary file
function keyringer_unset_tmpfile {
if [ -z "$1" ]; then
echo "No tmp file set"
fi
- rm -f "$1"
+ keyringer_shred "$1"
if [ "$?" != "0" ]; then
echo "Warning: could not delete file $1. Please delete it manually as it might have sensitive information."
@@ -342,16 +426,22 @@ function keyringer_get_new_file {
# File must not contain spaces
if [ ! -z "$2" ] ; then
FILE="`echo "$*" | sed -e 's/ /_/g'`"
- echo "File $* has spaces, secret will be named as $FILE..."
else
FILE="$1"
fi
# Sanitize and complete file name
- FILE="`echo $FILE | sed -e s/[^A-Za-z0-9.]/_/g`"
+ FILE="`echo $FILE | sed -e s/[^A-Za-z0-9.\/\-]/_/g`"
+
+ # Warn user about file name change
+ if [ "`basename $*`" != "`basename $FILE`" ]; then
+ echo "Sanitizing destination filename to `basename $FILE`"
+ fi
+
+ # Complete file name
FILE="$(keyringer_filename "$FILE")"
-
- if [ -z "$FILE" ]; then
+
+ if [ -z "$*" ]; then
keyringer_action_usage
exit 1
fi
@@ -361,7 +451,7 @@ function keyringer_get_new_file {
function keyringer_get_command {
# Aditional parameters
COMMAND="$1"
-
+
if [ -z "$COMMAND" ]; then
keyringer_action_usage command
exit 1
@@ -390,9 +480,16 @@ function keyringer_show_actions {
# Usage
function keyringer_usage {
- printf "Usage: %s <keyring> <action> [arguments]\n" "$BASENAME"
- printf "Available commands: \n"
+ local keyrings="$(ls --color=never `dirname $CONFIG` | sed -e 's/config//' | xargs)"
+
+ printf "Usage: %s <keyring> <action> [arguments]\n\n" "$BASENAME"
+ printf "Available commands: \n\n"
keyringer_show_actions | sed -e 's/^/\t/'
+ printf "\tinit <path> [remote]\n\n" $BASENAME
+
+ if [ ! -z "$keyrings" ]; then
+ printf "Available keyrings: %s \n" "$keyrings"
+ fi
}
# Check recipients
@@ -504,7 +601,7 @@ function keyringer_set_new_recipients {
function keyringer_create_new_recipients {
if [ ! -e "$1" ]; then
mkdir -p "`dirname $1`"
- echo "# Use entries in the form of 'john@doe.com XXXXXXXX" > "$1"
+ echo "# Use entries in the form of 'john@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'" > "$1"
echo "" >> "$1"
fi
}
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/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 ""