Fix from Thomas Henlich for bug in dead key support. I've reproduced the

[u/mdw/putty] / unix / puttygen.1

.TH puttygen 1
.UC
.SH NAME
puttygen \- public-key generator for the PuTTY tools
.SH SYNOPSIS
\fBputtygen\fP ( \fIkeyfile\fP | \-t \fIkeytype\fP [ \-b \fIbits\fP ] )
         [ \-C \fInew-comment\fP ] [ \-P ]
         [ \-O \fIoutput-type\fP | \-l | \-L | \-p ]
         [ \-o \fIoutput-file\fP ]
.SH DESCRIPTION
\fBputtygen\fP is a tool to generate and manipulate SSH public and
private key pairs. It is part of the PuTTY suite, although it can
also interoperate with the private key formats used by some other
SSH clients.

When you run \fBputtygen\fP, it does three things. Firstly, it
either loads an existing key file (if you specified \fIkeyfile\fP),
or generates a new key (if you specified \fIkeytype\fP). Then, it
optionally makes modifications to the key (changing the comment
and/or the passphrase); finally, it outputs the key, or some
information about the key, to a file.

All three of these phases are controlled by the options described in
the following section.
.SH OPTIONS
In the first phase, \fBputtygen\fP either loads or generates a key.
The options to control this are:
.IP "\fIkeyfile\fP"
Specify a private key file to be loaded. This private key file can
be in the (de facto standard) SSH1 key format, or in PuTTY's SSH2
key format, or in either of the SSH2 private key formats used by
OpenSSH and ssh.com's implementation.
.IP "\fB\-t\fP \fIkeytype\fP"
Specify a type of key to generate. The acceptable values here are
\fBrsa\fP and \fBdsa\fP (to generate SSH2 keys), and \fBrsa1\fP (to
generate SSH1 keys).
.IP "\fB\-b\fP \fIbits\fP"
Specify the size of the key to generate, in bits. Default is 1024.
.PP
In the second phase, \fBputtygen\fP optionally alters properties of
the key it has loaded or generated. The options to control this are:
.IP "\fB\-C\fP \fInew\-comment\fP"
Specify a comment string to describe the key. This comment string
will be used by PuTTY to identify the key to you (when asking you to
enter the passphrase, for example, so that you know which passphrase
to type).
.IP "\fB\-P\fP"
Indicate that you want to change the key's passphrase. This is
automatic when you are generating a new key, but not when you are
modifying an existing key.
.PP
In the third phase, \fBputtygen\fP saves the key or information
about it. The options to control this are:
.IP "\fB\-O\fP \fIoutput\-type\fP"
Specify the type of output you want \fBputtygen\fP to produce.
Acceptable options are:
.RS
.IP "\fBprivate\fP"
Save the private key in a format usable by PuTTY. This will either
be the standard SSH1 key format, or PuTTY's own SSH2 key format.
.IP "\fBpublic\fP"
Save the public key only. For SSH1 keys, the standard public key
format will be used ("1024 37 5698745...."). For SSH2 keys, the
public key will be output in the format specified in the IETF
drafts, which is a multi-line text file beginning with the line
"---- BEGIN SSH2 PUBLIC KEY ----".
.IP "\fBpublic-openssh\fP"
Save the public key only, in a format usable by OpenSSH. For SSH1
keys, this output format behaves identically to \fBpublic\fP. For
SSH2 keys, the public key will be output in the OpenSSH format,
which is a single line ("ssh-rsa AAAAB3NzaC1yc2...").
.IP "\fBfingerprint\fP"
Print the fingerprint of the public key. All fingerprinting
algorithms are believed compatible with OpenSSH.
.IP "\fBprivate-openssh\fP"
Save an SSH2 private key in OpenSSH's format. This option is not
permitted for SSH1 keys.
.IP "\fBprivate-sshcom\fP"
Save an SSH2 private key in ssh.com's format. This option is not
permitted for SSH1 keys.
.RE
.IP
If no output type is specified, the default is \fBprivate\fP.
.IP "\fB\-o\fP \fIoutput\-file\fP"
Specify the file where \fBputtygen\fP should write its output. If
this option is not specified, \fBputtygen\fP will assume you want to
overwrite the original file if the input and output file types are
the same (changing a comment or passphrase), and will assume you
want to output to stdout if you are asking for a public key or
fingerprint. Otherwise, the \fB\-o\fP option is required.
.IP "\fB\-l\fP"
Synonym for "\fB-O fingerprint\fP".
.IP "\fB\-L\fP"
Synonym for "\fB-O public-openssh\fP".
.IP "\fB\-p\fP"
Synonym for "\fB-O public\fP".
.SH EXAMPLES
To generate an SSH2 RSA key pair and save it in PuTTY's own format
(you will be prompted for the passphrase):

\fBputtygen -t rsa -C "my home key" -o mykey.ppk\fP

To generate a larger (2048-bit) key:

\fBputtygen -t rsa -b 2048 -C "my home key" -o mykey.ppk\fP

To change the passphrase on a key (you will be prompted for the old
and new passphrases):

\fBputtygen -P mykey.ppk\fP

To change the comment on a key:

\fBputtygen -C "new comment" mykey.ppk\fP

To convert a key into OpenSSH's private key format:

\fBputtygen mykey.ppk -O private-openssh -o my-openssh-key\fP

To convert a key \fIfrom\fP another format (\fBputtygen\fP will
automatically detect the input key type):

\fBputtygen my-ssh.com-key -o mykey.ppk\fP

To display the fingerprint of a key (some key types require a
passphrase to extract even this much information):

\fBputtygen -l mykey.ppk\fP

To add the OpenSSH-format public half of a key to your authorised
keys file:

\fBputtygen -L mykey.ppk >> $HOME/.ssh/authorized_keys\fP

.SH BUGS
There's currently no way to supply passphrases in batch mode, or
even just to specify that you don't want a passphrase at all.