summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
Diffstat (limited to 'man')
-rw-r--r--man/man1/monkeysphere.163
-rw-r--r--man/man1/openpgp2ssh.159
-rw-r--r--man/man1/pem2openpgp.110
-rw-r--r--man/man7/monkeysphere.742
-rw-r--r--man/man8/monkeysphere-authentication.8113
-rw-r--r--man/man8/monkeysphere-host.8117
6 files changed, 227 insertions, 177 deletions
diff --git a/man/man1/monkeysphere.1 b/man/man1/monkeysphere.1
index 887b5df..327a623 100644
--- 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
@@ -21,7 +21,7 @@ connection authentication.
\fBmonkeysphere\fP takes various subcommands:
.TP
-.B update-known_hosts [HOST]...
+.B update\-known_hosts [HOST]...
Update the known_hosts file. For each specified host, gpg will be
queried for a key associated with the host URI (see HOST
IDENTIFICATION in
@@ -37,9 +37,9 @@ known_hosts file will be processed. This subcommand will exit with a
status of 0 if at least one acceptable key was found for a specified
host, 1 if no matching keys were found at all, and 2 if matching keys
were found but none were acceptable. `k' may be used in place of
-`update-known_hosts'.
+`update\-known_hosts'.
.TP
-.B update-authorized_keys
+.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
@@ -54,18 +54,18 @@ is found for the user ID, nothing is done. This subcommand will exit
with a status of 0 if at least one acceptable key was found for a user
ID, 1 if no matching keys were found at all, and 2 if matching keys
were found but none were acceptable. `a' may be used in place of
-`update-authorized_keys'.
+`update\-authorized_keys'.
.TP
-.B gen-subkey [KEYID]
+.B gen\-subkey [KEYID]
Generate an authentication subkey for a private key in your GnuPG
keyring. KEYID is the key ID for the primary key for which the subkey
with "authentication" capability will be generated. If no key ID is
specified, but only one key exists in the secret keyring, that key
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'.
+the `\-\-length' or `\-l' option. `g' may be used in place of
+`gen\-subkey'.
.TP
-.B ssh-proxycommand
+.B ssh\-proxycommand
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,
@@ -78,16 +78,16 @@ more info).
This command is meant to be run as the ssh "ProxyCommand". This can
either be done by specifying the proxy command on the command line:
-.B ssh -o ProxyCommand="monkeysphere ssh-proxycommand %h %p" ...
+.B ssh \-o ProxyCommand="monkeysphere ssh\-proxycommand %h %p" ...
or by adding the following line to your ~/.ssh/config script:
-.B ProxyCommand monkeysphere ssh-proxycommand %h %p
+.B ProxyCommand monkeysphere ssh\-proxycommand %h %p
The script can easily be incorporated into other ProxyCommand scripts
-by calling it with the "--no-connect" option, i.e.:
+by calling it with the "\-\-no\-connect" option, i.e.:
-.B monkeysphere ssh-proxycommand --no-connect "$HOST" "$PORT"
+.B monkeysphere ssh\-proxycommand \-\-no\-connect "$HOST" "$PORT"
This will run everything except the final exec of netcat to make the
TCP connection to the host. In this way this command can be added to
@@ -114,14 +114,17 @@ MONKEYSPHERE_CHECK_KEYSERVER environment variable to either `true' or
either always or never check the keyserver for host key updates.
.TP
-.B subkey-to-ssh-agent [ssh-add arguments]
+.B subkey\-to\-ssh\-agent [ssh\-add arguments]
Push all authentication-capable subkeys in your GnuPG secret keyring
into your running ssh-agent. Additional arguments are passed through
to
-.BR ssh-add (1).
+.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'.
+`\-d' argument. To require confirmation on each use of the key, pass
+`\-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 help
Output a brief usage summary. `h' or `?' may be used in place of
@@ -133,29 +136,33 @@ 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 (subkeys.pgp.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)
+.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
@@ -178,9 +185,9 @@ Daniel Kahn Gillmor <dkg@fifthhorseman.net>
.SH SEE ALSO
-.BR monkeysphere-host (8),
-.BR monkeysphere-authentication (8),
+.BR monkeysphere\-host (8),
+.BR monkeysphere\-authentication (8),
.BR monkeysphere (7),
.BR ssh (1),
-.BR ssh-add (1),
+.BR ssh\-add (1),
.BR gpg (1)
diff --git a/man/man1/openpgp2ssh.1 b/man/man1/openpgp2ssh.1
index 8374a9f..304a442 100644
--- a/man/man1/openpgp2ssh.1
+++ b/man/man1/openpgp2ssh.1
@@ -1,5 +1,5 @@
.\" -*- nroff -*-
-.Dd $Mdocdate: June 11, 2008 $
+.Dd $Mdocdate: March 1, 2009 $
.Dt OPENPGP2SSH 1
.Os
.Sh NAME
@@ -8,9 +8,9 @@ openpgp2ssh
.Sh SYNOPSIS
.Nm openpgp2ssh < mykey.gpg
.Pp
-.Nm gpg --export $KEYID | openpgp2ssh $KEYID
+.Nm gpg \-\-export $KEYID | openpgp2ssh $KEYID
.Pp
-.Nm gpg --export-secret-key $KEYID | openpgp2ssh $KEYID
+.Nm gpg \-\-export\-secret\-key $KEYID | openpgp2ssh $KEYID
.Sh DESCRIPTION
.Nm
takes an OpenPGP-formatted primary key and associated
@@ -28,13 +28,13 @@ fingerprint of the key or subkey desired, but
will accept as few as the last 8 digits of the fingerprint as a key
ID.
.Pp
-If the input contains an OpenPGP RSA or DSA public key, it will be
-converted to the OpenSSH-style single-line keystring, prefixed with
-the key type. This format is suitable (with minor alterations) for
+If the input contains an OpenPGP RSA public key, it will be converted
+to the OpenSSH-style single-line keystring, prefixed with the key type
+(`ssh\-rsa'). This format is suitable (with minor alterations) for
insertion into known_hosts files and authorized_keys files.
.Pp
-If the input contains an OpenPGP RSA or DSA secret key, it will be
-converted to the equivalent PEM-encoded private key.
+If the input contains an OpenPGP RSA secret key, it will be converted
+to the equivalent PEM-encoded private key.
.Pp
.Nm
is part of the
@@ -47,24 +47,19 @@ intentional, since ssh attaches no inherent significance to these
features.
.Pp
.Nm
-only works with RSA or DSA keys, because those are the
-only ones which work with ssh.
-.Pp
-Assuming a valid key type, though,
-.Nm
-will produce output for
-any requested key. This means, among other things, that it will
-happily export revoked keys, unverifiable keys, expired keys, etc.
-Make sure you do your own key validation before using this tool!
+will produce output for any requested RSA key. This means, among
+other things, that it will happily export revoked keys, unverifiable
+keys, expired keys, etc. Make sure you do your own key validation
+before using this tool!
.Sh EXAMPLES
-.Nm gpg --export-secret-key $KEYID | openpgp2ssh $KEYID | ssh-add -c /dev/stdin
+.Nm gpg \-\-export\-secret\-key $KEYID | openpgp2ssh $KEYID | ssh\-add \-c /dev/stdin
.Pp
This pushes the secret key into the active
-.Xr ssh-agent 1 .
+.Xr ssh\-agent 1 .
Tools such as
.Xr ssh 1
which know how to talk to the
-.Xr ssh-agent 1
+.Xr ssh\-agent 1
can now rely on the key.
.Sh AUTHOR
.Nm
@@ -72,26 +67,28 @@ and this man page were written by Daniel Kahn Gillmor
<dkg@fifthhorseman.net>.
.Sh BUGS
.Nm
+only works with RSA keys. DSA keys are the only other key type
+available in both OpenPGP and SSH, but they are currently unsupported
+by this utility.
+.Pp
+.Nm
+only accepts raw OpenPGP packets on standard input. It does not
+accept ASCII-armored input.
+.Nm
Currently only exports into formats used by the OpenSSH.
It should support other key output formats, such as those used by
-lsh(1) and putty(1).
+.Xr lsh 1
+and
+.Xr putty 1 .
.Pp
Secret key output is currently not passphrase-protected.
.Pp
.Nm
currently cannot handle passphrase-protected secret keys on input.
-.Pp
-Key identifiers consisting of an odd number of hex digits are not
-accepted. Users who use a key ID with a standard length of 8, 16, or
-40 hex digits should not be affected by this.
-.Pp
-.Nm
-only acts on keys associated with the first primary key
-passed in. If you send it more than one primary key, it will silently
-ignore later ones.
.Sh SEE ALSO
.Xr pem2openpgp 1 ,
.Xr monkeysphere 1 ,
.Xr monkeysphere 7 ,
.Xr ssh 1 ,
-.Xr monkeysphere-server 8
+.Xr monkeysphere-authentication 8 ,
+.Xr monkeysphere-host 8
diff --git a/man/man1/pem2openpgp.1 b/man/man1/pem2openpgp.1
index ae75b11..45fd1ee 100644
--- a/man/man1/pem2openpgp.1
+++ b/man/man1/pem2openpgp.1
@@ -1,12 +1,12 @@
.\" -*- nroff -*-
-.Dd $Mdocdate: January 25, 2009 $
+.Dd $Mdocdate: March 1, 2009 $
.Dt PEM2OPENPGP 1
.Os
.Sh NAME
pem2openpgp
.Nd translate PEM-encoded RSA keys to OpenPGP certificates
.Sh SYNOPSIS
-.Nm pem2openpgp "$USERID" < mykey.pem | gpg --import
+.Nm pem2openpgp "$USERID" < mykey.pem | gpg \-\-import
.Pp
.Nm PEM2OPENPGP_EXPIRATION=$((86400 * $DAYS)) PEM2OPENPGP_USAGE_FLAGS=authentication,certify pem2openpgp "$USERID" <mykey.pem
.Sh DESCRIPTION
@@ -61,7 +61,7 @@ will read the key from stdin.
and this man page were written by Daniel Kahn Gillmor
<dkg@fifthhorseman.net>.
.Sh BUGS
-Only handles RSA keys at the moment. It would be nice to handle DSA
+Only handles RSA keys at the moment. It might be nice to handle DSA
keys as well.
.Pp
Currently only creates certificates with a single User ID. Should be
@@ -81,5 +81,5 @@ https://labs.riseup.net/code/projects/show/monkeysphere
.Xr monkeysphere 1 ,
.Xr monkeysphere 7 ,
.Xr ssh 1 ,
-.Xr monkeysphere-host 8 ,
-.Xr monkeysphere-authentication 8
+.Xr monkeysphere\-host 8 ,
+.Xr monkeysphere\-authentication 8
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/
diff --git a/man/man8/monkeysphere-authentication.8 b/man/man8/monkeysphere-authentication.8
index 361822d..a28922c 100644
--- a/man/man8/monkeysphere-authentication.8
+++ b/man/man8/monkeysphere-authentication.8
@@ -1,29 +1,29 @@
-.TH MONKEYSPHERE-SERVER "8" "June 2008" "monkeysphere" "User Commands"
+.TH MONKEYSPHERE-SERVER "8" "March 2009" "monkeysphere" "User Commands"
.SH NAME
-monkeysphere-authentication \- Monkeysphere authentication admin tool.
+monkeysphere\-authentication - Monkeysphere authentication admin tool.
.SH SYNOPSIS
-.B monkeysphere-authentication \fIsubcommand\fP [\fIargs\fP]
-.br
-.B monkeysphere-authentication expert \fIexpert-subcommand\fP [\fIargs\fP]
+.B monkeysphere\-authentication \fIsubcommand\fP [\fIargs\fP]
.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.
+\fBMonkeysphere\fP is a framework to leverage the OpenPGP Web of Trust
+(WoT) 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.
-\fBmonkeysphere-authentication\fP is a Monkeysphere server admin utility.
+\fBmonkeysphere\-authentication\fP is a Monkeysphere server admin
+utility for configuring and managing SSH user authentication through
+the WoT.
.SH SUBCOMMANDS
-\fBmonkeysphere-authentication\fP takes various subcommands:
+\fBmonkeysphere\-authentication\fP takes various subcommands:
.TP
-.B update-users [ACCOUNT]...
+.B update\-users [ACCOUNT]...
Rebuild the monkeysphere-controlled authorized_keys files. For each
specified account, the user ID's listed in the account's
authorized_user_ids file are processed. For each user ID, gpg will be
@@ -35,29 +35,29 @@ RAW_AUTHORIZED_KEYS variable is set, then a separate authorized_keys
file (usually ~USER/.ssh/authorized_keys) is appended to the
monkeysphere-controlled authorized_keys file. If no accounts are
specified, then all accounts on the system are processed. `u' may be
-used in place of `update-users'.
+used in place of `update\-users'.
.TP
-.B add-id-certifier KEYID|FILE
+.B add\-id\-certifier KEYID|FILE
Instruct system to trust user identity certifications made by KEYID.
The key ID will be loaded from the keyserver. A file may be loaded
instead of pulling the key from the keyserver by specifying the path
-to the file as the argument, or by specifying `-` to load from stdin.
-Using the `-n' or `--domain' option allows you to indicate that you
+to the file as the argument, or by specifying `\-' to load from stdin.
+Using the `\-n' or `\-\-domain' option allows you to indicate that you
only trust the given KEYID to make identifications within a specific
domain (e.g. "trust KEYID to certify user identities within the
@example.org domain"). A certifier trust level can be specified with
-the `-t' or `--trust' option (possible values are `marginal' and
+the `\-t' or `\-\-trust' option (possible values are `marginal' and
`full' (default is `full')). A certifier trust depth can be specified
-with the `-d' or `--depth' option (default is 1). `c+' may be used in
-place of `add-id-certifier'.
+with the `\-d' or `\-\-depth' option (default is 1). `c+' may be used in
+place of `add\-id\-certifier'.
.TP
-.B remove-id-certifier KEYID
+.B remove\-id\-certifier KEYID
Instruct system to ignore user identity certifications made by KEYID.
-`c-' may be used in place of `remove-id-certifier'.
+`c\-' may be used in place of `remove\-id\-certifier'.
.TP
-.B list-id-certifiers
+.B list\-id\-certifiers
List key IDs trusted by the system to certify user identities. `c'
-may be used in place of `list-id-certifiers'.
+may be used in place of `list\-id\-certifiers'.
.TP
.B help
Output a brief usage summary. `h' or `?' may be used in place of
@@ -69,30 +69,30 @@ show version number
Other commands:
.TP
.B setup
-Setup the server for Monkeysphere user authentication. This command
-is idempotent and run automatically by the other commands, and should
-therefore not usually need to be run manually. `s' may be used in
-place of `setup'.
+Setup the server in preparation for Monkeysphere user authentication.
+This command is idempotent and run automatically by the other
+commands, and should therefore not usually need to be run manually.
+`s' may be used in place of `setup'.
.TP
.B diagnostics
Review the state of the server with respect to authentication. `d'
may be used in place of `diagnostics'.
.TP
-.B gpg-cmd
+.B gpg\-cmd
Execute a gpg command, as the monkeysphere user, on the monkeysphere
-authentication "sphere" keyring. This takes a single argument
-(multiple gpg arguments need to be quoted). Use this command with
-caution, as modifying the authentication sphere keyring can affect ssh
-user authentication.
+authentication `sphere' keyring. This takes a single argument
+(i.e. multiple gpg arguments need to be quoted all together). Use
+this command with caution, as modifying the authentication sphere
+keyring can affect ssh user authentication.
.SH SETUP USER AUTHENTICATION
If the server will handle user authentication through
monkeysphere-generated authorized_keys files, the server must be told
which keys will act as identity certifiers. This is done with the
-\fBadd-id-certifier\fP command:
+\fBadd\-id\-certifier\fP command:
-$ monkeysphere-authentication add-id-certifier KEYID
+# monkeysphere\-authentication add\-id\-certifier KEYID
where KEYID is the key ID of the server admin, or whoever's
certifications should be acceptable to the system for the purposes of
@@ -100,32 +100,34 @@ authenticating remote users. You can run this command multiple times
to indicate that multiple certifiers are trusted. You may also
specify a filename instead of a key ID, as long as the file contains a
single OpenPGP public key. Certifiers can be removed with the
-\fBremove-id-certifier\fP command, and listed with the
-\fBlist-id-certifiers\fP command.
+\fBremove\-id\-certifier\fP command, and listed with the
+\fBlist\-id\-certifiers\fP command.
-Remote users will then be granted access to a local account based on
-the appropriately-signed and valid keys associated with user IDs
-listed in that account's authorized_user_ids file. By default, the
+A remote user will be granted access to a local account based on the
+appropriately-signed and valid keys associated with user IDs listed in
+that account's authorized_user_ids file. By default, the
authorized_user_ids file for an account is
~/.monkeysphere/authorized_user_ids. This can be changed in the
-monkeysphere-authentication.conf file.
+monkeysphere\-authentication.conf file.
-The \fBupdate-users\fP command can then be used to generate
-authorized_keys file for local accounts based on the authorized user
-IDs listed in the account's authorized_user_ids file:
+The \fBupdate\-users\fP command is used to generate authorized_keys
+files for a local account based on the user IDs listed in the
+account's authorized_user_ids file:
-$ monkeysphere-authentication update-users USER
+# monkeysphere\-authentication update\-users USER
Not specifying USER will cause all accounts on the system to updated.
-sshd can then use these monkeysphere generated authorized_keys files
-to grant access to user accounts for remote users. You must also tell
+The ssh server can use these monkeysphere-generated authorized_keys
+files to grant access to user accounts for remote users. In order for
sshd to look at the monkeysphere-generated authorized_keys file for
-user authentication by setting the following in the sshd_config:
+user authentication, the AuthorizedKeysFile parameter must be set in
+the sshd_config to point to the monkeysphere\-generated
+authorized_keys files:
AuthorizedKeysFile /var/lib/monkeysphere/authentication/authorized_keys/%u
-It is recommended to add "monkeysphere-authentication update-users" to a
-system crontab, so that user keys are kept up-to-date, and key
+It is recommended to add "monkeysphere\-authentication update\-users"
+to a system crontab, so that user keys are kept up-to-date, and key
revocations and expirations can be processed in a timely manner.
.SH ENVIRONMENT
@@ -141,7 +143,7 @@ Set the log level. Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in
increasing order of verbosity. (INFO)
.TP
MONKEYSPHERE_KEYSERVER
-OpenPGP keyserver to use. (pool.sks-keyservers.net)
+OpenPGP keyserver to use. (pool.sks\-keyservers.net)
.TP
MONKEYSPHERE_AUTHORIZED_USER_IDS
Path to user's authorized_user_ids file. %h gets replaced with the
@@ -157,11 +159,10 @@ raw authorized_keys file. %h gets replaced with the user's homedir,
MONKEYSPHERE_PROMPT
If set to `false', never prompt the user for confirmation. (true)
-
.SH FILES
.TP
-/etc/monkeysphere/monkeysphere-authentication.conf
+/etc/monkeysphere/monkeysphere\-authentication.conf
System monkeysphere-authentication config file.
.TP
/var/lib/monkeysphere/authorized_keys/USER
@@ -169,7 +170,7 @@ Monkeysphere-generated user authorized_keys files.
.SH AUTHOR
-Written by:
+This man page was written by:
Jameson Rollins <jrollins@fifthhorseman.net>,
Daniel Kahn Gillmor <dkg@fifthhorseman.net>,
Matthew Goins <mjgoins@openflows.com>
@@ -177,7 +178,9 @@ Matthew Goins <mjgoins@openflows.com>
.SH SEE ALSO
.BR monkeysphere (1),
-.BR monkeysphere-host (8),
+.BR monkeysphere\-host (8),
.BR monkeysphere (7),
.BR gpg (1),
-.BR ssh (1)
+.BR ssh (1),
+.BR sshd (8),
+.BR sshd_config (5)
diff --git a/man/man8/monkeysphere-host.8 b/man/man8/monkeysphere-host.8
index 7909b62..3e01105 100644
--- a/man/man8/monkeysphere-host.8
+++ b/man/man8/monkeysphere-host.8
@@ -1,14 +1,12 @@
-.TH MONKEYSPHERE-SERVER "8" "June 2008" "monkeysphere" "User Commands"
+.TH MONKEYSPHERE-SERVER "8" "March 2009" "monkeysphere" "User Commands"
.SH NAME
-monkeysphere-host \- Monkeysphere host admin tool.
+monkeysphere\-host - Monkeysphere host admin tool.
.SH SYNOPSIS
-.B monkeysphere-host \fIsubcommand\fP [\fIargs\fP]
-.br
-.B monkeysphere-host expert \fIexpert-subcommand\fP [\fIargs\fP]
+.B monkeysphere\-host \fIsubcommand\fP [\fIargs\fP]
.SH DESCRIPTION
@@ -17,29 +15,31 @@ 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.
-\fBmonkeysphere-host\fP is a Monkeysphere server admin utility.
+\fBmonkeysphere\-host\fP is a Monkeysphere server admin utility for
+managing the host's OpenPGP host key.
.SH SUBCOMMANDS
-\fBmonkeysphere-host\fP takes various subcommands:
+\fBmonkeysphere\-host\fP takes various subcommands:
.TP
-.B import-key FILE NAME[:PORT]
-Import a pem-encoded ssh secret host key from file FILE. If FILE
-is '-', then the key will be imported from stdin. NAME[:PORT] is used
-to specify the fully-qualified hostname (and port) used in the user ID
-of the new OpenPGP key. If PORT is not specified, the no port is
-added to the user ID, which means port 22 is assumed. `i' may be used
-in place of `import-key'.
+.B import\-key FILE NAME[:PORT]
+Import a pem-encoded ssh secret host key from file FILE. If FILE is
+`\-', then the key will be imported from stdin. Only RSA keys are
+supported at the moment. NAME[:PORT] is used to specify the
+fully-qualified hostname (and port) used in the user ID of the new
+OpenPGP key. If PORT is not specified, the no port is added to the
+user ID, which means port 22 is assumed. `i' may be used in place of
+`import\-key'.
.TP
-.B show-key
+.B show\-key
Output information about host's OpenPGP and SSH keys. `s' may be used
-in place of `show-key'.
+in place of `show\-key'.
.TP
-.B extend-key [EXPIRE]
+.B set\-expire [EXPIRE]
Extend the validity of the OpenPGP key for the host until EXPIRE from
the present. If EXPIRE is not specified, then the user will be
prompted for the extension term. Expiration is specified as with
-GnuPG:
+GnuPG (measured from today's date):
.nf
0 = key does not expire
<n> = key expires in n days
@@ -47,24 +47,24 @@ GnuPG:
<n>m = key expires in n months
<n>y = key expires in n years
.fi
-`e' may be used in place of `extend-key'.
+`e' may be used in place of `set\-expire'.
.TP
-.B add-hostname HOSTNAME
+.B add\-hostname HOSTNAME
Add a hostname user ID to the server host key. `n+' may be used in
-place of `add-hostname'.
+place of `add\-hostname'.
.TP
-.B revoke-hostname HOSTNAME
-Revoke a hostname user ID from the server host key. `n-' may be used
-in place of `revoke-hostname'.
+.B revoke\-hostname HOSTNAME
+Revoke a hostname user ID from the server host key. `n\-' may be used
+in place of `revoke\-hostname'.
.TP
-.B add-revoker KEYID|FILE
+.B add\-revoker KEYID|FILE
Add a revoker to the host's OpenPGP key. The key ID will be loaded
from the keyserver. A file may be loaded instead of pulling the key
from the keyserver by specifying the path to the file as the argument,
-or by specifying `-` to load from stdin. `r+' may be be used in place
+or by specifying `\-' to load from stdin. `r+' may be be used in place
of `add-revoker'.
.TP
-.B revoke-key
+.B revoke\-key
Generate (with the option to publish) a revocation certificate for the
host's OpenPGP key. If such a certificate is published, your host key
will be permanently revoked. This subcommand will ask you a series of
@@ -73,9 +73,10 @@ to stdout. If you explicitly tell it to publish the revocation
certificate immediately, it will send it to the public keyservers.
USE WITH CAUTION!
.TP
-.B publish-key
-Publish the host's OpenPGP key to the keyserver. `p' may be used in
-place of `publish-key'.
+.B publish\-key
+Publish the host's OpenPGP key to the public keyservers. `p' may be
+used in place of `publish-key'. Note that there is no way to remove a
+key from the public keyservers once it is published!
.TP
.B help
Output a brief usage summary. `h' or `?' may be used in place of
@@ -90,25 +91,41 @@ Other commands:
.B diagnostics
Review the state of the monkeysphere server host key and report on
suggested changes. Among other checks, this includes making sure
-there is a valid host key, that the key is published, that the sshd
+there is a valid host key, that the key is not expired, that the sshd
configuration points to the right place, etc. `d' may be used in
place of `diagnostics'.
.SH SETUP HOST AUTHENTICATION
-To enable host verification via the monkeysphere, the host's key must
-be published to the Web of Trust. This is not done by default. To
-publish the host key to the keyservers, run the following command:
+To enable host verification via the monkeysphere, an OpenPGP key must
+be made out of the host's ssh key, and the key must be published to
+the Web of Trust. This is not done by default. The first step is to
+import the host's ssh key into a monkeysphere-style OpenPGP key. This
+is done with the import\-key command. When importing a key, you must
+specify the path to the host's ssh RSA key to import, and a hostname
+to use as the key's user ID:
-$ monkeysphere-host publish-key
+# monkeysphere\-host import\-key /etc/ssh/ssh_host_rsa_key host.example.org
+
+On most systems, the ssh host RSA key is stored at
+/etc/ssh/ssh_host_rsa_key.
+
+Once the host key has been imported, it must be published to the Web
+of Trust so that users can retrieve the key when sshing to the host.
+The host key is published to the keyserver with the publish\-key
+command:
+
+$ monkeysphere\-host publish\-key
In order for users logging into the system to be able to identify the
host via the monkeysphere, at least one person (e.g. a server admin)
will need to sign the host's key. This is done using standard OpenPGP
keysigning techniques, usually: pull the key from the keyserver,
-verify and sign the key, and then re-publish the signature. Once an
-admin's signature is published, users logging into the host can use it
-to validate the host's key.
+verify and sign the key, and then re-publish the signature. Please
+see http://web.monkeysphere.info/signing-host-keys/ for more
+information. Once an admin's signature is published, users logging
+into the host can use it to validate the host's key without having to
+manually check the host key's fingerprint.
.SH ENVIRONMENT
@@ -116,29 +133,28 @@ The following environment variables will override those specified in
the config 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_KEYSERVER
-OpenPGP keyserver to use (pool.sks-keyservers.net).
+OpenPGP keyserver to use. (pool.sks\-keyservers.net)
.TP
MONKEYSPHERE_PROMPT
If set to `false', never prompt the user for confirmation. (true)
-
.SH FILES
.TP
-/etc/monkeysphere/monkeysphere-host.conf
-System monkeysphere-host config file.
+/etc/monkeysphere/monkeysphere\-host.conf
+System monkeysphere\-host config file.
.TP
-/var/lib/monkeysphere/host/ssh_host_rsa_key
-Copy of the host's private key in ssh format, suitable for use by
-sshd.
+/var/lib/monkeysphere/host/ssh_host_rsa_key.pub.gpg
+A world-readable copy of the host's public key in OpenPGP format,
+including all relevant self-signatures.
.SH AUTHOR
-Written by:
+This man page was written by:
Jameson Rollins <jrollins@fifthhorseman.net>,
Daniel Kahn Gillmor <dkg@fifthhorseman.net>,
Matthew Goins <mjgoins@openflows.com>
@@ -146,7 +162,8 @@ Matthew Goins <mjgoins@openflows.com>
.SH SEE ALSO
.BR monkeysphere (1),
-.BR monkeysphere-authentication (8),
+.BR monkeysphere\-authentication (8),
.BR monkeysphere (7),
.BR gpg (1),
-.BR ssh (1)
+.BR ssh (1),
+.BR sshd (8)
generated by cgit v1.2.3 (git 2.39.1) at 2024-08-17 14:36:32 +0000