Man page work.
authorJameson Graef Rollins <jrollins@phys.columbia.edu>
Thu, 12 Jun 2008 04:22:02 +0000 (00:22 -0400)
committerJameson Graef Rollins <jrollins@phys.columbia.edu>
Thu, 12 Jun 2008 04:22:02 +0000 (00:22 -0400)
- flesh out more of the man pages for monkeysphere and monkeysphere-server
- move the server cache directory to /var/cache, where it should be.

debian/dirs
etc/monkeysphere-server.conf
man/man1/monkeysphere.1
man/man8/monkeysphere-server.8
src/common
src/monkeysphere
src/monkeysphere-server

index 277c0b572b6d346c7ec9af6881249529d5dc3c7a..bdf0fe0493caa1a493981746e097ac1c6ba10dc6 100644 (file)
@@ -1,5 +1,4 @@
-var/lib/monkeysphere
-var/lib/monkeysphere/stage
+var/cache/monkeysphere
 usr/bin
 usr/sbin
 usr/share
 usr/bin
 usr/sbin
 usr/share
index bed5c0905fb70b5e4146f2a47c48a4fd2847fa6a..3c16c5fe112690a3ec1f9d467d92ad300bf3a9c0 100644 (file)
@@ -18,6 +18,3 @@
 # monkeysphere-generated authorized_keys file.  Should be path to file
 # where '%h' will be substituted for the user's home directory.
 #USER_CONTROLLED_AUTHORIZED_KEYS=%h/.ssh/authorized_keys
 # monkeysphere-generated authorized_keys file.  Should be path to file
 # where '%h' will be substituted for the user's home directory.
 #USER_CONTROLLED_AUTHORIZED_KEYS=%h/.ssh/authorized_keys
-
-# where to cache user authorized_keys lines
-#STAGING_AREA=/var/lib/monkeysphere/stage
index f9a6af47537551551391ee064f9bdd54372c718b..410a5d7d4745d6e20f2f91086ce5a5ed66867e16 100644 (file)
@@ -1,34 +1,53 @@
 .TH MONKEYSPHERE "1" "June 2008" "monkeysphere 0.1" "User Commands"
 .SH NAME
 .TH MONKEYSPHERE "1" "June 2008" "monkeysphere 0.1" "User Commands"
 .SH NAME
-monkeysphere \- monkeysphere client user interface
+monkeysphere \- MonkeySphere client user interface
 .SH SYNOPSIS
 .B monkeysphere \fIcommand\fP [\fIargs\fP]
 .SH DESCRIPTION
 .PP
 .SH SYNOPSIS
 .B monkeysphere \fIcommand\fP [\fIargs\fP]
 .SH DESCRIPTION
 .PP
-\fBmonkeysphere\fP is the client monkeysphere tool.
+MonkeySphere is a system to leverage the OpenPGP Web of Trust for ssh
+authentication and encryption.  OpenPGP keys are tracked via GnuPG,
+and added to the ssh authorized_keys and known_hosts files to be used
+for authentication and encryption of ssh connection.
+
+\fBmonkeysphere\fP is the MonkeySphere client utility.
+.PD
 .SH SUBCOMMANDS
 \fBmonkeysphere\fP takes various subcommands:
 .SH SUBCOMMANDS
 \fBmonkeysphere\fP takes various subcommands:
-.PD
 .TP
 .B update-known_hosts [HOST]...
 .TP
 .B update-known_hosts [HOST]...
-Update the known_hosts file.  For every host listed, search for a gpg
-key for the host in the Web of Trust.  If a key is found, any ssh keys
-for the host are removed from the known_hosts file.  If the found key
-is acceptable (see KEY ACCEPTABILITY), then the gpg key is converted
-to an ssh key and 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.  If they
-
-`k' may be used in place of `update-known_hosts'.
-.TP
-.B update-authorized_keys
-Update the authorized_keys file.
+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 none is found in the user's keychain. search
+for a gpg key for the host in the Web of Trust.  If a key is found, it
+will be added to the host_keys cache (see KEY CACHES) and any ssh keys
+for the host will be removed from the user's known_hosts file.  If the
+found key is acceptable (see KEY ACCEPTABILITY), then the host's gpg
+key will be 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.  `k' may be used in
+place of `update-known_hosts'.
 .TP
 .B update-userids [USERID]...
 .TP
 .B update-userids [USERID]...
-Update userid
+Add/update a userid in the authorized_user_ids file.  The user IDs
+specified should be exact matches to OpenPGP user IDs.  For each
+specified user ID, gpg will be queried for a key associated with that
+user ID, querying a keyserver if none is found in the user's keychain.
+If a key is found, it will be added to the user_keys cache (see KEY
+CACHES) and the user ID will be added to the user's
+authorized_user_ids file (if it wasn't already present).
+.TP
+.B update-authorized_keys
+Update the monkeysphere authorized_keys file.  The monkeysphere
+authorized_keys file will be regenerated from the valid keys in the
+user_key cache, and the user's independently controlled
+authorized_keys file (usually ~/.ssh/authorized_keys).
 .TP
 .B gen-ae-subkey KEYID
 .TP
 .B gen-ae-subkey KEYID
-Generate an `ae` capable subkey
+Generate an `ae` capable subkey.  For the primary key with the
+specified key ID, generate a subkey with "authentication" and
+"encryption" capability that can be used for MonkeySphere
+transactions.
 .TP
 .B help
 Output a brief usage summary.  `h' or `?' may be used in place of
 .TP
 .B help
 Output a brief usage summary.  `h' or `?' may be used in place of
@@ -45,6 +64,20 @@ flags.
 .B validity
 The key must be "fully" valid, and must not be expired or revoked.
 .PD
 .B validity
 The key must be "fully" valid, and must not be expired or revoked.
 .PD
+.SH KEY CACHES
+Monkeysphere keeps track of keys in key cache directories.  The files
+in the cache are named with the format "USERID_HASH.PUB_KEY_ID", where
+USERID_HASH is a hash of the exact OpenPGP user ID, and PUB_KEY_ID is
+the key ID of the primary key.  If the user/key ID combo exists in the
+Web of Trust but is not acceptable, then the file is empty.  If the
+primary key has at least one acceptable sub key, then an ssh-style
+key, converted from the OpenPGP key, of all acceptable subkeys will be
+stored in the cache file, one per line.  known_hosts style key lines
+will be stored in the host_keys cache files, and authorized_keys style
+key lines will be stored in the user_keys cache files.  OpenPGP keys
+are converted to ssh-style keys with the openpgp2ssh utility (see `man
+openpgp2ssh').
+.PD
 .SH FILES
 .PD 1
 .TP
 .SH FILES
 .PD 1
 .TP
@@ -55,7 +88,8 @@ User monkeysphere config file.
 System-wide monkeysphere config file.
 .TP
 ~/.config/monkeysphere/authorized_user_ids
 System-wide monkeysphere config file.
 .TP
 ~/.config/monkeysphere/authorized_user_ids
-GPG user IDs to validate for addition to the authorized_keys file.
+GPG user IDs associated with keys that will be checked for addition to
+the authorized_keys file. 
 .TP
 ~/.config/monkeysphere/authorized_keys
 Monkeysphere generated authorized_keys file.
 .TP
 ~/.config/monkeysphere/authorized_keys
 Monkeysphere generated authorized_keys file.
@@ -67,17 +101,8 @@ User keys cache directory.
 Host keys cache directory.
 .PD
 .SH AUTHOR
 Host keys cache directory.
 .PD
 .SH AUTHOR
-Written by Jameson Rollins
-.SH "REPORTING BUGS"
-Report bugs to <???@???>.
-.SH COPYRIGHT
-Copyright \(co 2008 Jameson Graef Rollins and Daniel Kahn Gillmor
-.br
-This is free software.  You may redistribute copies of it under the
-terms of the GNU General Public License
-<http://www.gnu.org/licenses/gpl.html>.  There is NO WARRANTY, to the
-extent permitted by law.
-.SH "SEE ALSO"
+Written by Jameson Rollins <jrollins@fifthhorseman.net>
+.SH SEE ALSO
 .BR ssh (1),
 .BR gpg (1),
 .BR monkeysphere-server (8)
 .BR ssh (1),
 .BR gpg (1),
 .BR monkeysphere-server (8)
index 7a12e17591a0b44200e8503ae22ec3607fb87c99..cc07077cea47e5f8ad38609013a748d39ad8cc5e 100644 (file)
@@ -5,20 +5,32 @@ monkeysphere-server \- monkeysphere server admin user interface
 .B monkeysphere-server \fIcommand\fP [\fIargs\fP]
 .SH DESCRIPTION
 .PP
 .B monkeysphere-server \fIcommand\fP [\fIargs\fP]
 .SH DESCRIPTION
 .PP
-\fBmonkeysphere-server\fP is the server admin monkeysphere tool.
+\fBMonkeySphere\fP is a system to leverage the OpenPGP Web of Trust
+for ssh authentication and encryption.  OpenPGP keys are tracked via
+GnuPG, and added to the ssh authorized_keys and known_hosts files to
+be used for authentication and encryption of ssh connection.
+
+\fBmonkeysphere-server\fP is the MonkeySphere server admin utility.
+.PD
 .SH SUBCOMMANDS
 \fBmonkeysphere-server\fP takes various subcommands:
 .SH SUBCOMMANDS
 \fBmonkeysphere-server\fP takes various subcommands:
-.PD
 .TP
 .TP
-.B update-users [HOST]...
+.B update-users [USER]...
+Update the admin-controlled authorized_keys files for user.  For each
+user specified, update the user's authorized_keys file in
+/var/cache/monkeysphere/USER.  See `man monkeysphere' for more info.
 .TP
 .B gen-key
 .TP
 .B gen-key
+Generate a gpg key for the host.
 .TP
 .B publish-key
 .TP
 .B publish-key
+Publish the host's gpg key to a keyserver.
 .TP
 .B trust-keys KEYID...
 .TP
 .B trust-keys KEYID...
+Mark key specified with KEYID with full owner trust.
 .TP
 .B update-user-userids USER USERID...
 .TP
 .B update-user-userids USER USERID...
+Add/update a userid in the authorized_user_ids file for USER.
 .TP
 .B help
 Output a brief usage summary.  `h' or `?' may be used in place of
 .TP
 .B help
 Output a brief usage summary.  `h' or `?' may be used in place of
@@ -39,21 +51,12 @@ Monkeysphere GNUPG home directory.
 /etc/monkeysphere/authorized_user_ids/USER
 Server maintained authorized_user_ids files for users.
 .TP
 /etc/monkeysphere/authorized_user_ids/USER
 Server maintained authorized_user_ids files for users.
 .TP
-/var/lib/monkeysphere/stage/USER
-Staging directory for user key caches.
+/var/cachemonkeysphere/USER
+User keys cache directories.
 .PD
 .SH AUTHOR
 .PD
 .SH AUTHOR
-Written by Jameson Rollins
-.SH "REPORTING BUGS"
-Report bugs to <???@???>.
-.SH COPYRIGHT
-Copyright \(co 2008 Jameson Graef Rollins and Daniel Kahn Gillmor
-.br
-This is free software.  You may redistribute copies of it under the
-terms of the GNU General Public License
-<http://www.gnu.org/licenses/gpl.html>.  There is NO WARRANTY, to the
-extent permitted by law.
-.SH "SEE ALSO"
+Written by Jameson Rollins <jrollins@fifthhorseman.net>
+.SH SEE ALSO
 .BR monkeysphere (1),
 .BR gpg (1),
 .BR ssh (1)
 .BR monkeysphere (1),
 .BR gpg (1),
 .BR ssh (1)
index d7caefdfd3dd50fddae5d0c0fdd53f5187cb6e8e..914c800a24d6d3471fc2f2eaaa477a47d085b5d2 100755 (executable)
@@ -14,8 +14,8 @@
 # managed directories
 ETC="/etc/monkeysphere"
 export ETC
 # managed directories
 ETC="/etc/monkeysphere"
 export ETC
-LIB="/var/lib/monkeysphere"
-export LIB 
+CACHE="/var/cache/monkeysphere"
+export CACHE
 ########################################################################
 
 failure() {
 ########################################################################
 
 failure() {
@@ -312,13 +312,13 @@ process_known_hosts() {
 # update an authorized_keys file after first processing the 
 # authorized_user_ids file
 update_authorized_keys() {
 # update an authorized_keys file after first processing the 
 # authorized_user_ids file
 update_authorized_keys() {
-    local cacheDir
     local msAuthorizedKeys
     local userAuthorizedKeys
     local msAuthorizedKeys
     local userAuthorizedKeys
+    local cacheDir
 
 
-    cacheDir="$1"
-    msAuthorizedKeys="$2"
-    userAuthorizedKeys="$3"
+    msAuthorizedKeys="$1"
+    userAuthorizedKeys="$2"
+    cacheDir="$3"
 
     process_authorized_ids "$AUTHORIZED_USER_IDS" "$cacheDir"
 
 
     process_authorized_ids "$AUTHORIZED_USER_IDS" "$cacheDir"
 
index aaeda117a0efd54d6a8ae7dcf4089fa7fe37fed8..5d865c96a3a7a747aa7054213500149baaec3ca4 100755 (executable)
@@ -35,8 +35,8 @@ Monkeysphere client tool.
 
 subcommands:
   update-known_hosts (k) [HOST]...  update known_hosts file
 
 subcommands:
   update-known_hosts (k) [HOST]...  update known_hosts file
-  update-authorized_keys (a)        update authorized_keys file
   update-userids (u) [USERID]...    add/update userid
   update-userids (u) [USERID]...    add/update userid
+  update-authorized_keys (a)        update authorized_keys file
   gen-ae-subkey (g) KEYID           generate an 'ae' capable subkey
   help (h,?)                        this help
 
   gen-ae-subkey (g) KEYID           generate an 'ae' capable subkey
   help (h,?)                        this help
 
@@ -170,7 +170,7 @@ case $COMMAND in
        userAuthorizedKeys=${USER_CONTROLLED_AUTHORIZED_KEYS/\%h/"$HOME"}
 
        # update authorized_keys
        userAuthorizedKeys=${USER_CONTROLLED_AUTHORIZED_KEYS/\%h/"$HOME"}
 
        # update authorized_keys
-       update_authorized_keys "$userKeysCacheDir" "$msAuthorizedKeys" "$userAuthorizedKeys"
+       update_authorized_keys "$msAuthorizedKeys" "$userAuthorizedKeys" "$userKeysCacheDir"
        ;;
 
     'update-userids'|'u')
        ;;
 
     'update-userids'|'u')
index a109cf533229c78074e1fe543e37569b49618321..0ff06af5b261d67b0c3b011faef74f3687ff4b4c 100755 (executable)
@@ -129,7 +129,6 @@ GNUPGHOME=${GNUPGHOME:-"$MS_HOME"/gnupg}
 KEYSERVER=${KEYSERVER:-subkeys.pgp.net}
 REQUIRED_KEY_CAPABILITY=${REQUIRED_KEY_CAPABILITY:-"e a"}
 USER_CONTROLLED_AUTHORIZED_KEYS=${USER_CONTROLLED_AUTHORIZED_KEYS:-%h/.ssh/authorized_keys}
 KEYSERVER=${KEYSERVER:-subkeys.pgp.net}
 REQUIRED_KEY_CAPABILITY=${REQUIRED_KEY_CAPABILITY:-"e a"}
 USER_CONTROLLED_AUTHORIZED_KEYS=${USER_CONTROLLED_AUTHORIZED_KEYS:-%h/.ssh/authorized_keys}
-STAGING_AREA=${STAGING_AREA:-"$LIB"/stage}
 
 export GNUPGHOME
 
 
 export GNUPGHOME
 
@@ -150,8 +149,8 @@ case $COMMAND in
            log "----- user: $uname -----"
 
            AUTHORIZED_USER_IDS="$MS_HOME"/authorized_user_ids/"$uname"
            log "----- user: $uname -----"
 
            AUTHORIZED_USER_IDS="$MS_HOME"/authorized_user_ids/"$uname"
-           cacheDir="$STAGING_AREA"/"$uname"/user_keys
-           msAuthorizedKeys="$STAGING_AREA"/"$uname"/authorized_keys
+           msAuthorizedKeys="$CACHE"/"$uname"/authorized_keys
+           cacheDir="$CACHE"/"$uname"/user_keys
 
             # make sure authorized_user_ids file exists
            if [ ! -s "$AUTHORIZED_USER_IDS" ] ; then
 
             # make sure authorized_user_ids file exists
            if [ ! -s "$AUTHORIZED_USER_IDS" ] ; then
@@ -166,7 +165,7 @@ case $COMMAND in
            fi
 
            # update authorized_keys
            fi
 
            # update authorized_keys
-           update_authorized_keys "$cacheDir" "$msAuthorizedKeys" "$userAuthorizedKeys"
+           update_authorized_keys "$msAuthorizedKeys" "$userAuthorizedKeys" "$cacheDir"
        done
 
        log "----- done. -----"
        done
 
        log "----- done. -----"
@@ -199,9 +198,9 @@ case $COMMAND in
            failure "you must specify at least one userid."
        fi
        AUTHORIZED_USER_IDS="$MS_HOME"/authorized_user_ids/"$uname"
            failure "you must specify at least one userid."
        fi
        AUTHORIZED_USER_IDS="$MS_HOME"/authorized_user_ids/"$uname"
-       userKeysCacheDir="$STAGING_AREA"/"$uname"/user_keys
+       cacheDir="$CACHE"/"$uname"/user_keys
        for userID ; do
        for userID ; do
-           update_userid "$userID" "$userKeysCacheDir"
+           update_userid "$userID" "$cacheDir"
        done
        ;;
 
        done
        ;;