Add new keys-from-userid subcommand to monkeysphere UI.

[monkeysphere.git] / man / man1 / monkeysphere.1

diff --git a/man/man1/monkeysphere.1 b/man/man1/monkeysphere.1
index b0c896f0ee54c99e5934758cfa3442761c2b8a5d..459bfcb83da681783d7932b884dd71c026d1576e 100644 (file)
--- a/man/man1/monkeysphere.1
+++ b/man/man1/monkeysphere.1
@@ -2,7 +2,7 @@
 
 .SH NAME
 
 
 .SH NAME
 

-monkeysphere \- Monkeysphere client user interface
+monkeysphere - Monkeysphere client user interface

 
 .SH SYNOPSIS
 
 
 .SH SYNOPSIS
 


@@ -21,14 +21,14 @@ connection authentication.
 
 \fBmonkeysphere\fP takes various subcommands:
 .TP
 
 \fBmonkeysphere\fP takes various subcommands:
 .TP

-.B update-known_hosts [HOST]...
+.B update\-known_hosts [HOST]...

 Update the known_hosts file.  For each specified host, gpg will be
 queried for a key associated with the host URI (see HOST
 IDENTIFICATION in
 Update the known_hosts file.  For each specified host, gpg will be
 queried for a key associated with the host URI (see HOST
 IDENTIFICATION in

-.BR monkeysphere(5)),
+.BR monkeysphere(7)),

 optionally querying a keyserver.
 If an acceptable key is found for the host (see KEY ACCEPTABILITY in
 optionally querying a keyserver.
 If an acceptable key is found for the host (see KEY ACCEPTABILITY in

-.BR monkeysphere(5)),
+.BR monkeysphere(7)),

 the key is added to the user's known_hosts file.  If a key is found
 but is unacceptable for the host, any matching keys are removed from
 the user's known_hosts file.  If no gpg key is found for the host,
 the key is added to the user's known_hosts file.  If a key is found
 but is unacceptable for the host, any matching keys are removed from
 the user's known_hosts file.  If no gpg key is found for the host,


@@ -37,16 +37,16 @@ known_hosts file will be processed.  This subcommand will exit with a
 status of 0 if at least one acceptable key was found for a specified
 host, 1 if no matching keys were found at all, and 2 if matching keys
 were found but none were acceptable.  `k' may be used in place of
 status of 0 if at least one acceptable key was found for a specified
 host, 1 if no matching keys were found at all, and 2 if matching keys
 were found but none were acceptable.  `k' may be used in place of

-`update-known_hosts'.
+`update\-known_hosts'.

 .TP
 .TP

-.B update-authorized_keys
+.B update\-authorized_keys

 Update the authorized_keys file for the user executing the command
 (see MONKEYSPHERE_AUTHORIZED_KEYS in ENVIRONMENT, below).  First all
 Update the authorized_keys file for the user executing the command
 (see MONKEYSPHERE_AUTHORIZED_KEYS in ENVIRONMENT, below).  First all

-monkeysphere keys are cleared from the authorized_keys file.  Then, or
-each user ID in the user's authorized_user_ids file, gpg will be
+monkeysphere keys are cleared from the authorized_keys file.  Then,
+for each user ID in the user's authorized_user_ids file, gpg will be

 queried for keys associated with that user ID, optionally querying a
 keyserver.  If an acceptable key is found (see KEY ACCEPTABILITY in
 queried for keys associated with that user ID, optionally querying a
 keyserver.  If an acceptable key is found (see KEY ACCEPTABILITY in

-.BR monkeysphere (5)),
+.BR monkeysphere (7)),

 the key is added to the user's authorized_keys file.
 If a key is found but is unacceptable for the user ID, any matching
 keys are removed from the user's authorized_keys file.  If no gpg key
 the key is added to the user's authorized_keys file.
 If a key is found but is unacceptable for the user ID, any matching
 keys are removed from the user's authorized_keys file.  If no gpg key


@@ -54,25 +54,89 @@ is found for the user ID, nothing is done.  This subcommand will exit
 with a status of 0 if at least one acceptable key was found for a user
 ID, 1 if no matching keys were found at all, and 2 if matching keys
 were found but none were acceptable.  `a' may be used in place of
 with a status of 0 if at least one acceptable key was found for a user
 ID, 1 if no matching keys were found at all, and 2 if matching keys
 were found but none were acceptable.  `a' may be used in place of

-`update-authorized_keys'.
+`update\-authorized_keys'.

 .TP
 .TP

-.B gen-subkey [KEYID]
+.B gen\-subkey [KEYID]

 Generate an authentication subkey for a private key in your GnuPG
 Generate an authentication subkey for a private key in your GnuPG

-keyring.  For the primary key with the specified key ID, generate a
-subkey with "authentication" capability that can be used for
-monkeysphere transactions.  An expiration length can be specified with
-the `-e' or `--expire' option (prompt otherwise).  If no key ID is
+keyring.  KEYID is the key ID for the primary key for which the subkey
+with "authentication" capability will be generated.  If no key ID is

 specified, but only one key exists in the secret keyring, that key
 specified, but only one key exists in the secret keyring, that key

-will be used.  `g' may be used in place of `gen-subkey'.
+will be used.  The length of the generated key can be specified with
+the `\-\-length' or `\-l' option.  `g' may be used in place of
+`gen\-subkey'.

 .TP
 .TP

-.B subkey-to-ssh-agent [ssh-add arguments]
+.B ssh\-proxycommand [--no-connect] HOST [PORT]
+An ssh ProxyCommand that can be used to trigger a monkeysphere update
+of the ssh known_hosts file for a host that is being connected to with
+ssh.  This works by updating the known_hosts file for the host first,
+before an attempted connection to the host is made.  Once the
+known_hosts file has been updated, a TCP connection to the host is
+made by exec'ing netcat(1).  Regular ssh communication is then done
+over this netcat TCP connection (see ProxyCommand in ssh_config(5) for
+more info).
+
+This command is meant to be run as the ssh "ProxyCommand".  This can
+either be done by specifying the proxy command on the command line:
+
+.B ssh \-o ProxyCommand="monkeysphere ssh\-proxycommand %h %p" ...
+
+or by adding the following line to your ~/.ssh/config script:
+
+.B ProxyCommand monkeysphere ssh\-proxycommand %h %p
+
+The script can easily be incorporated into other ProxyCommand scripts
+by calling it with the "\-\-no\-connect" option, i.e.:
+
+.B monkeysphere ssh\-proxycommand \-\-no\-connect "$HOST" "$PORT"
+
+This will run everything except the final exec of netcat to make the
+TCP connection to the host.  In this way this command can be added to
+another proxy command that does other stuff, and then makes the
+connection to the host itself.
+
+KEYSERVER CHECKING:
+The proxy command has a fairly nuanced policy for when keyservers are
+queried when processing a host.  If the host userID is not found in
+either the user's keyring or in the known_hosts file, then the
+keyserver is queried for the host userID.  If the host userID is found
+in the user's keyring, then the keyserver is not checked.  This
+assumes that the keyring is kept up-to-date, in a cronjob or the like,
+so that revocations are properly handled.  If the host userID is not
+found in the user's keyring, but the host is listed in the known_hosts
+file, then the keyserver is not checked.  This last policy might
+change in the future, possibly by adding a deferred check, so that
+hosts that go from non-monkeysphere-enabled to monkeysphere-enabled
+will be properly checked.
+
+Setting the CHECK_KEYSERVER variable in the config file or the
+MONKEYSPHERE_CHECK_KEYSERVER environment variable to either `true' or
+`false' will override the keyserver-checking policy defined above and
+either always or never check the keyserver for host key updates.
+
+.TP
+.B subkey\-to\-ssh\-agent [ssh\-add arguments]

 Push all authentication-capable subkeys in your GnuPG secret keyring
 into your running ssh-agent.  Additional arguments are passed through
 to
 Push all authentication-capable subkeys in your GnuPG secret keyring
 into your running ssh-agent.  Additional arguments are passed through
 to

-.BR ssh-add (1).
+.BR ssh\-add (1).

 For example, to remove the authentication subkeys, pass an additional
 For example, to remove the authentication subkeys, pass an additional

-`-d' argument.  To require confirmation on each use of the key, pass
-`-c'.  `s' may be used in place of `subkey-to-ssh-agent'.
+`\-d' argument.  To require confirmation on each use of the key, pass
+`\-c'.  The MONKEYSPHERE_SUBKEYS_FOR_AGENT environment can be used to
+specify the full fingerprints of specific keys to add to the agent
+(space separated), instead of adding them all.  `s' may be used in
+place of `subkey\-to\-ssh\-agent'.
+.TP
+.B sshfpr KEYID
+Output the ssh fingerprint of a key in your gpg keyring. `f' may be
+used in place of `fingerprint'.
+.TP
+.B keys\-from\-userid USERID
+Output to stdout all acceptable keys for a given user ID literal.
+`u' may be used in place of `keys\-from\-userid'.
+.TP
+.B version
+Show the monkeysphere version number.  `v' may be used in place of
+`version'.

 .TP
 .B help
 Output a brief usage summary.  `h' or `?' may be used in place of
 .TP
 .B help
 Output a brief usage summary.  `h' or `?' may be used in place of


@@ -84,50 +148,65 @@ The following environment variables will override those specified in
 the monkeysphere.conf configuration file (defaults in parentheses):
 .TP
 MONKEYSPHERE_LOG_LEVEL
 the monkeysphere.conf configuration file (defaults in parentheses):
 .TP
 MONKEYSPHERE_LOG_LEVEL

-Set the log level (INFO).  Can be SILENT, ERROR, INFO, VERBOSE, DEBUG,
-in increasing order of verbosity.
+Set the log level.  Can be SILENT, ERROR, INFO, VERBOSE, DEBUG,
+in increasing order of verbosity. (INFO)

 .TP
 MONKEYSPHERE_GNUPGHOME, GNUPGHOME
 .TP
 MONKEYSPHERE_GNUPGHOME, GNUPGHOME

-GnuPG home directory (~/.gnupg).
+GnuPG home directory. (~/.gnupg)

 .TP
 MONKEYSPHERE_KEYSERVER
 .TP
 MONKEYSPHERE_KEYSERVER

-OpenPGP keyserver to use (subkeys.pgp.net).
+OpenPGP keyserver to use. (pool.sks-keyservers.net)

 .TP
 MONKEYSPHERE_CHECK_KEYSERVER
 .TP
 MONKEYSPHERE_CHECK_KEYSERVER

-Whether or not to check keyserver when making gpg queries (`true').
+Whether or not to check keyserver when making gpg queries. (true)

 .TP
 MONKEYSPHERE_KNOWN_HOSTS
 .TP
 MONKEYSPHERE_KNOWN_HOSTS

-Path to ssh known_hosts file (~/.ssh/known_hosts).
+Path to ssh known_hosts file. (~/.ssh/known_hosts)

 .TP
 MONKEYSPHERE_HASH_KNOWN_HOSTS
 .TP
 MONKEYSPHERE_HASH_KNOWN_HOSTS

-Whether or not to hash to the known_hosts file entries (`true').
+Whether or not to hash to the known_hosts file entries. (true)

 .TP
 MONKEYSPHERE_AUTHORIZED_KEYS
 .TP
 MONKEYSPHERE_AUTHORIZED_KEYS

-Path to ssh authorized_keys file (~/.ssh/authorized_keys).
+Path to ssh authorized_keys file. (~/.ssh/authorized_keys)
+.TP
+MONKEYSPHERE_PROMPT
+If set to `false', never prompt the user for confirmation. (true)
+.TP
+MONKEYSPHERE_STRICT_MODES
+If set to `false', ignore too-loose permissions on known_hosts,
+authorized_keys, and authorized_user_ids files.  NOTE: setting this to
+false may expose you to abuse by other users on the system. (true)
+.TP
+MONKEYSPHERE_SUBKEYS_FOR_AGENT
+A space-separated list of authentication-capable subkeys to add to the
+ssh agent with subkey-to-ssh-agent.

 
 .SH FILES
 
 .TP
 
 .SH FILES
 
 .TP

-~/.config/monkeysphere/monkeysphere.conf
+~/.monkeysphere/monkeysphere.conf

 User monkeysphere config file.
 .TP
 /etc/monkeysphere/monkeysphere.conf
 System-wide monkeysphere config file.
 .TP
 User monkeysphere config file.
 .TP
 /etc/monkeysphere/monkeysphere.conf
 System-wide monkeysphere config file.
 .TP

-~/.config/monkeysphere/authorized_user_ids
-OpenPGP user IDs associated with keys that will be checked for
-addition to the authorized_keys file.
+~/.monkeysphere/authorized_user_ids
+A list of OpenPGP user IDs, one per line.  OpenPGP keys with an
+exactly-matching User ID (calculated valid by the designated identity
+certifiers), will have any valid authorization-capable keys or subkeys
+added to the given user's authorized_keys file.

 
 .SH AUTHOR
 
 
 .SH AUTHOR
 

-Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel
-Kahn Gillmor <dkg@fifthhorseman.net>
+Written by:
+Jameson Rollins <jrollins@fifthhorseman.net>,
+Daniel Kahn Gillmor <dkg@fifthhorseman.net>

 
 .SH SEE ALSO
 
 
 .SH SEE ALSO
 

-.BR monkeysphere-ssh-proxycommand (1),
-.BR monkeysphere-server (8),
-.BR monkeysphere (5),
+.BR monkeysphere\-host (8),
+.BR monkeysphere\-authentication (8),
+.BR monkeysphere (7),

 .BR ssh (1),
 .BR ssh (1),

-.BR ssh-add (1),
+.BR ssh\-add (1),

 .BR gpg (1)
 .BR gpg (1)