doc/man-pg.but

   1 \cfg{man-identity}{puttygen}{1}{2004-03-24}{PuTTY tool suite}{PuTTY tool suite}
   2
   3 \H{puttygen-manpage} Man page for PuTTYgen
   4
   5 \S{puttygen-manpage-name} NAME
   6
   7 \cw{puttygen} - public-key generator for the PuTTY tools
   8
   9 \S{puttygen-manpage-synopsis} SYNOPSIS
  10
  11 \c puttygen ( keyfile | -t keytype [ -b bits ] )
  12 \e bbbbbbbb   iiiiiii   bb iiiiiii   bb iiii
  13 \c          [ -C new-comment ] [ -P ] [ -q ]
  14 \e            bb iiiiiiiiiii     bb     bb
  15 \c          [ -O output-type | -l | -L | -p ]
  16 \e            bb iiiiiiiiiii   bb   bb   bb
  17 \c          [ -o output-file ]
  18 \e            bb iiiiiiiiiii
  19
  20 \S{puttygen-manpage-description} DESCRIPTION
  21
  22 \c{puttygen} is a tool to generate and manipulate SSH public and
  23 private key pairs. It is part of the PuTTY suite, although it can
  24 also interoperate with the key formats used by some other SSH clients.
  25
  26 When you run \c{puttygen}, it does three things. Firstly, it either
  27 loads an existing key file (if you specified \e{keyfile}), or
  28 generates a new key (if you specified \e{keytype}). Then, it
  29 optionally makes modifications to the key (changing the comment
  30 and/or the passphrase); finally, it outputs the key, or some
  31 information about the key, to a file.
  32
  33 All three of these phases are controlled by the options described in
  34 the following section.
  35
  36 \S{puttygen-manpage-options} OPTIONS
  37
  38 In the first phase, \c{puttygen} either loads or generates a key.
  39 Note that generating a key requires random data, which can cause
  40 \c{puttygen} to pause, possibly for some time if your system does
  41 not have much randomness available.
  42
  43 The options to control this phase are:
  44
  45 \dt \e{keyfile}
  46
  47 \dd Specify a key file to be loaded.
  48
  49 \lcont{
  50
  51 Usually this will be a private key, which can be in the (de facto
  52 standard) SSH-1 key format, or in PuTTY's SSH-2 key format, or in
  53 either of the SSH-2 private key formats used by OpenSSH and
  54 ssh.com's implementation.
  55
  56 You can also specify a file containing only a \e{public} key here.
  57 The operations you can do are limited to outputting another public
  58 key format or a fingerprint. Public keys can be in RFC 4716 or
  59 OpenSSH format, or the standard SSH-1 format.
  60
  61 }
  62
  63 \dt \cw{\-t} \e{keytype}
  64
  65 \dd Specify a type of key to generate. The acceptable values here are
  66 \c{rsa}, \c{dsa}, \c{ecdsa}, and \c{ed25519} (to generate SSH-2 keys),
  67 and \c{rsa1} (to generate SSH-1 keys).
  68
  69 \dt \cw{\-b} \e{bits}
  70
  71 \dd Specify the size of the key to generate, in bits. Default is 2048.
  72
  73 \dt \cw{\-q}
  74
  75 \dd Suppress the progress display when generating a new key.
  76
  77 \dt \cw{\-\-old\-passphrase} \e{file}
  78
  79 \dd Specify a file name; the first line will be read from this file
  80 (removing any trailing newline) and used as the old passphrase.
  81 \s{CAUTION:} If the passphrase is important, the file should be stored
  82 on a temporary filesystem or else securely erased after use.
  83
  84 \dt \cw{\-\-random\-device} \e{device}
  85
  86 \dd Specify device to read entropy from (default \c{/dev/random}).
  87
  88 In the second phase, \c{puttygen} optionally alters properties of
  89 the key it has loaded or generated. The options to control this are:
  90
  91 \dt \cw{\-C} \e{new\-comment}
  92
  93 \dd Specify a comment string to describe the key. This comment string
  94 will be used by PuTTY to identify the key to you (when asking you to
  95 enter the passphrase, for example, so that you know which passphrase
  96 to type).
  97
  98 \dt \cw{\-P}
  99
 100 \dd Indicate that you want to change the key's passphrase. This is
 101 automatic when you are generating a new key, but not when you are
 102 modifying an existing key.
 103
 104 In the third phase, \c{puttygen} saves the key or information
 105 about it. The options to control this are:
 106
 107 \dt \cw{\-O} \e{output\-type}
 108
 109 \dd Specify the type of output you want \c{puttygen} to produce.
 110 Acceptable options are:
 111
 112 \lcont{
 113
 114 \dt \cw{private}
 115
 116 \dd Save the private key in a format usable by PuTTY. This will either
 117 be the standard SSH-1 key format, or PuTTY's own SSH-2 key format.
 118
 119 \dt \cw{public}
 120
 121 \dd Save the public key only. For SSH-1 keys, the standard public key
 122 format will be used (\q{\cw{1024 37 5698745}...}). For SSH-2 keys, the
 123 public key will be output in the format specified by RFC 4716,
 124 which is a multi-line text file beginning with the line
 125 \q{\cw{---- BEGIN SSH2 PUBLIC KEY ----}}.
 126
 127 \dt \cw{public-openssh}
 128
 129 \dd Save the public key only, in a format usable by OpenSSH. For SSH-1
 130 keys, this output format behaves identically to \c{public}. For
 131 SSH-2 keys, the public key will be output in the OpenSSH format,
 132 which is a single line (\q{\cw{ssh-rsa AAAAB3NzaC1yc2}...}).
 133
 134 \dt \cw{fingerprint}
 135
 136 \dd Print the fingerprint of the public key. All fingerprinting
 137 algorithms are believed compatible with OpenSSH.
 138
 139 \dt \cw{private-openssh}
 140
 141 \dd Save an SSH-2 private key in OpenSSH's format, using the oldest
 142 format available to maximise backward compatibility. This option is not
 143 permitted for SSH-1 keys.
 144
 145 \dt \cw{private-openssh-new}
 146
 147 \dd As \c{private-openssh}, except that it forces the use of OpenSSH's
 148 newer format even for RSA, DSA, and ECDSA keys.
 149
 150 \dt \cw{private-sshcom}
 151
 152 \dd Save an SSH-2 private key in ssh.com's format. This option is not
 153 permitted for SSH-1 keys.
 154
 155 If no output type is specified, the default is \c{private}.
 156
 157 }
 158
 159 \dt \cw{\-o} \e{output\-file}
 160
 161 \dd Specify the file where \c{puttygen} should write its output. If
 162 this option is not specified, \c{puttygen} will assume you want to
 163 overwrite the original file if the input and output file types are
 164 the same (changing a comment or passphrase), and will assume you
 165 want to output to stdout if you are asking for a public key or
 166 fingerprint. Otherwise, the \c{\-o} option is required.
 167
 168 \dt \cw{\-l}
 169
 170 \dd Synonym for \q{\cw{-O fingerprint}}.
 171
 172 \dt \cw{\-L}
 173
 174 \dd Synonym for \q{\cw{-O public-openssh}}.
 175
 176 \dt \cw{\-p}
 177
 178 \dd Synonym for \q{\cw{-O public}}.
 179
 180 \dt \cw{\-\-new\-passphrase} \e{file}
 181
 182 \dd Specify a file name; the first line will be read from this file
 183 (removing any trailing newline) and used as the new passphrase. If the
 184 file is empty then the saved key will be unencrypted. \s{CAUTION:} If
 185 the passphrase is important, the file should be stored on a temporary
 186 filesystem or else securely erased after use.
 187
 188 The following options do not run PuTTYgen as normal, but print
 189 informational messages and then quit:
 190
 191 \dt \cw{\-h}, \cw{\-\-help}
 192
 193 \dd Display a message summarizing the available options.
 194
 195 \dt \cw{\-V}, \cw{\-\-version}
 196
 197 \dd Display the version of PuTTYgen.
 198
 199 \dt \cw{\-\-pgpfp}
 200
 201 \dd Display the fingerprints of the PuTTY PGP Master Keys, to aid
 202 in verifying new files released by the PuTTY team.
 203
 204 \S{puttygen-manpage-examples} EXAMPLES
 205
 206 To generate an SSH-2 RSA key pair and save it in PuTTY's own format
 207 (you will be prompted for the passphrase):
 208
 209 \c puttygen -t rsa -C "my home key" -o mykey.ppk
 210
 211 To generate a larger (4096-bit) key:
 212
 213 \c puttygen -t rsa -b 4096 -C "my home key" -o mykey.ppk
 214
 215 To change the passphrase on a key (you will be prompted for the old
 216 and new passphrases):
 217
 218 \c puttygen -P mykey.ppk
 219
 220 To change the comment on a key:
 221
 222 \c puttygen -C "new comment" mykey.ppk
 223
 224 To convert a key into OpenSSH's private key format:
 225
 226 \c puttygen mykey.ppk -O private-openssh -o my-openssh-key
 227
 228 To convert a key \e{from} another format (\c{puttygen} will
 229 automatically detect the input key type):
 230
 231 \c puttygen my-ssh.com-key -o mykey.ppk
 232
 233 To display the fingerprint of a key (some key types require a
 234 passphrase to extract even this much information):
 235
 236 \c puttygen -l mykey.ppk
 237
 238 To add the OpenSSH-format public half of a key to your authorised
 239 keys file:
 240
 241 \c puttygen -L mykey.ppk >> $HOME/.ssh/authorized_keys