- .TH MONKEYSPHERE-SERVER "1" "June 2008" "monkeysphere 0.1" "User Commands"
- .SH NAME
- monkeysphere-server \- monkeysphere server admin user interface
- .SH SYNOPSIS
- .B monkeysphere-server \fIcommand\fP [\fIargs\fP]
- .SH DESCRIPTION
- \fBMonkeySphere\fP is a system to leverage the OpenPGP Web of Trust
- for ssh authentication. OpenPGP keys are tracked via GnuPG, and added
- to the ssh authorized_keys and known_hosts files to be used for
- authentication of ssh connections.
- \fBmonkeysphere-server\fP is the MonkeySphere server admin utility.
- .SH SUBCOMMANDS
- \fBmonkeysphere-server\fP takes various subcommands:
- .TP
- .B update-users [USER]...
- Update admin-controlled authorized_keys files at
- /var/cache/monkeysphere/authorized_keys/USER. For each specified
- user, the user ID's listed in the user's authorized_user_ids file are
- processed. For each user ID, gpg will be queried for keys associated
- with that user ID, querying a keyserver if specified. If a key is
- found, it will be converted to an ssh key, and any matching ssh keys
- will be removed from the user's authorized_keys file. If the found
- key is acceptable (see KEY ACCEPTABILITY), then the key will be
- updated and re-added to the authorized_keys file. If no gpg key is
- found for the user ID, then nothing is done. If the
- RAW_AUTHORIZED_KEYS variable is set, then a user-controlled
- authorized_keys file (usually ~USER/.ssh/authorized_keys) is added to
- the authorized_keys file. If no users are specified, then all users
- listed in /etc/passwd are processed. `u' may be used in place of
- `update-users.
- .TP
- .B gen-key
- Generate a OpenPGP key pair for the host. `g' may be used in place of
- `gen-key'.
- .TP
- .B show-fingerprint
- Show the fingerprint for the host's OpenPGP key. `f' may be used in place of
- `show-fingerprint'.
- .TP
- .B publish-key
- Publish the host's OpenPGP key to the keyserver. `p' may be used in
- place of `publish-key'.
- .TP
- .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
- List certifier keys. `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
- `help'.
- .SH SETUP
- 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. This can be done with the
- \fBgen-key\fP subcommand:
- $ 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 \fBpublish-key\fP
- 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
- In order 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, the server must be told
- which keys will act as user certifiers. This is done with the
- \fBadd-certifier\fP 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 \fBremove-certifier\fP command, and listed with the
- \fBlist-certifiers\fP 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 \fBupdate-users\fP command can then be used to generate
- authorized_keys file for local users based on the authorized user IDs
- listed in the user's authorized_user_ids file:
- $ monkeysphere-server update-users USER
- sshd can then use these files to grant access to user accounts for
- remote users. 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
- 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 KEY ACCEPTABILITY
- GPG 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 must be "fully" valid (ie. signed by a trusted certifier), and
- must not be expired or revoked.
- .SH FILES
- .TP
- /etc/monkeysphere/monkeysphere-server.conf
- System monkeysphere-server config file.
- .TP
- /etc/monkeysphere/monkeysphere.conf
- System-wide monkeysphere config file.
- .TP
- /var/lib/monkeysphere/authorized_keys/USER
- Monkeysphere-generated user authorized_keys files.
- .TP
- /var/lib/monkeysphere/ssh_host_rsa_key
- Copy of the host's private key in ssh format, suitable for use by
- sshd.
- .TP
- /var/lib/monkeysphere/gnupg-host
- Monkeysphere host GNUPG home directory.
- .TP
- /var/lib/monkeysphere/gnupg-authentication
- Monkeysphere authentication GNUPG home directory.
- .SH AUTHOR
- Written by Jameson Rollins <jrollins@fifthhorseman.net>
- .SH SEE ALSO
- .BR monkeysphere (1),
- .BR gpg (1),
- .BR ssh (1)
|