From 4cf60ae41b38e76a5c30de991b470c80abbc57e4 Mon Sep 17 00:00:00 2001 From: Jameson Graef Rollins Date: Mon, 2 Mar 2009 13:21:22 -0500 Subject: [PATCH] expanded/clarified setup examples --- man/man8/monkeysphere-authentication.8 | 26 ++++++++------- man/man8/monkeysphere-host.8 | 46 +++++++++++++++++--------- 2 files changed, 45 insertions(+), 27 deletions(-) diff --git a/man/man8/monkeysphere-authentication.8 b/man/man8/monkeysphere-authentication.8 index cfd13e7..dfa7444 100644 --- a/man/man8/monkeysphere-authentication.8 +++ b/man/man8/monkeysphere-authentication.8 @@ -16,7 +16,8 @@ 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 for configuring SSH user authentication through the WoT. +utility for configuring and managing SSH user authentication through +the WoT. .SH SUBCOMMANDS @@ -102,24 +103,26 @@ single OpenPGP public key. Certifiers can be removed with the \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 +Remote users will be granted access to local accounts 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. -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 local accounts based on the authorized user IDs listed in +the account's authorized_user_ids file: $ 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 -sshd to look at the monkeysphere-generated authorized_keys file for -user authentication by setting the following in the sshd_config: +The ssh server can then 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, 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 @@ -156,7 +159,6 @@ 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 diff --git a/man/man8/monkeysphere-host.8 b/man/man8/monkeysphere-host.8 index 6198a65..8968cd7 100644 --- a/man/man8/monkeysphere-host.8 +++ b/man/man8/monkeysphere-host.8 @@ -15,19 +15,21 @@ 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: .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'. +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 Output information about host's OpenPGP and SSH keys. `s' may be used @@ -95,9 +97,23 @@ 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 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 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 @@ -105,9 +121,11 @@ 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 hosts key's fingerprint. .SH ENVIRONMENT @@ -124,7 +142,6 @@ OpenPGP keyserver to use. (pool.sks\-keyservers.net) MONKEYSPHERE_PROMPT If set to `false', never prompt the user for confirmation. (true) - .SH FILES .TP @@ -150,4 +167,3 @@ Matthew Goins .BR gpg (1), .BR ssh (1), .BR sshd (8), - -- 2.26.2