.\" -*- nroff -*-
-.Dd $Mdocdate: June 11, 2008 $
+.Dd $Mdocdate: March 1, 2009 $
.Dt OPENPGP2SSH 1
.Os
.Sh NAME
.Nd translate OpenPGP keys to SSH keys
.Sh SYNOPSIS
.Nm openpgp2ssh < mykey.gpg
-
-.Nm gpg --export $KEYID | openpgp2ssh $KEYID
-
-.Nm gpg --export-secret-key $KEYID | openpgp2ssh $KEYID
+.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
-fingerprint as the first argument to indicate which key to export.
-The keyid must be at least 8 hex characters.
-
-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
+.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 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 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.
-
-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
-.Xr monkeysphere 1
+.Pp
+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 7
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
+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 .
-Tools (such as
-.Xr ssh 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
-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
+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.
-
-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.
.Sh SEE ALSO
-.Xr monkeysphere 1 ,
-.Xr monkeysphere-admin 8
+.Xr pem2openpgp 1 ,
+.Xr monkeysphere 1 ,
+.Xr monkeysphere 7 ,
+.Xr ssh 1 ,
+.Xr monkeysphere-authentication 8 ,
+.Xr monkeysphere-host 8