Documentation

1 files changed, 47 insertions, 0 deletions

diff --git a/kiki.hs b/kiki.hs
index 2fa061a..610dd5b 100644
--- a/kiki.hs
+++ b/kiki.hs
@@ -458,13 +458,25 @@ kiki_usage = putStr . unlines $
         ,"                current working key (the one shown by --show-wk)."
         ,""
         ,"     --keypairs KEYSPEC KEYSPEC..."
+        ,"                A keypair is a secret key coupled with it's corresponding public"
+        ,"                key, both of which are ordinarily stored in a single file in pem"
+        ,"                format. Users incognisant of the fact that the public key (which"
+        ,"                is also stored separately) is in this file, often think of it as"
+        ,"                their secret key file."
+        ,""              
         ,"                Each KEYSPEC specifies that a key should match the content and"
         ,"                timestamp of an external PKCS #1 private RSA key file."
         ,"                "
         ,"                KEYSPEC ::= SPEC=FILE{CMD} "
         ,""
+        ,"                The form of SPEC is documented below. If there is only one master"
+        ,"                key in your keyring and only one key is used for each purpose, then"                              ,"                it is possible for SPEC in this case to merely be a tag which offers"
+        ,"                information about what this key is used for, for example, any of"
+        ,"                `tor', `ssh-client', `ssh-host', or `strongswan' will do."
+        ,""
         ,"                If neither SPEC or FILE match any keys, then the CMD will be "
         ,"                executed in order to create the FILE."
+
         ,""
         ,"Output:"
         ,"     --show-wk  Show fingerprints for the working key (which will be used to"
@@ -490,6 +502,41 @@ kiki_usage = putStr . unlines $
         ,"                Outputs the secret crypto-coin key in Wallet Input Format."
         ,""
         ,"     --help     Shows this help screen."
+        ,""
+        ,"Specifying keys on the kiki command line:"
+        ,""
+        ,"  SPEC ::= MASTER/SUBKEY"
+        ,""
+        ,"  SPEC indicates a specific key in the keyring, in it's longest incarnation,"
+        ,"  it is of the form MASTER/SUBKEY where MASTER and SUBKEY are documented below."
+        ,"  If kiki can infer the key unambiguously, either via the command in question or"
+        ,"  the contents of the keyring, then it is permissable to ommit either MASTER or"
+        ,"  SUBKEY, in which case the slash may also be ommitted unless it is used via its"
+        ,"  position to indicate whether a SUBKEY or MASTER is intended."
+        ,""
+        ,"  MASTER may be any of"
+        ,"     * The tail end of a fingerprint prefixed by 'fp:'"
+        ,"     * A sub-string of a user id (without slashes) prefixed by 'u:'" 
+        ,"     * 40 characters of hexidecimal (kiki will assume this to be a fingerprint)"
+        ,"     * A sub-string of a user id (without slashes, the prefix 'u:' is optional)"
+        ,""
+        ,"  SUBKEY may be any of"
+        ,"     * The tail end of a fingerprint prefixed by 'fp:'"
+        ,"     * An exact match of a usage tag prefixed by 't:'"
+        ,"     * 40 characters of hexidecimal (kiki will assume this to be a fingerprint)"
+        ,"     * An exact match of a usage tag (The prefix 't:' is optional)"
+        ,""
+        ,"     In parsing the spec, kiki will attempt to match the string to one of the"
+        ,"     above formats, in the order presented."
+        ,""
+        ,"  Examples of valid SPEC strings:"
+        ,""
+        ,"      fp:4A39F/tor"
+        ,"      u:joe/tor"
+        ,"      u:joe/t:tor"
+        ,"      u:joe/fp:4abf30"
+        ,"      joe/tor"
+        ,"      5E24CD442AA6965D2012E62A905C24185D5379C2"
         ]
 
 doAutosign rt kd@(KeyData k ksigs umap submap) = ops