Manpage: limitations (2)

1 files changed, 39 insertions, 5 deletions

diff --git a/share/man/keyringer.1 b/share/man/keyringer.1
index 9f9f835..822c54e 100644
--- a/share/man/keyringer.1
+++ b/share/man/keyringer.1
@@ -1,4 +1,4 @@
-.TH KEYRINGER 1 "Oct 24, 2013" "Keyringer User Manual"
+.TH KEYRINGER 1 "Oct 25, 2013" "Keyringer User Manual"
 .SH NAME
 .PP
 keyringer - encrypted and distributed secret sharing software
@@ -22,11 +22,13 @@ can be synced with remote branches.
 .PP
 Keyringer has three types of actions:
 .IP "1." 3
-Repository lookup and manipulation actions.
+Repository lookup and manipulation actions, which handles repository
+initialization, content tracking and navigation.
 .IP "2." 3
-Secret manipulation actions.
+Secret manipulation actions, which takes care of encrypting, decrypting
+and other read/write operations on secrets.
 .IP "3." 3
-Configuration actions.
+Configuration actions, handling repository metadata.
 .SH REPOSITORY LOOKUP AND MANIPULATION ACTIONS
 .TP
 .B init <\f[I]path\f[]> [\f[I]remote\f[]]
@@ -211,7 +213,7 @@ fingerprint is \f[I]XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.\f[]
 All lines starting with the hash (#) character are interpreted as
 comments.
 .PP
-Parameters to the \f[I]recipients\f[] subcommand are:
+Parameters to the \f[I]recipients\f[] action are:
 .TP
 .B \f[I]ls\f[]
 List all existing recipient files.
@@ -240,6 +242,38 @@ 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 \[bu] 2
+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 \f[I]--hidden-recipient\f[] GnuPG option.
+.IP \[bu] 2
+History is not rewritten by default when secrets are removed from a
+keyringer repository.
+After a secret is removed with \f[I]del\f[] action, it will still be
+available in the repository history even after a commit.
+This is by design due to the following reasons:
+.IP "1." 3
+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
+is someone mistakenly overwrites a secret.
+.IP "2." 3
+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 4
+.PP
+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.
+.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