X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=man%2Fman1%2Fopenpgp2ssh.1;h=bea1da50c4e1737fc30a7ba0ebee1aa8b163347f;hb=308aa104f66a40f2426c13b96f48631937502f6b;hp=cd79b6ccc5593dd191aa66f09d4a639d4f9f2768;hpb=f95803153b478e3ca3dd634c340355d7d582dcea;p=monkeysphere.git

diff --git a/man/man1/openpgp2ssh.1 b/man/man1/openpgp2ssh.1
index cd79b6c..bea1da5 100644
--- a/man/man1/openpgp2ssh.1
+++ b/man/man1/openpgp2ssh.1
@@ -7,59 +7,85 @@ openpgp2ssh
 .Nd translate OpenPGP keys to SSH keys
 .Sh SYNOPSIS
 .Nm openpgp2ssh < mykey.gpg 
-
+.Pp
 .Nm gpg --export $KEYID | openpgp2ssh $KEYID
-
+.Pp
 .Nm gpg --export-secret-key $KEYID | openpgp2ssh $KEYID
 .Sh DESCRIPTION
-openpgp2ssh takes OpenPGP-formatted RSA and DSA keys on standard
-input, and spits out the requested equivalent SSH-style key on
-standard output.
-
-If the data on standard input contains only a single key, you can
-invoke openpgp2ssh 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
+.Nm
+takes an OpenPGP-formatted primary key and associated
+subkeys on standard input, and spits out the requested equivalent
+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 at least 8 hex characters.
-
+The keyid must be exactly 16 hex characters.
+.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
 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.
-
-Note that the output keys from this process are stripped of all
-identifying information, including certifications, self-signatures,
-etc.
-
-openpgp2ssh is part of the
+.Pp
+.Nm
+is part of the
 .Xr monkeysphere 1
 framework for providing a PKI for SSH.
+.Sh CAVEATS
+The keys produced by this process are stripped of all identifying
+information, including certifications, self-signatures, etc.  This is
+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!
 .Sh EXAMPLES
 .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 . 
-Tools (such as 
-.Xr ssh 1 )
+Tools such as 
+.Xr ssh 1
 which know how to talk to the 
 .Xr ssh-agent 1
 can now rely on the key.
 .Sh AUTHOR
-openpgp2ssh and this man page were written by Daniel Kahn Gillmor
+.Nm
+and this man page were written by Daniel Kahn Gillmor
 <dkg@fifthhorseman.net>.
 .Sh BUGS
-openpgp2ssh currently only exports into formats used by the OpenSSH.
+.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).
-
+.Pp
 Secret key output is currently not passphrase-protected.
-
-This program is not yet implemented, and this man page currently only
-describes expected functionality.
+.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 monkeysphere 1 , 
-.Xr monkeysphere-admin 8
+.Xr monkeysphere 1 ,
+.Xr ssh 1 ,
+.Xr monkeysphere-server 8