deprecate sshfpr; add sshfprs-for-userid (closes: MS #1436)

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

diff --git a/man/man1/monkeysphere.1 b/man/man1/monkeysphere.1
index 7cc4fe090085bf8c01f45837c109ac9c46893429..25421cef9fcf7580c1826c1315091e7b1ad9aefa 100644 (file)
--- a/man/man1/monkeysphere.1
+++ b/man/man1/monkeysphere.1
@@ -2,7 +2,7 @@
 
 .SH NAME
 
-monkeysphere \- Monkeysphere client user interface
+monkeysphere - Monkeysphere client user interface
 
 .SH SYNOPSIS
 
@@ -11,9 +11,11 @@ monkeysphere \- Monkeysphere client user interface
 .SH DESCRIPTION
 
 \fBMonkeysphere\fP is a framework to leverage the OpenPGP web of trust
-for OpenSSH authentication.  OpenPGP keys are tracked via GnuPG, and
-added to the authorized_keys and known_hosts files used by OpenSSH for
-connection authentication.
+for OpenSSH and TLS key-based authentication.  OpenPGP keys are
+tracked via GnuPG, and added to the authorized_keys and known_hosts
+files used by OpenSSH for connection authentication.  Monkeysphere can
+also be used by a validation agent to validate TLS connections
+(e.g. https).
 
 \fBmonkeysphere\fP is the Monkeysphere client utility.
 
@@ -42,8 +44,8 @@ were found but none were acceptable.  `k' may be used in place of
 .B update\-authorized_keys
 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
 .BR monkeysphere (7)),
@@ -65,7 +67,7 @@ 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
-.B ssh\-proxycommand
+.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,
@@ -121,7 +123,21 @@ to
 .BR ssh\-add (1).
 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'.
+`\-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 keys\-for\-userid USERID
+Output to stdout all acceptable keys for a given user ID.
+`u' may be used in place of `keys\-for\-userid'.
+.TP
+.B sshfprs\-for\-userid USERID
+Output the ssh fingerprints of acceptable keys for a given user ID.
+.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
@@ -133,29 +149,38 @@ The following environment variables will override those specified in
 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
-GnuPG home directory (~/.gnupg).
+GnuPG home directory. (~/.gnupg)
 .TP
 MONKEYSPHERE_KEYSERVER
-OpenPGP keyserver to use (pool.sks-keyservers.net).
+OpenPGP keyserver to use. (pool.sks-keyservers.net)
 .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
-Path to ssh known_hosts file (~/.ssh/known_hosts).
+Path to ssh known_hosts file. (~/.ssh/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
-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).
+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
 
@@ -167,13 +192,15 @@ User monkeysphere config file.
 System-wide monkeysphere config file.
 .TP
 ~/.monkeysphere/authorized_user_ids
-OpenPGP user IDs associated with keys that will be checked for
-addition to the authorized_keys file.
+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
 
 Written by:
-Jameson Rollins <jrollins@fifthhorseman.net>,
+Jameson Rollins <jrollins@finestructure.net>,
 Daniel Kahn Gillmor <dkg@fifthhorseman.net>
 
 .SH SEE ALSO