Merge commit 'dkg/master'

1 files changed, 34 insertions, 8 deletions

diff --git a/man/man7/monkeysphere.7 b/man/man7/monkeysphere.7
index 578d96c..f5a2371 100644
--- a/man/man7/monkeysphere.7
+++ b/man/man7/monkeysphere.7
@@ -1,8 +1,8 @@
-.TH MONKEYSPHERE "7" "June 2008" "monkeysphere" "System Frameworks"
+.TH MONKEYSPHERE "7" "March 2009" "monkeysphere" "System Frameworks"
 
 .SH NAME
 
-monkeysphere \- ssh authentication framework using OpenPGP Web of
+monkeysphere - ssh authentication framework using OpenPGP Web of
 Trust
 
 .SH DESCRIPTION
@@ -14,7 +14,33 @@ 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
 
@@ -24,7 +50,7 @@ ssh authentication.  OpenPGP keys are considered acceptable if the
 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
@@ -36,7 +62,7 @@ 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
-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
 
@@ -47,11 +73,11 @@ Daniel Kahn Gillmor <dkg@fifthhorseman.net>
 .SH SEE ALSO
 
 .BR monkeysphere (1),
-.BR monkeysphere-host (8),
-.BR monkeysphere-authentication (8),
+.BR monkeysphere\-host (8),
+.BR monkeysphere\-authentication (8),
 .BR openpgp2ssh (1),
 .BR pem2openpgp (1),
 .BR gpg (1),
 .BR http://tools.ietf.org/html/rfc4880,
 .BR ssh (1),
-.BR http://tools.ietf.org/wg/secsh/draft-ietf-secsh-scp-sftp-ssh-uri/
+.BR http://tools.ietf.org/wg/secsh/draft\-ietf\-secsh\-scp\-sftp\-ssh\-uri/