Merge commit 'dkg/master'

[monkeysphere.git] / man / man1 / monkeysphere.1

diff --git a/man/man1/monkeysphere.1 b/man/man1/monkeysphere.1
index f9a6af47537551551391ee064f9bdd54372c718b..30e35bba3a5fc7732b52bae70ee3b5935ba77ff6 100644 (file)
--- a/man/man1/monkeysphere.1
+++ b/man/man1/monkeysphere.1
@@ -1,52 +1,76 @@
 .TH MONKEYSPHERE "1" "June 2008" "monkeysphere 0.1" "User Commands"
 .TH MONKEYSPHERE "1" "June 2008" "monkeysphere 0.1" "User Commands"

+

 .SH NAME
 .SH NAME

-monkeysphere \- monkeysphere client user interface
+
+monkeysphere \- MonkeySphere client user interface
+

 .SH SYNOPSIS
 .SH SYNOPSIS

+

 .B monkeysphere \fIcommand\fP [\fIargs\fP]
 .B monkeysphere \fIcommand\fP [\fIargs\fP]

+

 .SH DESCRIPTION
 .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 of ssh connections.
+
+\fBmonkeysphere\fP is the MonkeySphere client utility.
+

 .SH SUBCOMMANDS
 .SH SUBCOMMANDS

+

 \fBmonkeysphere\fP takes various 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'.
+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.  `k' may be used in place of
+`update-known_hosts'.

 .TP
 .B update-authorized_keys
 .TP
 .B update-authorized_keys

-Update the authorized_keys file.
+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.  `a' may be used in place
+of `update-authorized_keys'.

 .TP
 .TP

-.B update-userids [USERID]...
-Update userid
-.TP
-.B gen-ae-subkey KEYID
-Generate an `ae` capable subkey
+.B gen-subkey KEYID
+Generate an `a` capable 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
+place of `gen-subkey'.

 .TP
 .B help
 Output a brief usage summary.  `h' or `?' may be used in place of
 `help'.
 .TP
 .B help
 Output a brief usage summary.  `h' or `?' may be used in place of
 `help'.

-.PD
+
+.SH HOST URIs
+
+Host OpenPGP keys have associated user IDs that use the ssh URI
+specification for the host, ie. "ssh://host.full.domain".
+

 .SH KEY ACCEPTABILITY
 .SH KEY ACCEPTABILITY

+

 GPG keys are considered acceptable if the following criteria are met:
 GPG keys are considered acceptable if the following criteria are met:

-.PD

 .TP
 .B capability
 .TP
 .B capability

-The key must have both the "authentication" and "encrypt" capability
-flags.
+The key must have the "authentication" ("a") usage flag set.

 .TP
 .B validity
 The key must be "fully" valid, and must not be expired or revoked.
 .TP
 .B validity
 The key must be "fully" valid, and must not be expired or revoked.

-.PD
+

 .SH FILES
 .SH FILES

-.PD 1
+

 .TP
 ~/.config/monkeysphere/monkeysphere.conf
 User monkeysphere config file.
 .TP
 ~/.config/monkeysphere/monkeysphere.conf
 User monkeysphere config file.


@@ -55,29 +79,16 @@ 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.
-.TP
-~/.config/monkeysphere/authorized_keys
-Monkeysphere generated authorized_keys file.
-.TP
-~/.config/monkeysphere/user_keys
-User keys cache directory.
-.TP
-~/.config/monkeysphere/host_keys
-Host keys cache directory.
-.PD
+OpenPGP user IDs associated with keys that will be checked for
+addition to the authorized_keys file.
+

 .SH AUTHOR
 .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-ssh-proxycommand (1),
+.BR monkeysphere-server (8),

 .BR ssh (1),
 .BR ssh (1),

-.BR gpg (1),
-.BR monkeysphere-server (8)
+.BR gpg (1)