some improvements to man pages

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

diff --git a/man/man1/openpgp2ssh.1 b/man/man1/openpgp2ssh.1
index bea1da50c4e1737fc30a7ba0ebee1aa8b163347f..304a442577b3f60e3765737b999a8d87688bda8c 100644 (file)
--- a/man/man1/openpgp2ssh.1
+++ b/man/man1/openpgp2ssh.1
@@ -1,5 +1,5 @@
 .\"  -*- nroff -*-
-.Dd $Mdocdate: June 11, 2008 $
+.Dd $Mdocdate: March 1, 2009 $
 .Dt OPENPGP2SSH 1
 .Os
 .Sh NAME
@@ -8,9 +8,9 @@ openpgp2ssh
 .Sh SYNOPSIS
 .Nm openpgp2ssh < mykey.gpg 
 .Pp
-.Nm gpg --export $KEYID | openpgp2ssh $KEYID
+.Nm gpg \-\-export $KEYID | openpgp2ssh $KEYID
 .Pp
-.Nm gpg --export-secret-key $KEYID | openpgp2ssh $KEYID
+.Nm gpg \-\-export\-secret\-key $KEYID | openpgp2ssh $KEYID
 .Sh DESCRIPTION
 .Nm
 takes an OpenPGP-formatted primary key and associated
@@ -19,23 +19,26 @@ SSH-style key on standard output.
 .Pp
 If the data on standard input contains no subkeys, you can invoke
 .Nm
-without arguments.  If the data on standard input contains
-multiple keys (e.g. a primary key and associated subkeys), you must
-specify a specific OpenPGP keyid (e.g. CCD2ED94D21739E9) or
-fingerprint as the first argument to indicate which key to export.
-The keyid must be exactly 16 hex characters.
+without arguments.  If the data on standard input contains multiple
+keys (e.g. a primary key and associated subkeys), you must specify a
+specific OpenPGP key identifier as the first argument to indicate
+which key to export.  The key ID is normally the 40 hex digit OpenPGP
+fingerprint of the key or subkey desired, but
+.Nm
+will accept as few as the last 8 digits of the fingerprint as a key
+ID.
 .Pp
-If the input contains an OpenPGP RSA or DSA public key, it will be
-converted to the OpenSSH-style single-line keystring, prefixed with
-the key type.  This format is suitable (with minor alterations) for
+If the input contains an OpenPGP RSA public key, it will be converted
+to the OpenSSH-style single-line keystring, prefixed with the key type
+(`ssh\-rsa').  This format is suitable (with minor alterations) for
 insertion into known_hosts files and authorized_keys files.
 .Pp
-If the input contains an OpenPGP RSA or DSA secret key, it will be
-converted to the equivalent PEM-encoded private key.
+If the input contains an OpenPGP RSA secret key, it will be converted
+to the equivalent PEM-encoded private key.
 .Pp
 .Nm
 is part of the
-.Xr monkeysphere 1
+.Xr monkeysphere 7
 framework for providing a PKI for SSH.
 .Sh CAVEATS
 The keys produced by this process are stripped of all identifying
@@ -44,24 +47,19 @@ intentional, since ssh attaches no inherent significance to these
 features.
 .Pp
 .Nm
-only works with RSA or DSA keys, because those are the
-only ones which work with ssh.
-.Pp
-Assuming a valid key type, though, 
-.Nm
-will produce output for
-any requested key.  This means, among other things, that it will
-happily export revoked keys, unverifiable keys, expired keys, etc.
-Make sure you do your own key validation before using this tool!
+will produce output for any requested RSA key.  This means, among
+other things, that it will happily export revoked keys, unverifiable
+keys, expired keys, etc.  Make sure you do your own key validation
+before using this tool!
 .Sh EXAMPLES
-.Nm gpg --export-secret-key $KEYID | openpgp2ssh $KEYID | ssh-add -c /dev/stdin
+.Nm gpg \-\-export\-secret\-key $KEYID | openpgp2ssh $KEYID | ssh\-add \-c /dev/stdin
 .Pp
 This pushes the secret key into the active
-.Xr ssh-agent 1 . 
+.Xr ssh\-agent 1 . 
 Tools such as 
 .Xr ssh 1
 which know how to talk to the 
-.Xr ssh-agent 1
+.Xr ssh\-agent 1
 can now rely on the key.
 .Sh AUTHOR
 .Nm
@@ -69,23 +67,28 @@ and this man page were written by Daniel Kahn Gillmor
 <dkg@fifthhorseman.net>.
 .Sh BUGS
 .Nm
+only works with RSA keys.  DSA keys are the only other key type
+available in both OpenPGP and SSH, but they are currently unsupported
+by this utility.
+.Pp
+.Nm
+only accepts raw OpenPGP packets on standard input.  It does not
+accept ASCII-armored input.
+.Nm
 Currently only exports into formats used by the OpenSSH.
 It should support other key output formats, such as those used by
-lsh(1) and putty(1).
+.Xr lsh 1
+and
+.Xr putty 1 .
 .Pp
 Secret key output is currently not passphrase-protected.
 .Pp
 .Nm
 currently cannot handle passphrase-protected secret keys on input.
-.Pp
-It would be nice to be able to use keyids shorter or longer than 16
-hex characters.
-.Pp
-.Nm
-only acts on keys associated with the first primary key
-passed in.  If you send it more than one primary key, it will silently
-ignore later ones.
 .Sh SEE ALSO
+.Xr pem2openpgp 1 ,
 .Xr monkeysphere 1 ,
+.Xr monkeysphere 7 ,
 .Xr ssh 1 ,
-.Xr monkeysphere-server 8
+.Xr monkeysphere-authentication 8 ,
+.Xr monkeysphere-host 8