Merge remote branch 'dkg/master'

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

diff --git a/man/man1/openpgp2ssh.1 b/man/man1/openpgp2ssh.1
index 62671419488d7129b519a849e8d974385240a6c9..304a442577b3f60e3765737b999a8d87688bda8c 100644 (file)
--- a/man/man1/openpgp2ssh.1
+++ b/man/man1/openpgp2ssh.1
@@ -1,5 +1,5 @@
 .\"  -*- nroff -*-
 .\"  -*- nroff -*-

-.Dd $Mdocdate: June 11, 2008 $
+.Dd $Mdocdate: March 1, 2009 $

 .Dt OPENPGP2SSH 1
 .Os
 .Sh NAME
 .Dt OPENPGP2SSH 1
 .Os
 .Sh NAME


@@ -7,60 +7,88 @@ openpgp2ssh
 .Nd translate OpenPGP keys to SSH keys
 .Sh SYNOPSIS
 .Nm openpgp2ssh < mykey.gpg 
 .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
 .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.
 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 keys produced by 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.
 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
 .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
 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 
 which know how to talk to the 

-.Xr ssh-agent 1
+.Xr ssh\-agent 1

 can now rely on the key.
 .Sh AUTHOR
 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
 <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
 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.
 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
 .Sh SEE ALSO

+.Xr pem2openpgp 1 ,

 .Xr monkeysphere 1 ,
 .Xr monkeysphere 1 ,

+.Xr monkeysphere 7 ,

 .Xr ssh 1 ,
 .Xr ssh 1 ,

-.Xr monkeysphere-server 8
+.Xr monkeysphere-authentication 8 ,
+.Xr monkeysphere-host 8