1puttygen(1)                    PuTTY tool suite                    puttygen(1)
2
3
4

NAME

6       puttygen - public-key generator for the PuTTY tools
7

SYNOPSIS

9       puttygen ( keyfile | -t keytype [ -b bits ] [ --primes method ] [ -q ] )
10                [ -C new-comment ] [ -P ] [ --reencrypt ]
11                [ --certificate cert-file | --remove-certificate ]
12                [ -O output-type | -l | -L | -p | --dump | --cert-info ]
13                   [ --ppk-param key=value,... | -E fptype ]
14                [ -o output-file ]
15

DESCRIPTION

17       puttygen  is  a  tool to generate and manipulate SSH public and private
18       key pairs. It is part of the PuTTY suite, although it can also interop‐
19       erate with the key formats used by some other SSH clients.
20
21       When  you  run puttygen, it does three things. Firstly, it either loads
22       an existing key file (if you specified keyfile), or generates a new key
23       (if  you specified keytype). Then, it optionally makes modifications to
24       the key (such as changing the comment and/or the passphrase);  finally,
25       it outputs the key, or some information about the key, to a file.
26
27       All  three  of  these phases are controlled by the options described in
28       the following section.
29

OPTIONS

31       In the first phase, puttygen either loads or generates a key. Note that
32       generating  a  key  requires  random  data, which can cause puttygen to
33       pause, possibly for some time if your system does not have much random‐
34       ness available.
35
36       The options to control this phase are:
37
38       keyfile
39              Specify  a  key  file  to be loaded. (Use `-' to read a key file
40              from standard input.)
41
42              Usually this will be a private key, which  can  be  in  the  (de
43              facto  standard)  SSH-1 key format, or in PuTTY's SSH-2 key for‐
44              mat, or in either of the  SSH-2  private  key  formats  used  by
45              OpenSSH and ssh.com's implementation.
46
47              You  can  also specify a file containing only a public key here.
48              The operations you can do are limited to outputting another pub‐
49              lic  key  format  (possibly  removing  an  attached  certificate
50              first), or a fingerprint. Public keys can  be  in  RFC  4716  or
51              OpenSSH format, or the standard SSH-1 format.
52
53       -t keytype
54              Specify  a  type  of key to generate. The acceptable values here
55              are rsa, dsa, ecdsa, eddsa,  ed25519,  and  ed448  (to  generate
56              SSH-2 keys), and rsa1 (to generate SSH-1 keys).
57
58       -b bits
59              Specify  the  size  of the key to generate, in bits. Default for
60              rsa and dsa keys is 2048.
61
62       --primes method
63              Method for generating prime numbers. The acceptable values  here
64              are  probable  (the default), proven, and proven-even; the later
65              methods are slower. (Various synonyms for these method names are
66              also accepted.)
67
68              The  `probable  primes'  method sounds unsafe, but it's the most
69              commonly used prime-generation strategy. There is  in  theory  a
70              possibility  that  it  might accidentally generate a number that
71              isn't prime, but the software does enough checking to make  that
72              probability  vanishingly  small  (less  than  1 in 2^80, or 1 in
73              10^24). So, in practice, nobody worries about it very much.
74
75              The other methods cause PuTTYgen to use numbers that it is  sure
76              are  prime, because it generates the output number together with
77              a proof of its primality. This takes more effort, but it  elimi‐
78              nates that theoretical risk in the probabilistic method.
79
80              You might choose to switch from probable to proven primes if you
81              have a local security standard that demands it, or if you  don't
82              trust  the  probabilistic  argument  for the safety of the usual
83              method.
84
85       --strong-rsa
86              When generating an RSA key, make sure the prime factors  of  the
87              key  modulus are `strong primes'. A strong prime is a prime num‐
88              ber chosen to have a particular  structure  that  makes  certain
89              factoring  algorithms  more difficult to apply, so some security
90              standards recommend their use. However, the most modern  factor‐
91              ing  algorithms  are  unaffected, so this option is probably not
92              worth turning on unless you have a local  standard  that  recom‐
93              mends it.
94
95       -q     Suppress the progress display when generating a new key.
96
97       --old-passphrase file
98              Specify  a file name; the first line will be read from this file
99              (removing any trailing newline) and used as the old  passphrase.
100              CAUTION:  If  the  passphrase  is  important, the file should be
101              stored on a temporary filesystem or else securely  erased  after
102              use.
103
104       --random-device device
105              Specify  device  to read entropy from. By default, puttygen uses
106              /dev/urandom, falling back to /dev/random if it has to.
107
108       In the second phase, puttygen optionally alters properties of  the  key
109       it has loaded or generated. The options to control this are:
110
111       -C new-comment
112              Specify  a  comment  string  to  describe  the key. This comment
113              string will be used by PuTTY to identify the key  to  you  (when
114              asking  you  to  enter  the passphrase, for example, so that you
115              know which passphrase to type).
116
117       -P     Indicate that you want to change the key's passphrase.  This  is
118              automatic  when  you  are generating a new key, but not when you
119              are modifying an existing key.
120
121       --certificate certificate-file
122              Adds an OpenSSH-style certificate to the public half of the key,
123              so that the output file contains a certified public key with the
124              same private key. If the input file already contained a certifi‐
125              cate,  it  will be replaced with the new one. (Use `-' to read a
126              certificate from standard input.)
127
128       --remove-certificate
129              Removes any certificate that was part of the key, to recover the
130              uncertified version of the underlying key.
131
132       --reencrypt
133              For an existing private key saved with a passphrase, refresh the
134              encryption without changing the passphrase.
135
136              This is most likely to be useful with the --ppk-param option, to
137              change some aspect of the key file's format or encryption.
138
139       --ppk-param key=value,...
140              When  saving  a  PPK  file  (the default private output type for
141              SSH-2 keys), adjust details of the on-disk format.
142
143              Aspects to change are specified as a series of  key=value  pairs
144              separated by commas. The keys are:
145
146              version
147                     The  PPK  format  version. Possible values are 3 (the de‐
148                     fault) and 2 (which is less resistant to brute-force  de‐
149                     cryption,  but  which you might need if your key needs to
150                     be used by old versions of PuTTY tools, or other PPK con‐
151                     sumers).
152
153                     The following keys only affect PPK version 3 files.
154
155              kdf    The variant of the Argon2 key derivation function to use.
156                     Options are argon2id (default, and recommended), argon2i,
157                     and argon2d.
158
159                     You  might  change  this if you consider your exposure to
160                     side-channel attacks to be different to the norm.
161
162              memory The amount of memory needed to decrypt the key, in Kbyte.
163                     Default is 8192 (i.e., 8 Mbyte).
164
165              time   Approximate  time,  on  this machine, required to attempt
166                     decrypting the key, in milliseconds. Default is 100 (ms).
167
168              passes Alternative to time: explicitly  specify  the  number  of
169                     hash passes required to attempt decrypting the key.
170
171              parallelism
172                     Number  of parallelisable threads that can be used to de‐
173                     crypt the key. Default is 1 (force decryption to run sin‐
174                     gle-threaded).
175
176       In the third phase, puttygen saves the key or information about it. The
177       options to control this are:
178
179       -O output-type
180              Specify the type of output you want puttygen to produce. Accept‐
181              able options are:
182
183              private
184                     Save  the  private  key in a format usable by PuTTY. This
185                     will either be the standard SSH-1 key format, or  PuTTY's
186                     own SSH-2 key format (`PPK'). This is the default.
187
188              public Save  the  public  key only. For SSH-1 keys, the standard
189                     public key format will be used  (`1024  37  5698745...').
190                     For SSH-2 keys, the public key will be output in the for‐
191                     mat specified by RFC 4716, which  is  a  multi-line  text
192                     file  beginning with the line `---- BEGIN SSH2 PUBLIC KEY
193                     ----'.
194
195              public-openssh
196                     Save the public key only, in a format usable by  OpenSSH.
197                     For SSH-1 keys, this output format behaves identically to
198                     public. For SSH-2 keys, the public key will be output  in
199                     the  OpenSSH  format,  which  is  a single line (`ssh-rsa
200                     AAAAB3NzaC1yc2...').
201
202              fingerprint
203                     Print a fingerprint of the public key. The -E option lets
204                     you  specify  which  fingerprinting algorithm to use. All
205                     algorithms are believed compatible with OpenSSH.
206
207              private-openssh
208                     Save an SSH-2 private key in OpenSSH's format, using  the
209                     oldest  format available to maximise backward compatibil‐
210                     ity. This option is not permitted for SSH-1 keys.
211
212              private-openssh-new
213                     As private-openssh, except that  it  forces  the  use  of
214                     OpenSSH's newer format even for RSA, DSA, and ECDSA keys.
215
216              private-sshcom
217                     Save  an  SSH-2 private key in ssh.com's format. This op‐
218                     tion is not permitted for SSH-1 keys.
219
220              cert-info
221                     Save a textual dump of information about the  certificate
222                     on  the  key,  if any: whether it's a host or a user cer‐
223                     tificate, what host(s) or user(s) it's certified  to  be,
224                     its  validity  period, ID and serial number, and the fin‐
225                     gerprint of the signing CA.
226
227              text   Save a textual dump of the numeric components  comprising
228                     the  key (both the public and private parts, if present).
229                     Useful for debugging, or for using PuTTYgen as a key gen‐
230                     erator for applications other than SSH.
231
232                     The  output  consists  of  a  series of name=value lines,
233                     where each value is either a  C-like  string  literal  in
234                     double  quotes, a hexadecimal number starting with 0x...,
235                     or  a  binary  blob  encoded  with  base64,  denoted   by
236                     b64("...").
237
238              If no output type is specified, the default is private.
239
240       -o output-file
241              Specify the file where puttygen should write its output. If this
242              option is not specified, puttygen will assume you want to  over‐
243              write  the  original file if the input and output file types are
244              the same (changing a comment or passphrase), and will assume you
245              want  to  output  to  stdout if you are asking for a public key,
246              fingerprint, or one of the textual dump types. Otherwise, the -o
247              option is required.
248
249       -l     Synonym for `-O fingerprint'.
250
251       -L     Synonym for `-O public-openssh'.
252
253       -p     Synonym for `-O public'.
254
255       --cert-info
256              Synonym for `-O cert-info'.
257
258       --dump Synonym for `-O text'.
259
260       -E fptype
261              Specify  the  algorithm  to use if generating a fingerprint. The
262              available algorithms are are sha256 (the default) and md5.
263
264              By default, when showing the fingerprint of a  public  key  that
265              includes  a  certificate, puttygen will not include the certifi‐
266              cate, so that the fingerprint shown will be the same as the  un‐
267              derlying  public  key. If you want the fingerprint including the
268              certificate (for example, so  as  to  tell  two  certified  keys
269              apart),  you  can specify sha256-cert or md5-cert as the finger‐
270              print type.
271
272       --new-passphrase file
273              Specify a file name; the first line will be read from this  file
274              (removing  any trailing newline) and used as the new passphrase.
275              If the file is empty then the saved  key  will  be  unencrypted.
276              CAUTION:  If  the  passphrase  is  important, the file should be
277              stored on a temporary filesystem or else securely  erased  after
278              use.
279
280       The following options do not run PuTTYgen as normal, but print informa‐
281       tional messages and then quit:
282
283       -h, --help
284              Display a message summarizing the available options.
285
286       -V, --version
287              Display the version of PuTTYgen.
288
289       --pgpfp
290              Display the fingerprints of the PuTTY PGP Master Keys, to aid in
291              verifying new files released by the PuTTY team.
292

EXAMPLES

294       To  generate  an  SSH-2  RSA key pair and save it in PuTTY's own format
295       (you will be prompted for the passphrase):
296
297       puttygen -t rsa -C "my home key" -o mykey.ppk
298
299       To generate a larger (4096-bit) key:
300
301       puttygen -t rsa -b 4096 -C "my home key" -o mykey.ppk
302
303       To change the passphrase on a key (you will be prompted for the old and
304       new passphrases):
305
306       puttygen -P mykey.ppk
307
308       To change the comment on a key:
309
310       puttygen -C "new comment" mykey.ppk
311
312       To convert a key into OpenSSH's private key format:
313
314       puttygen mykey.ppk -O private-openssh -o my-openssh-key
315
316       To  convert  a key from another format (puttygen will automatically de‐
317       tect the input key type):
318
319       puttygen my-ssh.com-key -o mykey.ppk
320
321       To display the SHA-256 fingerprint of a key (some key types  require  a
322       passphrase to extract even this much information):
323
324       puttygen -l mykey.ppk
325
326       To  add the OpenSSH-format public half of a key to your authorised keys
327       file:
328
329       puttygen -L mykey.ppk >> $HOME/.ssh/authorized_keys
330
331
332
333PuTTY tool suite                  2004‐03‐24                       puttygen(1)
Impressum