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
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
.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
gen-key (g) [HOSTNAME] generate gpg key for the server
show-fingerprint (f) show server's host key fingerprint
publish-key (p) publish server's host key to keyserver
- trust-key (t) KEYID import and tsign a certification key
+ add-certifier (a) KEYID import and tsign a certification key
+ remove-certifier (r) KEYID remove a certification key
+ list-certifiers (l) list certification keys
help (h,?) this help
EOF
echo "The following key parameters will be used for the host private key:"
echo "$keyParameters"
- read -p "Generate key? [Y|n]: " OK; OK=${OK:=Y}
+ read -p "Generate key? (Y/n) " OK; OK=${OK:=Y}
if [ ${OK/y/Y} != 'Y' ] ; then
failure "aborting."
fi
# publish server key to keyserver
publish_server_key() {
- read -p "really publish key to $KEYSERVER? [y|N]: " OK; OK=${OK:=N}
+ read -p "really publish key to $KEYSERVER? (y/N) " OK; OK=${OK:=N}
if [ ${OK/y/Y} != 'Y' ] ; then
failure "aborting."
fi
failure "NOT PUBLISHED (to avoid permanent publication errors during monkeysphere development)."
}
-# retrieve key from web of trust, and set owner trust to "full"
-# if key is found.
-trust_key() {
+# retrieve key from web of trust, import it into the host keyring, and
+# ltsign the key in the host keyring so that it may certify other keys
+add_certifier() {
local keyID
- local trustLevel
+ local fingerprint
+ local ltsignCommand
keyID="$1"
-
- # default values for trust depth and domain
- DEPTH=${DEPTH:-1}
- DOMAIN=${DOMAIN:-}
-
- if [ -z "$keyID" ] ; then
- failure "You must specify key to trust."
- fi
-
export keyID
# export host ownertrust to authentication keyring
echo "key found:"
gpg_authentication "--fingerprint $fingerprint"
+ read -p "Are you sure you want to add this key as a certifier of users on this system? (y/N) " OK; OK=${OK:-N}
+ if [ "${OK/y/Y}" != 'Y' ] ; then
+ failure "aborting."
+ fi
+
# export the key to the host keyring
gpg_authentication "--export $keyID" | gpg_host --import
+ # default values for trust depth and domain
+ DEPTH=${DEPTH:-1}
+ DOMAIN=${DOMAIN:-}
+
# ltsign command
# NOTE: *all* user IDs will be ltsigned
ltsignCommand=$(cat <<EOF
gpg_authentication "--check-trustdb"
}
+# delete a certifiers key from the host keyring
+remove_certifier() {
+ local keyID
+ local fingerprint
+
+ keyID="$1"
+
+ # delete the requested key (with prompting)
+ gpg_host --delete-key "$keyID"
+
+ # update the trustdb for the authentication keyring
+ gpg_authentication "--check-trustdb"
+}
+
+# list the host certifiers
+list_certifiers() {
+ gpg_host --list-keys
+}
+
########################################################################
# MAIN
########################################################################
publish_server_key
;;
- 'trust-key'|'t')
- trust_key "$@"
+ 'add-certifier'|'a')
+ if [ -z "$1" ] ; then
+ failure "You must specify a key ID."
+ fi
+ add_certifier "$1"
+ ;;
+
+ 'remove-certifier'|'r')
+ if [ -z "$1" ] ; then
+ failure "You must specify a key ID."
+ fi
+ remove_certifier "$1"
+ ;;
+
+ 'list-certifiers'|'l')
+ list_certifiers "$@"
;;
'help'|'h'|'?')
projects / monkeysphere.git / commitdiff