summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
Diffstat (limited to 'man')
-rw-r--r--man/man8/monkeysphere-server.882
1 files changed, 68 insertions, 14 deletions
diff --git a/man/man8/monkeysphere-server.8 b/man/man8/monkeysphere-server.8
index dbcc083..3411c64 100644
--- a/man/man8/monkeysphere-server.8
+++ b/man/man8/monkeysphere-server.8
@@ -32,7 +32,7 @@ user-controlled authorized_keys file (usually
may be used in place of `update-users.
.TP
.B gen-key
-Generate a gpg key for the host. `g' may be used in place of
+Generate a gpg key pair for the host. `g' may be used in place of
`gen-key'.
.TP
.B show-fingerprint
@@ -43,11 +43,24 @@ Show the fingerprint for the host's OpenPGP key. `f' may be used in place of
Publish the host's gpg key to the keyserver. `p' may be used in place
of `publish-key'.
.TP
-.B trust-key KEYID [LEVEL]
-Set owner trust for key. If LEVEL is not specified, then the program
+.B add-certifier KEYID
+Add a certifier key to host keyring. The key with specified key ID
+will be retrieved from the keyserver and imported to the host keyring.
+It will then be given a non-exportable trust signature, with default
+depth of 1, so that the key may certifier users to log into the
+system. `a' may be used in place of `add-certifier'.
+.TP
+.B remove-certifier KEYID
+Remove a certifier key from the host keyring. The key with specified
+key ID will be removed entirely from the host keyring so that the key
+will not longer be able to certify users on the system. `r' may be
+used in place of `remove-certifier'.
+.TP
+.B list-certifiers KEYID
+Add key to certify system users. If LEVEL is not specified, then the program
will prompt for an owner trust level to set for KEYID. This function
-lsigns the key as well so that it will have a known validity. `t' may
-be used in place of `trust-key'.
+lsigns the key as well so that it will have a known validity. `l' may
+be used in place of `list-certifiers'.
.TP
.B help
Output a brief usage summary. `h' or `?' may be used in place of
@@ -55,22 +68,63 @@ Output a brief usage summary. `h' or `?' may be used in place of
.SH SETUP
-In order to start using the monkeysphere, there are a couple of things
-you need to do first. The first is to generate an OpenPGP key for the
-server and convert that key to an ssh key that can be used by ssh for
-host authentication. To do this, run the "gen-key" subcommand. Once
-that is done, publish the key to a keyserver with "publish-key"
-subcommand. Finally, you need to modify the sshd_config to tell sshd
-where the new server host key:
+In order to start using the monkeysphere, you must first generate an
+OpenPGP key for the server and convert that key to an ssh key that can
+be used by ssh for host authentication. To do this, run the "gen-key"
+subcommand to generate the host key pair:
+
+$ monkeysphere-server gen-key
+
+To enable host verification via the monkeysphere, you must then
+publish the host's key to the Web of Trust using the "publish-key"
+command to push the key to a keyserver. Then modify the sshd_config
+to tell sshd where the new server host key is located:
HostKey /var/lib/monkeysphere/ssh_host_rsa_key
+For users logging into the system to be able to verify the host via
+the monkeysphere, at least one person (ie. a server admin) will need
+to sign the host's key. This is done in the same way that key signing
+is usually done, by pulling the host's key from the keyserver, signing
+the key, and re-publishing the signature. Once that is done, users
+logging into the host will be able to certify the host's key via the
+signature of the host admin.
+
If the server will also handle user authentication through
-monkeysphere-generated authorized_keys files, set the following:
+monkeysphere-generated authorized_keys files, the server must be told
+which keys will act as user certifiers. This is done with the
+"add-certifier" command:
+
+$ monkeysphere-server add-certifier KEYID
+
+where KEYID is the key ID of the server admin, or whoever's signature
+will be certifying users to the system. Certifiers can be later
+remove with the "remove-certifier" command, and listed with the
+"list-certifiers" command.
+
+Remote user's will then be granted access to a local user account
+based on the appropriately signed and valid keys associated with user
+IDs listed in the authorized_user_ids file of the local user. By
+default, the authorized_user_ids file for local users is found in
+~/.config/monkeysphere/authorized_user_ids. This can be changed in
+the monkeysphere-server.conf file.
+
+The "update-users" command can then be used to generate
+authorized_keys file for local users that sshd can use to grant access
+to user accounts for remote users:
+
+$ monkeysphere-server update-users [USER]
+
+If no user is specified, authorized_keys files will be generated for
+all users on the system. 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:
AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
-Once those changes are made, restart the ssh server.
+It is recommended to add "monkeysphere-server update-users" to a
+system crontab, so that user keys are kept up-to-date, and key
+revokations and expirations can be processed in a timely manor.
.SH FILES