first draft man page

1 files changed, 459 insertions, 0 deletions

diff --git a/doc/kiki.txt b/doc/kiki.txt
new file mode 100644
index 0000000..15ae53b
--- /dev/null
+++ b/doc/kiki.txt
@@ -0,0 +1,459 @@
+kiki - a bridge between keys
+
+  Kiki turns your OpenGPG key into a single sign-on (SSO) identity
+  for all cryptographically-authenticated services.
+
+  It also enables you to accept such identities for your own services.
+
+  Fuck Google, fuck Facebook, and fuck Verisign.  [TODO: enlarge list]
+
+Synopsis:
+
+  kiki [command] [options] [[command] [options]]...
+
+  [TODO: show the most useful commands as examples.]
+
+Description:
+
+  Kiki creates a cryptographic chain of trust, _from_ a foundation of
+  the OpenPGP web of trust, _to_ all other key types.
+
+  The following key types are currently supported:
+
+    * ssh (host and client)
+    * ipsec
+    * DNSKEY (DNSSEC)
+    * x509 (TLS/SSL, client and server authentication; HTTP/SMTP)
+    * Tor hidden service (.onion)
+    * I2P hidden service (.b32.i2p)
+    * GNUNet hidden service (.gnu, .zkey)
+    * Bitcoin address (and other cryptocoins)
+    * OpenPGP subkeys (merge subkeys from multiple keyrings into one)
+
+  Kiki allows such keys to be taken from an existing system and imported
+  into an OpenPGP key so that they can be shared easily.
+
+  In the other direction, Kiki will determine the OpenPGP UID(s)
+  cryptographically chained to any public key in any format, so that
+  services with cryptographic authentication can be easily modified
+  to accept OpenPGP identities by calling Kiki.  Kiki can also export
+  public keys into convenient formats, ready for use by services that do
+  not call Kiki.
+
+  In addition to supporting the traditional OpenPGP web of trust,
+  Kiki recognizes the possibility of _self-authenticating_ OpenPGP
+  signatures.  These are signatures which assert ownership of UIDs which
+  are provably owned by the signer.  For example, an OpenPGP key which
+  claims the UID <root@hiotuxliwisbp6mi.onion> is self-authenticating
+  if the private key corresponding to 'hiotuxliwisbp6mi' has signed the
+  UID.  Such OpenPGP keys do not need to be validated by an external
+  signature.  They can be validated using their own internal data, and
+  trusted immediately.
+
+Tutorial:
+
+  To get started with Kiki, yada yada, [TODO]
+
+Commands:
+
+  If no command is given, the default command is 'show-working-key'.
+
+  For options common to multiple commands, see _Options_.
+
+  import-key [options] [file]
+
+    options: --autosign --sign-key --authentic-only
+
+    Import an OpenPGP key into the default keyring, optionally signing
+    it with the default key.  If no file is specified, the key is read
+    from stdin.
+
+    With --authentic-only, import the key only if it is
+    self-authenticating or can be authenticated by already-trusted keys.
+    With --autosign, import the key either way, but only sign it if it
+    is self-authenticating (as if 'autosign' were run).
+
+    For a detailed description of the requirements for
+    self-authenticated keys, see section _Self-authentication_.
+
+  import-subkey [options] [public key filename | private key filename] [...]
+
+    options: [--usage=<type>] [--set-notation <name=value>] [--no-usage] [key format]
+
+    Import keys from an external file, or from stdin, into the keyring,
+    as subkeys of the working key.  The keys will be signed by the
+    master key, and cross-certification will be performed (i.e., the
+    keys will be used to sign the master key).
+
+    Without a private key, cross-certification is impossible, and a
+    confirmation will be required, which can be overridden with --yes.
+
+    The --usage option can be used to specify the 'usage@' notation,
+    which is used by Kiki and Samizdat to determine what functions the
+    key should have outside of PGP.  If neither --usage nor --no-usage
+    is specified, the usage will be inferred from the filename and/or
+    key format.
+
+    When the input is a file, the internal timestamp of the subkey will
+    be set to match its mtime.  The subkey timestamp is not altered if
+    the subkey already exists.
+
+  export-subkey [options] <uid | master keyprint | subkey keyprint> [output path]
+
+    options: [--public[=file]] [--private[=file]] [--usage=string] [key format]
+
+    Export the explicitly specified subkey, or the newest subkey
+    indicated by the usage option, in the explicitly specified format,
+    or the format indicated by the usage option.  If no output file
+    specification is supplied, stdout is used, but this may require
+    --public or --private, depending on the key format.  (Not all key
+    formats allow public and private keys to be appended in a single
+    file in a reasonable way.)
+
+    If a uid or master key is specified, then the usage option is
+    mandatory; it is required to select which subkey to export.  Only
+    one of --public or --private can be specified unless both have
+    arguments.
+
+    If --public or --private is specified without arguments, then the
+    public or private key is written to the specified output path.  If
+    neither is specified, then the output path is where the private key
+    will be written.  In that case, the public key will be also written,
+    to a path determined by that of the private key, by a mechanism
+    specified by the key format.
+
+    When --public or --private have arguments, these are the locations
+    where the public and private keys are written.  A path of '-' can be
+    specified for output to stdout.
+
+    When the output is a file, the mtime on the file will be set to
+    match OpenPGP's internal subkey timestamp.
+
+    For more information about key formats, see _Key formats_.
+
+  [TODO: generic 'authorize' command?]
+
+  ssh-authorize [options] <uid | master keyprint | subkey keyprint>
+
+    options: --user=user
+
+    Authorize ssh access for the specified user by appending the
+    appropriate key to $HOME/.ssh/authorized_keys unless it already
+    exists there.
+
+    Without --user, access to the current user account is granted.
+    Otherwise, root is required, and access to the specified user
+    account is granted.
+
+    A comment will be written indicating the UID prepended with
+    '[samizdat]'.
+
+  ssh-unauthorize [uid]
+
+    options: --user=user --authorized_keys=<file>
+
+    Without a uid argument, revoked keys, expired keys, and expired
+    subkeys, will have their corresponding ssh keys removed from
+    $HOME/.ssh/authorized_keys, or the specified file.  Additionally,
+    auth lines tagged [samizdat] for keys that are missing from the
+    keyring will be removed.
+
+    With a uid argument, all subkeys of the specified UID will be
+    removed.
+
+    Without --user, access to the current user account is removed.
+    Otherwise, root is required, and access to the specified user
+    account is removed.
+
+  autosign [key] [...]
+
+    This command will operate on all keys if none are specified.
+
+    The working key is used to sign the specified keys if they can be
+    self-authenticated.  This tells GnuPG to trust such keys, which it
+    would not otherwise do.
+
+    For a detailed description of the requirements for
+    self-authenticated keys, see section _Self-authentication_.
+
+  show-working-key
+
+    Show all available information about the default working key.
+
+    Equivalent to 'show --all' with no uid argument.
+
+  show [options] [uid or keyprint]
+
+    options: [--all | key format]
+
+    With '--all' or without a key format option, display a listing
+    showing all keys and UIDs associated with a given UID, indicating
+    trust-chain relationships between them.
+
+    With a key format option, output a machine-useable version of the
+    key type specified.  If a UID or master keyprint is specified, then
+    the 'usage@' annotation will be used to decide which subkey to
+    display.  If a subkey fingerprint is specified, then that key will
+    be output in the specified format.  If multiple keys are available
+    with a matching 'usage@' annotation, the most recent key is chosen.
+
+    Untrusted or unrequested data may be output via stderr.  Only
+    trusted and requested data is output via stdout.
+
+    For more information about key formats, see _Key formats_.
+
+  list <uid | master keyprint | subkey keyprint> <key format>
+
+    List all subkeys of the specified master key, or of the master key
+    of the specified subkey, tagged with the usage specified by the key
+    format.
+
+    For more information about key formats, see _Key formats_.
+
+  verify [options] [file or network resource]
+
+    options: [key format | --challenge] --uid --short-uid --keyprint --datetime
+
+    Output the verified identity of the signer of the data.  If no file
+    is specified, then the data is read from stdin.
+
+    A key format can be specified to indicate the format of the data.
+    Otherwise, an attempt is made to infer the key format from the data
+    itself, in which case it must not contain extraneous information.
+    For network resources, it can always be inferred.
+
+    Supported network resources are:
+
+      ssh://server[:port]
+      https://[SNI domain@]server[:port]
+      tls://[SNI domain@]server[:port]
+      dnskey://[domain][@dns server:port]
+
+    For DNSKEY network resources, all DNSKEY responses must validate;
+    but ZSK's might be validated indirectly, through RRSIG records made
+    with validated ZSK's.
+
+    Identities are output on stdout, with one identity per line.  Stderr
+    may contain additional information.  Special characters in UIDs
+    (such as newline) are escaped.
+
+    By default, or with --uid, show the full UID.  With --short-uid,
+    show only the email part of the UID, without brackets.  With
+    --keyprint, show the keyprint of the master key.
+
+    With both --keyprint and one of --uid or --short-uid, show the
+    keyprint, followed by a space, followed by the UID in the specified
+    form.
+
+    With '--challenge', a cryptographic challenge response is verified.
+    In this case, the stdout output is not necessarily an OpenPGP UID or
+    keyprint, but is specific to the challenge type.
+
+    Kiki will exit with failure if verification fails.
+
+    For more information about key formats, see _Key formats_.
+
+  challenge [options] <challenge type> <uid>
+
+    options: --language=[lang] --short --no-instructions --shell --validity-period=[interval]
+    challenge types: --bitcoin --tor --i2p --pgp
+
+    Output to stdout a human-readable challenge which can be completed
+    only with the appropriate private key.  Creating the challenge may
+    require generating a PGP signature, in which case the working key
+    will be used.  The response to the challenge can be verified with
+    the 'verify --challenge' command.
+
+    With --validity-period, the challenge will expire after the
+    specified interval.  The interval is specified in DNS zone file
+    format.  The current system time is used to calculate an absolute
+    expiration time in the future.
+
+    Unless --no-instructions is specified, the challenge will contain
+    detailed instructions intended for unsophisticated recipients.  If
+    --short is specified, the instructions will be less detailed.  If
+    --shell is specified, the "instructions" take the form of a Bourne
+    shell script.
+
+  response [file]
+
+    A challenge generated from 'challenge' is read from the specified
+    file, or via stdin, and an identity-proving response is generated
+    automatically and output to stdout.
+
+  help
+
+Key formats:
+
+  [TODO: determine, and document, the precise relationship between key
+  formats and usage notations.]
+
+  --pem --ssh --wallet --dnskey --ipsec --pgp
+
+  --wallet
+
+    Bitcoin wallet input format.  These cryptocoins are also supported:
+
+    [...]
+
+  --ssh
+
+    OpenSSH key format.  For public keys, this is the format used in
+    authorized_keys.  The "comment" section, which is output via stderr,
+    contains a UID with special characters (such as newline) escaped.
+
+Options:
+
+  These options are common to multiple commands.  Options specific to
+  commands are documented with the commands.
+
+  --homedir
+  --passphrase-fd
+  --keyring
+  --no-default-keyring
+  --primary-keyring
+  --default-key
+  --trustdb-name
+  --verbose
+  --quiet
+  --no-tty
+  --yes
+  --no
+
+Environment:
+
+  HOME
+  GNUPGHOME
+  GPG_AGENT_INFO
+  PINENTRY_USER_DATA
+
+Files:
+
+  $HOME/.gnupg
+
+  $GNUPGHOME/{pub,sec}ring.gpg
+
+  /etc/ssh/ssh_host*_key
+
+  /etc/ipsec.d/private/*.pem
+
+  etc.
+
+Self-authentication:
+
+  [Explain the criteria of self-authentication in precise terms.]
+
+Author:
+
+  Kiki by Joe Crayne.  This manual by Andrew Cady.
+
+Copyright:
+
+  (C) 2014 Joe Crayne.  All Rights Reserved.
+
+  When released, Kiki will be released under a free software license.
+  This version is a pre-release.
+
+Reporting Bugs:
+
+  Bugs?  Impossible.
+
+                          "From key to shining key..."
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+kiki [OPTIONS]
+
+     kiki merges a set of keyring files into a combined database and then
+     uses the database to update the files so that they have the most complete
+     information.
+
+     The files pubring.gpg and subring.gpg in the directory specified by the 
+     --homedir option are implicitly included in the keyring set.
+
+     kiki can also import or export secret subkeys by using the --keypairs option.
+
+     Subkeys that are imported with kiki are given an annotation "usage@" which
+     indicates what the key is for.  This tag can be used as a SPEC to select a
+     particular key.  Master keys may be specified by using fingerprints or by
+     specifying a substring of an associated UID.
+
+Flags:
+     --homedir DIR
+                Where to find the the files secring.gpg and pubring.gpg. The 
+                default location is taken from the environment variable 
+                GNUPGHOME.
+
+     --passphrase-fd N
+                Read passphrase from the given file descriptor.
+
+     --import   Add master keys to pubring.gpg.  Without this option, only UID
+                and subkey data is updated. 
+
+     --import-if-authentic
+                Add signed master keys to pubring.gpg.  Like --import except that
+                only keys with signatures from the working key (--show-wk) are
+                imported.
+
+     --autosign Sign all cross-certified tor-style UIDs.
+                A tor-style UID is of the form:
+                        Anonymous <root@HOSTNAME.onion>
+                It is considered cross certified if there exists a cross-certified
+                'tor' subkey corresponding to the address HOSTNAME.onion.
+
+Merging:
+     --keyrings FILE FILE...
+                Provide keyring files other than the implicit secring.gpg and
+                pubring.gpg in the --homedir.  This option is implicit unless
+                --keypairs or --wallets is used.
+
+     --wallets  FILE FILE...
+                Provide wallet files with secret crypto-coin keys in Wallet
+                Import Format.  The keys will be treated as subkeys of your
+                current working key (the one shown by --show-wk).
+
+     --keypairs KEYSPEC KEYSPEC...
+                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} 
+
+                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
+                make signatures) and all its subkeys and UID.
+
+     --show-key SPEC
+                Show fingerprints for the specified key and all its subkeys
+                and UID.
+
+     --show-all Show fingerprints and UIDs and usage tags for all known keys.
+
+     --show-whose-key
+                Shows the fingerprint and UIDs of the key that owns the one that
+                is input on stdin in ssh-rsa format.
+
+     --show-pem SPEC
+                Outputs the PKCS #8 public key corresponding to SPEC.
+
+     --show-ssh SPEC
+                Outputs the ssh-rsa blob for the specified public key.
+
+     --show-wip SPEC
+                Outputs the secret crypto-coin key in Wallet Input Format.
+
+     --help     Shows this help screen.