diff options
| -rw-r--r-- | man/man7/monkeysphere.7 | 13 | ||||
| -rw-r--r-- | man/man8/monkeysphere-authentication.8 | 62 | ||||
| -rw-r--r-- | man/man8/monkeysphere-host.8 | 82 | ||||
| -rwxr-xr-x | src/monkeysphere | 2 | ||||
| -rwxr-xr-x | tests/basic | 15 |
5 files changed, 102 insertions, 72 deletions
diff --git a/man/man7/monkeysphere.7 b/man/man7/monkeysphere.7 index 8d7c43a..d221c87 100644 --- a/man/man7/monkeysphere.7 +++ b/man/man7/monkeysphere.7 @@ -7,7 +7,7 @@ Trust .SH DESCRIPTION -\fBMonkeySphere\fP is a framework to leverage the OpenPGP Web of Trust +\fBMonkeysphere\fP is a framework to leverage the OpenPGP Web of Trust for ssh authentication. OpenPGP keys are tracked via GnuPG, and added to the authorized_keys and known_hosts files used by ssh for connection authentication. @@ -40,14 +40,17 @@ URI specification for the host, i.e. "ssh://host.full.domain[:port]". .SH AUTHOR -Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel Kahn -Gillmor <dkg@fifthhorseman.net> +Written by: +Jameson Rollins <jrollins@fifthhorseman.net>, +Daniel Kahn Gillmor <dkg@fifthhorseman.net> .SH SEE ALSO .BR monkeysphere (1), -.BR monkeysphere-server (8), -.BR monkeysphere-ssh-proxycommand (1), +.BR monkeysphere-host (8), +.BR monkeysphere-authentication (8), +.BR openpgp2ssh (1), +.BR pem2openpgp (1), .BR gpg (1), .BR ssh (1), .BR http://tools.ietf.org/html/rfc4880, diff --git a/man/man8/monkeysphere-authentication.8 b/man/man8/monkeysphere-authentication.8 index 68a7a1b..2b0091e 100644 --- a/man/man8/monkeysphere-authentication.8 +++ b/man/man8/monkeysphere-authentication.8 @@ -20,26 +20,28 @@ authentication. \fBmonkeysphere-authentication\fP is a Monkeysphere server admin utility. .SH SUBCOMMANDS -\fBmonkeysphere-authentication\fP takes various subcommands.(Users may use the -abbreviated subcommand in parentheses): +\fBmonkeysphere-authentication\fP takes various subcommands. .TP -.B update-users (u) [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 queried for keys associated with that -user ID, optionally querying a keyserver. If an acceptable key is found (see -KEY ACCEPTABILITY in monkeysphere(7)), the key is added to the account's -monkeysphere-controlled authorized_keys file. If the 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'. - -\" XXX - +.B setup +Setup the server for Monkeysphere user authentication. `s' may be +used in place of `setup'. .TP -.B add-id-certifier (c+) KEYID +.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 +queried for keys associated with that user ID, optionally querying a +keyserver. If an acceptable key is found (see KEY ACCEPTABILITY in +monkeysphere(7)), the key is added to the account's +monkeysphere-controlled authorized_keys file. If the +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'. +.TP +.B add-id-certifier KEYID Instruct system to trust user identity certifications made by KEYID. Using the `-n' or `--domain' option allows you to indicate that you only trust the given KEYID to make identifications within a specific @@ -50,11 +52,11 @@ the `-t' or `--trust' option (possible values are `marginal' and with the `-d' or `--depth' option (default is 1). `c+' may be used in place of `add-id-certifier'. .TP -.B remove-id-certifier (c-) 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'. .TP -.B list-id-certifiers (c) +.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'. .TP @@ -66,11 +68,13 @@ Output a brief usage summary. `h' or `?' may be used in place of show version number .SH "EXPERT" SUBCOMMANDS + Some commands are very unlikely to be needed by most administrators. -These commands must follow the word `expert'. +These commands must prefaced by the word `expert'. .TP -.B diagnostics (d) -Review the state of the server with respect to authentication. +.B diagnostics +Review the state of the server with respect to authentication. `d' +may be used in place of `diagnostics'. .TP .B gpg-cmd Execute a gpg command on the gnupg-authentication keyring as the @@ -79,7 +83,7 @@ arguments need to be quoted). Use this command with caution, as modifying the gnupg-authentication keyring can affect ssh user authentication. -.SH SETUP +.SH SETUP USER AUTHENTICATION If the server will handle user authentication through monkeysphere-generated authorized_keys files, the server must be told @@ -116,7 +120,7 @@ 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: -AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u +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 @@ -125,7 +129,7 @@ revocations and expirations can be processed in a timely manner. .SH ENVIRONMENT The following environment variables will override those specified in -(defaults in parentheses): +the config file (defaults in parentheses): .TP MONKEYSPHERE_MONKEYSPHERE_USER User to control authentication keychain (monkeysphere). @@ -135,7 +139,7 @@ Set the log level (INFO). Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in increasing order of verbosity. .TP MONKEYSPHERE_KEYSERVER -OpenPGP keyserver to use (subkeys.pgp.net). +OpenPGP keyserver to use (pool.sks-keyservers.net). .TP MONKEYSPHERE_AUTHORIZED_USER_IDS Path to user authorized_user_ids file @@ -156,8 +160,10 @@ Monkeysphere-generated user authorized_keys files. .SH AUTHOR -Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel Kahn -Gillmor <dkg@fifthhorseman.net> +Written by: +Jameson Rollins <jrollins@fifthhorseman.net>, +Daniel Kahn Gillmor <dkg@fifthhorseman.net>, +Matthew Goins <mjgoins@openflows.com> .SH SEE ALSO diff --git a/man/man8/monkeysphere-host.8 b/man/man8/monkeysphere-host.8 index fd676a4..78b6b4a 100644 --- a/man/man8/monkeysphere-host.8 +++ b/man/man8/monkeysphere-host.8 @@ -23,6 +23,10 @@ connection authentication. \fBmonkeysphere-host\fP takes various subcommands: .TP +.B show-key +Output information about host's OpenPGP and SSH keys. `s' may be used +in place of `show-key'. +.TP .B extend-key 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 @@ -36,7 +40,6 @@ does: <n>y = key expires in n years .fi `e' may be used in place of `extend-key'. - .TP .B add-hostname HOSTNAME Add a hostname user ID to the server host key. `n+' may be used in @@ -47,11 +50,12 @@ Revoke a hostname user ID from the server host key. `n-' may be used in place of `revoke-hostname'. .TP .B add-revoker FINGERPRINT - +Add a revoker to the host's OpenPGP key. `o' may be be used in place +of `add-revoker'. .TP -.B show-key -Output gpg information about host's OpenPGP key. `s' may be used in -place of `show-key'. +.B revoke-key +Revoke the host's OpenPGP key. `r' may be used in place of +`revoke-key'. .TP .B publish-key Publish the host's OpenPGP key to the keyserver. `p' may be used in @@ -63,9 +67,11 @@ Output a brief usage summary. `h' or `?' may be used in place of .TP .B version show version number + .SH "EXPERT" SUBCOMMANDS + Some commands are very unlikely to be needed by most administrators. -These commands must follow the word `expert'. +These commands must prefaced by the word `expert'. .TP .B gen-key [HOSTNAME] Generate a OpenPGP key for the host. If HOSTNAME is not specified, @@ -73,18 +79,8 @@ then the system fully-qualified domain name will be user. An alternate key bit length can be specified with the `-l' or `--length' option (default 2048). An expiration length can be specified with the `-e' or `--expire' option (prompt otherwise). The expiration format -is the same as that of \fBextend-key\fP, below. A key revoker -fingerprint can be specified with the `-r' or `--revoker' option. `g' -may be used in place of `gen-key'. - -.TP -.B diagnostics -Review the state of the server with respect to the MonkeySphere in -general 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 configuration points to the right place, and -that there are at least some valid identity certifiers. `d' may be -used in place of `diagnostics'. +is the same as that of \fBextend-key\fP, below. `g' may be used in +place of `gen-key'. .TP .B import-key FIXME: @@ -92,53 +88,63 @@ FIXME: --hostname (-h) NAME[:PORT] hostname for key user ID --keyfile (-f) FILE key file to import --expire (-e) EXPIRE date to expire +.TP +.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 +configuration points to the right place, etc. `d' may be used in +place of `diagnostics'. -.SH SETUP +.SH SETUP HOST AUTHENTICATION -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: +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: -$ monkeysphere-server gen-key +$ monkeysphere-host publish-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. You must also modify the -sshd_config on the server to tell sshd where the new server host key -is located: +You must also modify the sshd_config on the server to tell sshd where +the new server host key is located: -HostKey /var/lib/monkeysphere/ssh_host_rsa_key +HostKey /var/lib/monkeysphere/host/ssh_host_rsa_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: pul 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. +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. + +.SH ENVIRONMENT +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. .TP MONKEYSPHERE_KEYSERVER -OpenPGP keyserver to use (subkeys.pgp.net). +OpenPGP keyserver to use (pool.sks-keyservers.net). .SH FILES + .TP /etc/monkeysphere/monkeysphere-host.conf System monkeysphere-host config file. .TP -/var/lib/monkeysphere/ssh_host_rsa_key +/var/lib/monkeysphere/host/ssh_host_rsa_key Copy of the host's private key in ssh format, suitable for use by sshd. .SH AUTHOR -Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel Kahn -Gillmor <dkg@fifthhorseman.net> +Written by: +Jameson Rollins <jrollins@fifthhorseman.net>, +Daniel Kahn Gillmor <dkg@fifthhorseman.net>, +Matthew Goins <mjgoins@openflows.com> .SH SEE ALSO diff --git a/src/monkeysphere b/src/monkeysphere index 8b7bfee..da5f406 100755 --- a/src/monkeysphere +++ b/src/monkeysphere @@ -51,7 +51,7 @@ subcommands: gen-subkey (g) [KEYID] generate an authentication subkey --length (-l) BITS key length in bits (2048) --expire (-e) EXPIRE date to expire - ssh-proxycommand ssh proxycommand + ssh-proxycommand monkeysphere ssh ProxyCommand subkey-to-ssh-agent (s) store authentication subkey in ssh-agent version (v) show version number help (h,?) this help diff --git a/tests/basic b/tests/basic index b5afb23..99a881b 100755 --- a/tests/basic +++ b/tests/basic @@ -23,6 +23,9 @@ which socat >/dev/null || { echo "You must have socat installed to run this test ## FIXME: other checks? +###################################################################### +### FUNCTIONS + # gpg command for test admin user gpgadmin() { GNUPGHOME="$TEMPDIR"/admin/.gnupg gpg "$@" @@ -103,7 +106,9 @@ SSHD_PID= trap failed_cleanup EXIT +###################################################################### ### SETUP VARIABLES + ## set up some variables to ensure that we're operating strictly in ## the tests, not system-wide: @@ -138,6 +143,7 @@ export SOCKET="$TEMPDIR"/ssh-socket export DISPLAY=monkeys +###################################################################### ### CONFIGURE ENVIRONMENTS # copy in admin and testuser home to tmp @@ -172,6 +178,7 @@ AuthorizedKeysFile ${MONKEYSPHERE_SYSDATADIR}/authentication/authorized_keys/%u EOF +###################################################################### ### SERVER HOST SETUP # set up monkeysphere host @@ -199,12 +206,15 @@ echo "### certifying server host key..." GNUPGHOME="$MONKEYSPHERE_SYSCONFIGDIR"/host gpg --armor --export "$HOSTKEYID" | gpgadmin --import echo y | gpgadmin --command-fd 0 --sign-key "$HOSTKEYID" +# FIXME: add revoker? + # FIXME: how can we test publish-key without flooding junk into the # keyservers? # FIXME: should we run "diagnostics" here to test setup? +###################################################################### ### SERVER AUTHENTICATION SETUP # set up monkeysphere authentication @@ -226,6 +236,7 @@ echo y | monkeysphere-authentication add-id-certifier "$TEMPDIR"/admin/.gnupg/pu # FIXME: should we run "diagnostics" here to test setup? +###################################################################### ### TESTUSER SETUP # generate an auth subkey for the test user that expires in 2 days @@ -249,6 +260,7 @@ echo "### update server authorized_keys file for this testuser..." monkeysphere-authentication update-users $(whoami) +###################################################################### ### TESTS # connect to test sshd, using monkeysphere-ssh-proxycommand to verify @@ -293,6 +305,9 @@ chmod o-w "$TESTHOME"/.monkeysphere/authorized_user_ids # FIXME: addtest: revoke the host key and check ssh failure + +###################################################################### + trap - EXIT echo "##################################################" |