diff options
| -rw-r--r-- | man/man1/monkeysphere.1 | 76 | ||||
| -rw-r--r-- | man/man1/openpgp2ssh.1 | 3 | ||||
| -rw-r--r-- | man/man5/monkeysphere.5 | 54 | ||||
| -rw-r--r-- | man/man8/monkeysphere-server.8 | 76 | ||||
| -rw-r--r-- | src/common | 2 |
5 files changed, 118 insertions, 93 deletions
diff --git a/man/man1/monkeysphere.1 b/man/man1/monkeysphere.1 index 9cdf0fc..07cd3ea 100644 --- a/man/man1/monkeysphere.1 +++ b/man/man1/monkeysphere.1 @@ -6,14 +6,14 @@ monkeysphere \- MonkeySphere client user interface .SH SYNOPSIS -.B monkeysphere \fIcommand\fP [\fIargs\fP] +.B monkeysphere \fIsubcommand\fP [\fIargs\fP] .SH DESCRIPTION -\fBMonkeySphere\fP is a system 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 ssh authorized_keys and known_hosts files to be used for -authentication of ssh connections. +to the authorized_keys and known_hosts files used by ssh for +connection authentication. \fBmonkeysphere\fP is the MonkeySphere client utility. @@ -23,59 +23,43 @@ authentication of ssh connections. .TP .B update-known_hosts [HOST]... Update the known_hosts file. For each specified host, gpg will be -queried for a key associated with the host URI (see HOST URIs), -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 known_hosts file. If the found key is acceptable (see -KEY ACCEPTABILITY), then the key will be updated and re-added to the -known_hosts file. If no gpg key is found for the host, then nothing -is done. If no hosts are specified, all hosts listed in the -known_hosts file will be processed. This command will exit with a -status of 0 if all host were found to be acceptable, 2 if all the -hosts were found to be unacceptable (ie. with keys removed from the -known_hosts file), and 1 otherwise. `k' may be used in place of -`update-known_hosts'. +queried for a key associated with the host URI (see HOST +IDENTIFICATION in monkeysphere(5)), optionally querying a keyserver. +If an acceptable key is found for the host (see KEY ACCEPTABILITY in +monkeysphere(5)), the key is added to the user's known_hosts file. If +a key is found but is unacceptable for the host, any matching keys are +removed from the user's known_hosts file. If no gpg key is found for +the host, nothing is done. If no hosts are specified, all hosts +listed in the known_hosts file will be processed. This subcommand +will exit with a status of 0 if at least one acceptable key was found +for a specified host, 1 if no matching keys were found at all, and 2 +if matching keys were found but none were acceptable. `k' may be used +in place of `update-known_hosts'. .TP .B update-authorized_keys Update the monkeysphere authorized_keys file. For each user ID in the user's authorized_user_ids file, 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. This command will exit -with a status of 0 if all user IDs were found to be acceptable, 2 if -all the user IDs were found to be unacceptable (ie. with keys removed -from the authorized_keys file), and 1 otherwise. `a' may be used in -place of `update-authorized_keys'. +associated with that user ID, optionally querying a keyserver. If an +acceptable key is found (see KEY ACCEPTABILITY in monkeysphere(5)), +the key is add to the user's authorized_keys file. If a key is found +but is unacceptable for the user ID, any matching keys are removed +from the user's authorized_keys file. If no gpg key is found for the +user ID, nothing is done. This subcommand will exit with a status of +0 if at least one acceptable key was found for a user ID, 1 if no +matching keys wer found at all, and 2 if matching keys were found but +none were acceptable. `a' may be used in place of +`update-authorized_keys'. .TP .B gen-subkey KEYID -Generate an `a` capable subkey. For the primary key with the +Generate an authentication subkey. For the primary key with the specified key ID, generate a subkey with "authentication" capability -that can be used for MonkeySphere transactions. `g' may be used in +that can be used for monkeysphere transactions. `g' may be used in place of `gen-subkey'. .TP .B help Output a brief usage summary. `h' or `?' may be used in place of `help'. -.SH HOST URIs - -Host OpenPGP keys have associated user IDs that use the ssh URI -specification for the host, ie. "ssh://host.full.domain[:port]". - -.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 @@ -91,11 +75,13 @@ addition to the authorized_keys file. .SH AUTHOR -Written by Jameson Rollins <jrollins@fifthhorseman.net> +Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel +Kahn Gillmor <dkg@fifthhorseman.net> .SH SEE ALSO .BR monkeysphere-ssh-proxycommand (1), .BR monkeysphere-server (8), +.BR monkeysphere (5), .BR ssh (1), .BR gpg (1) diff --git a/man/man1/openpgp2ssh.1 b/man/man1/openpgp2ssh.1 index 6141ec5..281bb0f 100644 --- a/man/man1/openpgp2ssh.1 +++ b/man/man1/openpgp2ssh.1 @@ -38,7 +38,7 @@ converted to the equivalent PEM-encoded private key. .Pp .Nm is part of the -.Xr monkeysphere 1 +.Xr monkeysphere 5 framework for providing a PKI for SSH. .Sh CAVEATS The keys produced by this process are stripped of all identifying @@ -91,5 +91,6 @@ passed in. If you send it more than one primary key, it will silently ignore later ones. .Sh SEE ALSO .Xr monkeysphere 1 , +.Xr monkeysphere 5 , .Xr ssh 1 , .Xr monkeysphere-server 8 diff --git a/man/man5/monkeysphere.5 b/man/man5/monkeysphere.5 new file mode 100644 index 0000000..50ad2b3 --- /dev/null +++ b/man/man5/monkeysphere.5 @@ -0,0 +1,54 @@ +.TH MONKEYSPHERE "5" "June 2008" "monkeysphere" "System Frameworks" + +.SH NAME + +monkeysphere \- ssh authentication framework using OpenPGP Web of +Trust + +.SH DESCRIPTION + +\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. + +.SH IDENTITY CERTIFIERS + +FIXME: describe identity certifier concept + +.SH KEY ACCEPTABILITY + +During known_host and authorized_keys updates, the monkeysphere +commands work from a set of user IDs to determine acceptable keys for +ssh authentication. OpenPGP 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 itself must be valid, i.e. it must be well-formed, not +expired, and not revoked. +.TP +.B certification +The relevant user ID must be signed by a trusted identity certifier. + +.SH HOST IDENTIFICATION + +The OpenPGP keys for hosts have associated user IDs that use the ssh +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> + +.SH SEE ALSO + +.BR monkeysphere (1), +.BR monkeysphere-server (8), +.BR monkeysphere-ssh-proxycommand (1), +.BR gpg (1), +.BR ssh (1), +.BR http://tools.ietf.org/html/rfc4880, +.BR http://tools.ietf.org/wg/secsh/draft-ietf-secsh-scp-sftp-ssh-uri/ diff --git a/man/man8/monkeysphere-server.8 b/man/man8/monkeysphere-server.8 index 1300d89..ba0c7b3 100644 --- a/man/man8/monkeysphere-server.8 +++ b/man/man8/monkeysphere-server.8 @@ -1,4 +1,4 @@ -.TH MONKEYSPHERE-SERVER "1" "June 2008" "monkeysphere 0.1" "User Commands" +.TH MONKEYSPHERE-SERVER "1" "June 2008" "monkeysphere" "User Commands" .SH NAME @@ -6,14 +6,14 @@ monkeysphere-server \- monkeysphere server admin user interface .SH SYNOPSIS -.B monkeysphere-server \fIcommand\fP [\fIargs\fP] +.B monkeysphere-server \fIsubcommand\fP [\fIargs\fP] .SH DESCRIPTION -\fBMonkeySphere\fP is a system 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 ssh authorized_keys and known_hosts files to be used for -authentication of ssh connections. +to the authorized_keys and known_hosts files used by ssh for +connection authentication. \fBmonkeysphere-server\fP is the MonkeySphere server admin utility. @@ -21,22 +21,19 @@ authentication of ssh connections. \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. +.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(5)), 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 gen-key Generate a OpenPGP key pair for the host. `g' may be used in place of @@ -50,21 +47,17 @@ Show the fingerprint for the host's OpenPGP key. `f' may be used in place of 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'. +.B add-identity-certifier KEYID +Instruct system to trust user identity certifications made by KEYID. +`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'. +.B remove-identity-certifier KEYID +Instruct system to ignore user identity certifications made by KEYID. +`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'. +.B list-identity-certifiers +List key IDs trusted by the system to certify user identities. `l' +may be used in place of `list-identity-certifiers'. .TP .B help Output a brief usage summary. `h' or `?' may be used in place of @@ -131,17 +124,6 @@ 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 @@ -166,10 +148,12 @@ Monkeysphere authentication GNUPG home directory. .SH AUTHOR -Written by Jameson Rollins <jrollins@fifthhorseman.net> +Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel Kahn +Gillmor <dkg@fifthhorseman.net> .SH SEE ALSO .BR monkeysphere (1), +.BR monkeysphere (5), .BR gpg (1), .BR ssh (1) @@ -85,7 +85,7 @@ remove_line() { # if the line is there are removed, return 0 if [ "$file" -a "$string" ] ; then - grep -v "$string" "$file" | sponge "$file" + grep -v -F "$string" "$file" | sponge "$file" return 0 # otherwise return 1 else |