Manpage: limitations

1 files changed, 47 insertions, 14 deletions

diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn
index d77fb92..7e79b35 100644
--- a/share/man/keyringer.1.mdwn
+++ b/share/man/keyringer.1.mdwn
@@ -1,6 +1,6 @@
 % KEYRINGER(1) Keyringer User Manual
-% Silvio Rhatto
-% Oct 24, 2013
+% Silvio Rhatto <rhatto@riseup.net>
+% Oct 25, 2013
 
 # NAME
 
@@ -28,9 +28,13 @@ synced with remote branches.
 
 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 handles repository initialization,
+   content tracking and navigation.
+
+2. Secret manipulation actions, which takes care of encrypting, decrypting and other
+   read/write operations on secrets.
+
+3. Configuration actions, handling repository metadata.
 
 # REPOSITORY LOOKUP AND MANIPULATION ACTIONS
 
@@ -164,19 +168,19 @@ recipients <*ls*|*edit*> <*recipient-file*>
 
     All lines starting with the hash (#) character are interpreted as comments.
 
-## OPTIONS
+    Parameters to the *recipients* action are:
 
-ls
-:   List all existing recipient files.
+      *ls*
+      :   List all existing recipient files.
 
-edit
-:   Create or edit a recipient-file.
+      *edit*
+      :   Create or edit a recipient-file.
 
-    Editing happens using the editor specified by the `$EDITOR`
-    environment variable.
+          Editing happens using the editor specified by the `$EDITOR`
+          environment variable.
 
-    The required parameter *recipient-file* is taken relativelly
-    from the `$KEYRING_FOLDER/config/recipients/` folder.
+          The required parameter *recipient-file* is taken relativelly
+          from the `$KEYRING_FOLDER/config/recipients/` folder.
 
 # FILES
 
@@ -192,6 +196,35 @@ $KEYRING_FOLDER/config/options
 
 # LIMITATIONS
 
+Keyringer currently has the following limitations:
+
+* Metadata is not encrypted, meaning that an attacker with access to a keyringer
+  repository knows all public key IDs are 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 *--hidden-recipient* GnuPG
+  option.
+
+* History is not rewritten by default when secrets are removed from a keyringer
+  repository. After a secret is removed with *del* action, it will still be
+  available in the repository history even after a commit. This is by design
+  due to the following reasons:
+
+  1. 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 is someone
+     mistakenly overwrites a secret.
+
+  2. 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 attack 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.