-.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
-\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.
+\fBMonkeysphere\fP is a framework to leverage the OpenPGP web of trust
+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).
.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
-During known_host and authorized_keys updates, the monkeysphere
-commands work from a set of user IDs to determine acceptable keys for
-ssh authentication. OpenPGP keys are considered acceptable if the
-following criteria are met:
+The monkeysphere commands work from a set of user IDs to determine
+acceptable keys for ssh and TLS 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
.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]".
+The OpenPGP keys for hosts have associated `service names` (OpenPGP
+user IDs) that are based on URI specifications for the service. Some
+examples:
+.TP
+.B ssh:
+ssh://host.example.com[:port]
+.TP
+.B https:
+https://host.example.com[:port]
.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),
-.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 ssh (1),
.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/
projects / monkeysphere.git / blobdiff