path: root/man/man7/monkeysphere.7

.TH MONKEYSPHERE "7" "June 2008" "monkeysphere" "System Frameworks"

.SH NAME

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.

.SH IDENTITY CERTIFIERS

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:
.TP
.B capability
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
expired, and not revoked.
.TP
.B certification
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]".

.SH AUTHOR

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

.SH SEE ALSO

.BR monkeysphere (1),
.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/