path: root/doc/kiki.txt

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.