git.distorted.org.uk Git - u/mdw/putty/blob - unix/puttygen.1

   1 .TH puttygen 1
   2 .UC
   3 .SH NAME
   4 puttygen \- public-key generator for the PuTTY tools
   5 .SH SYNOPSIS
   6 \fBputtygen\fP ( \fIkeyfile\fP | \-t \fIkeytype\fP [ \-b \fIbits\fP ] )
   7          [ \-C \fInew-comment\fP ] [ \-P ]
   8          [ \-O \fIoutput-type\fP | \-l | \-L | \-p ]
   9          [ \-o \fIoutput-file\fP ]
  10 .SH DESCRIPTION
  11 \fBputtygen\fP is a tool to generate and manipulate SSH public and
  12 private key pairs. It is part of the PuTTY suite, although it can
  13 also interoperate with the private key formats used by some other
  14 SSH clients.
  15
  16 When you run \fBputtygen\fP, it does three things. Firstly, it
  17 either loads an existing key file (if you specified \fIkeyfile\fP),
  18 or generates a new key (if you specified \fIkeytype\fP). Then, it
  19 optionally makes modifications to the key (changing the comment
  20 and/or the passphrase); finally, it outputs the key, or some
  21 information about the key, to a file.
  22
  23 All three of these phases are controlled by the options described in
  24 the following section.
  25 .SH OPTIONS
  26 In the first phase, \fBputtygen\fP either loads or generates a key.
  27 The options to control this are:
  28 .IP "\fIkeyfile\fP"
  29 Specify a private key file to be loaded. This private key file can
  30 be in the (de facto standard) SSH1 key format, or in PuTTY's SSH2
  31 key format, or in either of the SSH2 private key formats used by
  32 OpenSSH and ssh.com's implementation.
  33 .IP "\fB\-t\fP \fIkeytype\fP"
  34 Specify a type of key to generate. The acceptable values here are
  35 \fBrsa\fP and \fBdsa\fP (to generate SSH2 keys), and \fBrsa1\fP (to
  36 generate SSH1 keys).
  37 .IP "\fB\-b\fP \fIbits\fP"
  38 Specify the size of the key to generate, in bits. Default is 1024.
  39 .PP
  40 In the second phase, \fBputtygen\fP optionally alters properties of
  41 the key it has loaded or generated. The options to control this are:
  42 .IP "\fB\-C\fP \fInew\-comment\fP"
  43 Specify a comment string to describe the key. This comment string
  44 will be used by PuTTY to identify the key to you (when asking you to
  45 enter the passphrase, for example, so that you know which passphrase
  46 to type).
  47 .IP "\fB\-P\fP"
  48 Indicate that you want to change the key's passphrase. This is
  49 automatic when you are generating a new key, but not when you are
  50 modifying an existing key.
  51 .PP
  52 In the third phase, \fBputtygen\fP saves the key or information
  53 about it. The options to control this are:
  54 .IP "\fB\-O\fP \fIoutput\-type\fP"
  55 Specify the type of output you want \fBputtygen\fP to produce.
  56 Acceptable options are:
  57 .RS
  58 .IP "\fBprivate\fP"
  59 Save the private key in a format usable by PuTTY. This will either
  60 be the standard SSH1 key format, or PuTTY's own SSH2 key format.
  61 .IP "\fBpublic\fP"
  62 Save the public key only. For SSH1 keys, the standard public key
  63 format will be used ("1024 37 5698745...."). For SSH2 keys, the
  64 public key will be output in the format specified in the IETF
  65 drafts, which is a multi-line text file beginning with the line
  66 "---- BEGIN SSH2 PUBLIC KEY ----".
  67 .IP "\fBpublic-openssh\fP"
  68 Save the public key only, in a format usable by OpenSSH. For SSH1
  69 keys, this output format behaves identically to \fBpublic\fP. For
  70 SSH2 keys, the public key will be output in the OpenSSH format,
  71 which is a single line ("ssh-rsa AAAAB3NzaC1yc2...").
  72 .IP "\fBfingerprint\fP"
  73 Print the fingerprint of the public key. All fingerprinting
  74 algorithms are believed compatible with OpenSSH.
  75 .IP "\fBprivate-openssh\fP"
  76 Save an SSH2 private key in OpenSSH's format. This option is not
  77 permitted for SSH1 keys.
  78 .IP "\fBprivate-sshcom\fP"
  79 Save an SSH2 private key in ssh.com's format. This option is not
  80 permitted for SSH1 keys.
  81 .RE
  82 .IP
  83 If no output type is specified, the default is \fBprivate\fP.
  84 .IP "\fB\-o\fP \fIoutput\-file\fP"
  85 Specify the file where \fBputtygen\fP should write its output. If
  86 this option is not specified, \fBputtygen\fP will assume you want to
  87 overwrite the original file if the input and output file types are
  88 the same (changing a comment or passphrase), and will assume you
  89 want to output to stdout if you are asking for a public key or
  90 fingerprint. Otherwise, the \fB\-o\fP option is required.
  91 .IP "\fB\-l\fP"
  92 Synonym for "\fB-O fingerprint\fP".
  93 .IP "\fB\-L\fP"
  94 Synonym for "\fB-O public-openssh\fP".
  95 .IP "\fB\-p\fP"
  96 Synonym for "\fB-O public\fP".
  97 .SH EXAMPLES
  98 To generate an SSH2 RSA key pair and save it in PuTTY's own format
  99 (you will be prompted for the passphrase):
 100
 101 \fBputtygen -t rsa -C "my home key" -o mykey.ppk\fP
 102
 103 To generate a larger (2048-bit) key:
 104
 105 \fBputtygen -t rsa -b 2048 -C "my home key" -o mykey.ppk\fP
 106
 107 To change the passphrase on a key (you will be prompted for the old
 108 and new passphrases):
 109
 110 \fBputtygen -P mykey.ppk\fP
 111
 112 To change the comment on a key:
 113
 114 \fBputtygen -C "new comment" mykey.ppk\fP
 115
 116 To convert a key into OpenSSH's private key format:
 117
 118 \fBputtygen mykey.ppk -O private-openssh -o my-openssh-key\fP
 119
 120 To convert a key \fIfrom\fP another format (\fBputtygen\fP will
 121 automatically detect the input key type):
 122
 123 \fBputtygen my-ssh.com-key -o mykey.ppk\fP
 124
 125 To display the fingerprint of a key (some key types require a
 126 passphrase to extract even this much information):
 127
 128 \fBputtygen -l mykey.ppk\fP
 129
 130 To add the OpenSSH-format public half of a key to your authorised
 131 keys file:
 132
 133 \fBputtygen -L mykey.ppk >> $HOME/.ssh/authorized_keys\fP
 134
 135 .SH BUGS
 136 There's currently no way to supply passphrases in batch mode, or
 137 even just to specify that you don't want a passphrase at all.