From 73ca36760f37dced1d3f7323f26cd926e22e5c9e Mon Sep 17 00:00:00 2001 From: Andrew Cady Date: Wed, 5 Mar 2014 19:23:24 -0500 Subject: first draft man page --- doc/kiki.txt | 459 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 459 insertions(+) create mode 100644 doc/kiki.txt 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 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=] [--set-notation ] [--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] [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] + + 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= + + 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 + + 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] + + 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 + 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. -- cgit v1.2.3