don't use read -p; it is sucky (closes: #446)
[monkeysphere.git] / man / man7 / monkeysphere.7
index 8d7c43a4514d50defdc1942346ac8ec12df32bbc..f5a23718c933d0138923eb32c785f7e7feb34282 100644 (file)
@@ -1,20 +1,46 @@
-.TH MONKEYSPHERE "7" "June 2008" "monkeysphere" "System Frameworks"
+.TH MONKEYSPHERE "7" "March 2009" "monkeysphere" "System Frameworks"
 
 .SH NAME
 
 
 .SH NAME
 
-monkeysphere \- ssh authentication framework using OpenPGP Web of
+monkeysphere - ssh authentication framework using OpenPGP Web of
 Trust
 
 .SH DESCRIPTION
 
 Trust
 
 .SH DESCRIPTION
 
-\fBMonkeySphere\fP is a framework to leverage the OpenPGP Web of Trust
+\fBMonkeysphere\fP is a framework to leverage the OpenPGP Web of Trust
 for ssh authentication.  OpenPGP keys are tracked via GnuPG, and added
 to the authorized_keys and known_hosts files used by ssh for
 connection authentication.
 
 .SH IDENTITY CERTIFIERS
 
 for ssh authentication.  OpenPGP keys are tracked via GnuPG, and added
 to the authorized_keys and known_hosts files used by ssh for
 connection authentication.
 
 .SH IDENTITY CERTIFIERS
 
-FIXME: describe identity certifier concept
+Each host that uses the \fBMonkeysphere\fP to authenticate its remote
+users needs some way to determine that those users are who they claim
+to be.  SSH permits key-based authentication, but we want instead to
+bind authenticators to human-comprehensible user identities.  This
+switch from raw keys to User IDs makes it possible for administrators
+to see intuitively who has access to an account, and it also enables
+end users to transition keys (and revoke compromised ones)
+automatically across all \fBMonkeysphere\fP-enabled hosts.  The User
+IDs and certifications that the \fBMonkeysphere\fP relies on are found
+in the OpenPGP Web of Trust.
+
+However, in order to establish this binding, each host must know whose
+cerifications to trust.  Someone who a host trusts to certify User
+Identities is called an Identity Certifier.  A host must have at least
+one Identity Certifier in order to bind User IDs to keys.  Commonly,
+every ID Certifier would be trusted by the host to fully identify any
+User ID, but more nuanced approaches are possible as well.  For
+example, a given host could specify a dozen ID certifiers, but assign
+them all "marginal" trust.  Then any given User ID would need to be
+certified in the OpenPGP Web of Trust by at least three of those
+certifiers. 
+
+It is also possible to limit the scope of trust for a given ID
+Certifier to a particular domain.  That is, a host can be configured
+to fully (or marginally) trust a particular ID Certifier only when
+they certify identities within, say, example.org (based on the e-mail
+address in the User ID).
 
 .SH KEY ACCEPTABILITY
 
 
 .SH KEY ACCEPTABILITY
 
@@ -24,7 +50,7 @@ ssh authentication.  OpenPGP keys are considered acceptable if the
 following criteria are met:
 .TP
 .B capability
 following criteria are met:
 .TP
 .B capability
-The key must have the "authentication" ("a") usage flag set.
+The key must have the `authentication' (`a') usage flag set.
 .TP
 .B validity
 The key itself must be valid, i.e. it must be well-formed, not
 .TP
 .B validity
 The key itself must be valid, i.e. it must be well-formed, not
@@ -36,19 +62,22 @@ The relevant user ID must be signed by a trusted identity certifier.
 .SH HOST IDENTIFICATION
 
 The OpenPGP keys for hosts have associated user IDs that use the ssh
 .SH HOST IDENTIFICATION
 
 The OpenPGP keys for hosts have associated user IDs that use the ssh
-URI specification for the host, i.e. "ssh://host.full.domain[:port]".
+URI specification for the host, i.e. `ssh://host.full.domain[:port]'.
 
 .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
 
 .BR monkeysphere (1),
 
 .SH SEE ALSO
 
 .BR monkeysphere (1),
-.BR monkeysphere-server (8),
-.BR monkeysphere-ssh-proxycommand (1),
+.BR monkeysphere\-host (8),
+.BR monkeysphere\-authentication (8),
+.BR openpgp2ssh (1),
+.BR pem2openpgp (1),
 .BR gpg (1),
 .BR gpg (1),
-.BR ssh (1),
 .BR http://tools.ietf.org/html/rfc4880,
 .BR http://tools.ietf.org/html/rfc4880,
-.BR http://tools.ietf.org/wg/secsh/draft-ietf-secsh-scp-sftp-ssh-uri/
+.BR ssh (1),
+.BR http://tools.ietf.org/wg/secsh/draft\-ietf\-secsh\-scp\-sftp\-ssh\-uri/