1SSH-KEYGEN(1)             BSD General Commands Manual            SSH-KEYGEN(1)
2

NAME

4     ssh-keygen — authentication key generation, management and conversion
5

SYNOPSIS

7     ssh-keygen [-q] [-b bits] [-t dsa | ecdsa | ed25519 | rsa]
8                [-N new_passphrase] [-C comment] [-f output_keyfile]
9     ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile]
10     ssh-keygen -i [-m key_format] [-f input_keyfile]
11     ssh-keygen -e [-m key_format] [-f input_keyfile]
12     ssh-keygen -y [-f input_keyfile]
13     ssh-keygen -c [-P passphrase] [-C comment] [-f keyfile]
14     ssh-keygen -l [-v] [-E fingerprint_hash] [-f input_keyfile]
15     ssh-keygen -B [-f input_keyfile]
16     ssh-keygen -D pkcs11
17     ssh-keygen -F hostname [-f known_hosts_file] [-l]
18     ssh-keygen -H [-f known_hosts_file]
19     ssh-keygen -R hostname [-f known_hosts_file]
20     ssh-keygen -r hostname [-f input_keyfile] [-g]
21     ssh-keygen -G output_file [-v] [-b bits] [-M memory] [-S start_point]
22     ssh-keygen -T output_file -f input_file [-v] [-a rounds] [-J num_lines]
23                [-j start_line] [-K checkpt] [-W generator]
24     ssh-keygen -s ca_key -I certificate_identity [-h] [-U]
25                [-D pkcs11_provider] [-n principals] [-O option]
26                [-V validity_interval] [-z serial_number] file ...
27     ssh-keygen -L [-f input_keyfile]
28     ssh-keygen -A [-f prefix_path]
29     ssh-keygen -k -f krl_file [-u] [-s ca_public] [-z version_number]
30                file ...
31     ssh-keygen -Q -f krl_file file ...
32

DESCRIPTION

34     ssh-keygen generates, manages and converts authentication keys for
35     ssh(1).  ssh-keygen can create keys for use by SSH protocol version 2.
36
37     The type of key to be generated is specified with the -t option.  If
38     invoked without any arguments, ssh-keygen will generate an RSA key.
39
40     ssh-keygen is also used to generate groups for use in Diffie-Hellman
41     group exchange (DH-GEX).  See the MODULI GENERATION section for details.
42
43     Finally, ssh-keygen can be used to generate and update Key Revocation
44     Lists, and to test whether given keys have been revoked by one.  See the
45     KEY REVOCATION LISTS section for details.
46
47     Normally each user wishing to use SSH with public key authentication runs
48     this once to create the authentication key in ~/.ssh/id_dsa,
49     ~/.ssh/id_ecdsa, ~/.ssh/id_ed25519 or ~/.ssh/id_rsa.  Additionally, the
50     system administrator may use this to generate host keys, as seen in
51     /etc/rc.
52
53     Normally this program generates the key and asks for a file in which to
54     store the private key.  The public key is stored in a file with the same
55     name but “.pub” appended.  The program also asks for a passphrase.  The
56     passphrase may be empty to indicate no passphrase (host keys must have an
57     empty passphrase), or it may be a string of arbitrary length.  A
58     passphrase is similar to a password, except it can be a phrase with a
59     series of words, punctuation, numbers, whitespace, or any string of char‐
60     acters you want.  Good passphrases are 10-30 characters long, are not
61     simple sentences or otherwise easily guessable (English prose has only
62     1-2 bits of entropy per character, and provides very bad passphrases),
63     and contain a mix of upper and lowercase letters, numbers, and non-
64     alphanumeric characters.  The passphrase can be changed later by using
65     the -p option.
66
67     There is no way to recover a lost passphrase.  If the passphrase is lost
68     or forgotten, a new key must be generated and the corresponding public
69     key copied to other machines.
70
71     For keys stored in the newer OpenSSH format, there is also a comment
72     field in the key file that is only for convenience to the user to help
73     identify the key.  The comment can tell what the key is for, or whatever
74     is useful.  The comment is initialized to “user@host” when the key is
75     created, but can be changed using the -c option.
76
77     After a key is generated, instructions below detail where the keys should
78     be placed to be activated.
79
80     The options are as follows:
81
82     -A      For each of the key types (rsa, dsa, ecdsa and ed25519) for which
83             host keys do not exist, generate the host keys with the default
84             key file path, an empty passphrase, default bits for the key
85             type, and default comment.  If -f has also been specified, its
86             argument is used as a prefix to the default path for the result‐
87             ing host key files.  This is used by /etc/rc to generate new host
88             keys.
89
90     -a rounds
91             When saving a private key this option specifies the number of KDF
92             (key derivation function) rounds used.  Higher numbers result in
93             slower passphrase verification and increased resistance to brute-
94             force password cracking (should the keys be stolen).
95
96             When screening DH-GEX candidates (using the -T command).  This
97             option specifies the number of primality tests to perform.
98
99     -B      Show the bubblebabble digest of specified private or public key
100             file.
101
102     -b bits
103             Specifies the number of bits in the key to create.  For RSA keys,
104             the minimum size is 1024 bits and the default is 2048 bits.  Gen‐
105             erally, 2048 bits is considered sufficient.  DSA keys must be
106             exactly 1024 bits as specified by FIPS 186-2.  For ECDSA keys,
107             the -b flag determines the key length by selecting from one of
108             three elliptic curve sizes: 256, 384 or 521 bits.  Attempting to
109             use bit lengths other than these three values for ECDSA keys will
110             fail.  Ed25519 keys have a fixed length and the -b flag will be
111             ignored.
112
113     -C comment
114             Provides a new comment.
115
116     -c      Requests changing the comment in the private and public key
117             files.  The program will prompt for the file containing the pri‐
118             vate keys, for the passphrase if the key has one, and for the new
119             comment.
120
121     -D pkcs11
122             Download the RSA public keys provided by the PKCS#11 shared
123             library pkcs11.  When used in combination with -s, this option
124             indicates that a CA key resides in a PKCS#11 token (see the
125             CERTIFICATES section for details).
126
127     -E fingerprint_hash
128             Specifies the hash algorithm used when displaying key finger‐
129             prints.  Valid options are: “md5” and “sha256”.  The default is
130             “sha256”.
131
132     -e      This option will read a private or public OpenSSH key file and
133             print to stdout the key in one of the formats specified by the -m
134             option.  The default export format is “RFC4716”.  This option
135             allows exporting OpenSSH keys for use by other programs, includ‐
136             ing several commercial SSH implementations.
137
138     -F hostname
139             Search for the specified hostname in a known_hosts file, listing
140             any occurrences found.  This option is useful to find hashed host
141             names or addresses and may also be used in conjunction with the
142             -H option to print found keys in a hashed format.
143
144     -f filename
145             Specifies the filename of the key file.
146
147     -G output_file
148             Generate candidate primes for DH-GEX.  These primes must be
149             screened for safety (using the -T option) before use.
150
151     -g      Use generic DNS format when printing fingerprint resource records
152             using the -r command.
153
154     -H      Hash a known_hosts file.  This replaces all hostnames and
155             addresses with hashed representations within the specified file;
156             the original content is moved to a file with a .old suffix.
157             These hashes may be used normally by ssh and sshd, but they do
158             not reveal identifying information should the file's contents be
159             disclosed.  This option will not modify existing hashed hostnames
160             and is therefore safe to use on files that mix hashed and non-
161             hashed names.
162
163     -h      When signing a key, create a host certificate instead of a user
164             certificate.  Please see the CERTIFICATES section for details.
165
166     -I certificate_identity
167             Specify the key identity when signing a public key.  Please see
168             the CERTIFICATES section for details.
169
170     -i      This option will read an unencrypted private (or public) key file
171             in the format specified by the -m option and print an OpenSSH
172             compatible private (or public) key to stdout.  This option allows
173             importing keys from other software, including several commercial
174             SSH implementations.  The default import format is “RFC4716”.
175
176     -J num_lines
177             Exit after screening the specified number of lines while perform‐
178             ing DH candidate screening using the -T option.
179
180     -j start_line
181             Start screening at the specified line number while performing DH
182             candidate screening using the -T option.
183
184     -K checkpt
185             Write the last line processed to the file checkpt while perform‐
186             ing DH candidate screening using the -T option.  This will be
187             used to skip lines in the input file that have already been pro‐
188             cessed if the job is restarted.
189
190     -k      Generate a KRL file.  In this mode, ssh-keygen will generate a
191             KRL file at the location specified via the -f flag that revokes
192             every key or certificate presented on the command line.
193             Keys/certificates to be revoked may be specified by public key
194             file or using the format described in the KEY REVOCATION LISTS
195             section.
196
197     -L      Prints the contents of one or more certificates.
198
199     -l      Show fingerprint of specified public key file.  For RSA and DSA
200             keys ssh-keygen tries to find the matching public key file and
201             prints its fingerprint.  If combined with -v, a visual ASCII art
202             representation of the key is supplied with the fingerprint.
203
204     -M memory
205             Specify the amount of memory to use (in megabytes) when generat‐
206             ing candidate moduli for DH-GEX.
207
208     -m key_format
209             Specify a key format for the -i (import) or -e (export) conver‐
210             sion options.  The supported key formats are: “RFC4716” (RFC
211             4716/SSH2 public or private key), “PKCS8” (PEM PKCS8 public key)
212             or “PEM” (PEM public key).  The default conversion format is
213             “RFC4716”.  Setting a format of “PEM” when generating or updating
214             a supported private key type will cause the key to be stored in
215             the legacy PEM private key format.
216
217     -N new_passphrase
218             Provides the new passphrase.
219
220     -n principals
221             Specify one or more principals (user or host names) to be
222             included in a certificate when signing a key.  Multiple princi‐
223             pals may be specified, separated by commas.  Please see the
224             CERTIFICATES section for details.
225
226     -O option
227             Specify a certificate option when signing a key.  This option may
228             be specified multiple times.  See also the CERTIFICATES section
229             for further details.
230
231             At present, no standard options are valid for host keys.  The
232             options that are valid for user certificates are:
233
234             clear   Clear all enabled permissions.  This is useful for clear‐
235                     ing the default set of permissions so permissions may be
236                     added individually.
237
238             critical:name[=contents]
239             extension:name[=contents]
240                     Includes an arbitrary certificate critical option or
241                     extension.  The specified name should include a domain
242                     suffix, e.g. “name@example.com”.  If contents is speci‐
243                     fied then it is included as the contents of the exten‐
244                     sion/option encoded as a string, otherwise the exten‐
245                     sion/option is created with no contents (usually indicat‐
246                     ing a flag).  Extensions may be ignored by a client or
247                     server that does not recognise them, whereas unknown
248                     critical options will cause the certificate to be
249                     refused.
250
251             force-command=command
252                     Forces the execution of command instead of any shell or
253                     command specified by the user when the certificate is
254                     used for authentication.
255
256             no-agent-forwarding
257                     Disable ssh-agent(1) forwarding (permitted by default).
258
259             no-port-forwarding
260                     Disable port forwarding (permitted by default).
261
262             no-pty  Disable PTY allocation (permitted by default).
263
264             no-user-rc
265                     Disable execution of ~/.ssh/rc by sshd(8) (permitted by
266                     default).
267
268             no-x11-forwarding
269                     Disable X11 forwarding (permitted by default).
270
271             permit-agent-forwarding
272                     Allows ssh-agent(1) forwarding.
273
274             permit-port-forwarding
275                     Allows port forwarding.
276
277             permit-pty
278                     Allows PTY allocation.
279
280             permit-user-rc
281                     Allows execution of ~/.ssh/rc by sshd(8).
282
283             permit-X11-forwarding
284                     Allows X11 forwarding.
285
286             source-address=address_list
287                     Restrict the source addresses from which the certificate
288                     is considered valid.  The address_list is a comma-sepa‐
289                     rated list of one or more address/netmask pairs in CIDR
290                     format.
291
292     -P passphrase
293             Provides the (old) passphrase.
294
295     -p      Requests changing the passphrase of a private key file instead of
296             creating a new private key.  The program will prompt for the file
297             containing the private key, for the old passphrase, and twice for
298             the new passphrase.
299
300     -Q      Test whether keys have been revoked in a KRL.
301
302     -q      Silence ssh-keygen.
303
304     -R hostname
305             Removes all keys belonging to hostname from a known_hosts file.
306             This option is useful to delete hashed hosts (see the -H option
307             above).
308
309     -r hostname
310             Print the SSHFP fingerprint resource record named hostname for
311             the specified public key file.
312
313     -S start
314             Specify start point (in hex) when generating candidate moduli for
315             DH-GEX.
316
317     -s ca_key
318             Certify (sign) a public key using the specified CA key.  Please
319             see the CERTIFICATES section for details.
320
321             When generating a KRL, -s specifies a path to a CA public key
322             file used to revoke certificates directly by key ID or serial
323             number.  See the KEY REVOCATION LISTS section for details.
324
325     -T output_file
326             Test DH group exchange candidate primes (generated using the -G
327             option) for safety.
328
329     -t dsa | ecdsa | ed25519 | rsa
330             Specifies the type of key to create.  The possible values are
331             “dsa”, “ecdsa”, “ed25519”, or “rsa”.
332
333     -U      When used in combination with -s, this option indicates that a CA
334             key resides in a ssh-agent(1).  See the CERTIFICATES section for
335             more information.
336
337     -u      Update a KRL.  When specified with -k, keys listed via the com‐
338             mand line are added to the existing KRL rather than a new KRL
339             being created.
340
341     -V validity_interval
342             Specify a validity interval when signing a certificate.  A valid‐
343             ity interval may consist of a single time, indicating that the
344             certificate is valid beginning now and expiring at that time, or
345             may consist of two times separated by a colon to indicate an
346             explicit time interval.
347
348             The start time may be specified as the string “always” to indi‐
349             cate the certificate has no specified start time, a date in
350             YYYYMMDD format, a time in YYYYMMDDHHMM[SS] format, a relative
351             time (to the current time) consisting of a minus sign followed by
352             an interval in the format described in the TIME FORMATS section
353             of sshd_config(5).
354
355             The end time may be specified as a YYYYMMDD date, a YYYYMMD‐
356             DHHMM[SS] time, a relative time starting with a plus character or
357             the string “forever” to indicate that the certificate has no
358             expirty date.
359
360             For example: “+52w1d” (valid from now to 52 weeks and one day
361             from now), “-4w:+4w” (valid from four weeks ago to four weeks
362             from now), “20100101123000:20110101123000” (valid from 12:30 PM,
363             January 1st, 2010 to 12:30 PM, January 1st, 2011), “-1d:20110101”
364             (valid from yesterday to midnight, January 1st, 2011).
365             “-1m:forever” (valid from one minute ago and never expiring).
366
367     -v      Verbose mode.  Causes ssh-keygen to print debugging messages
368             about its progress.  This is helpful for debugging moduli genera‐
369             tion.  Multiple -v options increase the verbosity.  The maximum
370             is 3.
371
372     -W generator
373             Specify desired generator when testing candidate moduli for DH-
374             GEX.
375
376     -y      This option will read a private OpenSSH format file and print an
377             OpenSSH public key to stdout.
378
379     -z serial_number
380             Specifies a serial number to be embedded in the certificate to
381             distinguish this certificate from others from the same CA.  The
382             default serial number is zero.
383
384             When generating a KRL, the -z flag is used to specify a KRL ver‐
385             sion number.
386

MODULI GENERATION

388     ssh-keygen may be used to generate groups for the Diffie-Hellman Group
389     Exchange (DH-GEX) protocol.  Generating these groups is a two-step
390     process: first, candidate primes are generated using a fast, but memory
391     intensive process.  These candidate primes are then tested for suitabil‐
392     ity (a CPU-intensive process).
393
394     Generation of primes is performed using the -G option.  The desired
395     length of the primes may be specified by the -b option.  For example:
396
397           # ssh-keygen -G moduli-2048.candidates -b 2048
398
399     By default, the search for primes begins at a random point in the desired
400     length range.  This may be overridden using the -S option, which speci‐
401     fies a different start point (in hex).
402
403     Once a set of candidates have been generated, they must be screened for
404     suitability.  This may be performed using the -T option.  In this mode
405     ssh-keygen will read candidates from standard input (or a file specified
406     using the -f option).  For example:
407
408           # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
409
410     By default, each candidate will be subjected to 100 primality tests.
411     This may be overridden using the -a option.  The DH generator value will
412     be chosen automatically for the prime under consideration.  If a specific
413     generator is desired, it may be requested using the -W option.  Valid
414     generator values are 2, 3, and 5.
415
416     Screened DH groups may be installed in /etc/gsissh/moduli.  It is impor‐
417     tant that this file contains moduli of a range of bit lengths and that
418     both ends of a connection share common moduli.
419

CERTIFICATES

421     ssh-keygen supports signing of keys to produce certificates that may be
422     used for user or host authentication.  Certificates consist of a public
423     key, some identity information, zero or more principal (user or host)
424     names and a set of options that are signed by a Certification Authority
425     (CA) key.  Clients or servers may then trust only the CA key and verify
426     its signature on a certificate rather than trusting many user/host keys.
427     Note that OpenSSH certificates are a different, and much simpler, format
428     to the X.509 certificates used in ssl(8).
429
430     ssh-keygen supports two types of certificates: user and host.  User cer‐
431     tificates authenticate users to servers, whereas host certificates
432     authenticate server hosts to users.  To generate a user certificate:
433
434           $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
435
436     The resultant certificate will be placed in /path/to/user_key-cert.pub.
437     A host certificate requires the -h option:
438
439           $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
440
441     The host certificate will be output to /path/to/host_key-cert.pub.
442
443     It is possible to sign using a CA key stored in a PKCS#11 token by pro‐
444     viding the token library using -D and identifying the CA key by providing
445     its public half as an argument to -s:
446
447           $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub
448
449     Similarly, it is possible for the CA key to be hosted in a ssh-agent(1).
450     This is indicated by the -U flag and, again, the CA key must be identi‐
451     fied by its public half.
452
453           $ ssh-keygen -Us ca_key.pub -I key_id user_key.pub
454
455     In all cases, key_id is a "key identifier" that is logged by the server
456     when the certificate is used for authentication.
457
458     Certificates may be limited to be valid for a set of principal
459     (user/host) names.  By default, generated certificates are valid for all
460     users or hosts.  To generate a certificate for a specified set of princi‐
461     pals:
462
463           $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
464           $ ssh-keygen -s ca_key -I key_id -h -n host.domain host_key.pub
465
466     Additional limitations on the validity and use of user certificates may
467     be specified through certificate options.  A certificate option may dis‐
468     able features of the SSH session, may be valid only when presented from
469     particular source addresses or may force the use of a specific command.
470     For a list of valid certificate options, see the documentation for the -O
471     option above.
472
473     Finally, certificates may be defined with a validity lifetime.  The -V
474     option allows specification of certificate start and end times.  A cer‐
475     tificate that is presented at a time outside this range will not be con‐
476     sidered valid.  By default, certificates are valid from UNIX Epoch to the
477     distant future.
478
479     For certificates to be used for user or host authentication, the CA pub‐
480     lic key must be trusted by sshd(8) or ssh(1).  Please refer to those man‐
481     ual pages for details.
482

KEY REVOCATION LISTS

484     ssh-keygen is able to manage OpenSSH format Key Revocation Lists (KRLs).
485     These binary files specify keys or certificates to be revoked using a
486     compact format, taking as little as one bit per certificate if they are
487     being revoked by serial number.
488
489     KRLs may be generated using the -k flag.  This option reads one or more
490     files from the command line and generates a new KRL.  The files may
491     either contain a KRL specification (see below) or public keys, listed one
492     per line.  Plain public keys are revoked by listing their hash or con‐
493     tents in the KRL and certificates revoked by serial number or key ID (if
494     the serial is zero or not available).
495
496     Revoking keys using a KRL specification offers explicit control over the
497     types of record used to revoke keys and may be used to directly revoke
498     certificates by serial number or key ID without having the complete orig‐
499     inal certificate on hand.  A KRL specification consists of lines contain‐
500     ing one of the following directives followed by a colon and some direc‐
501     tive-specific information.
502
503     serial: serial_number[-serial_number]
504             Revokes a certificate with the specified serial number.  Serial
505             numbers are 64-bit values, not including zero and may be
506             expressed in decimal, hex or octal.  If two serial numbers are
507             specified separated by a hyphen, then the range of serial numbers
508             including and between each is revoked.  The CA key must have been
509             specified on the ssh-keygen command line using the -s option.
510
511     id: key_id
512             Revokes a certificate with the specified key ID string.  The CA
513             key must have been specified on the ssh-keygen command line using
514             the -s option.
515
516     key: public_key
517             Revokes the specified key.  If a certificate is listed, then it
518             is revoked as a plain public key.
519
520     sha1: public_key
521             Revokes the specified key by including its SHA1 hash in the KRL.
522
523     sha256: public_key
524             Revokes the specified key by including its SHA256 hash in the
525             KRL.  KRLs that revoke keys by SHA256 hash are not supported by
526             OpenSSH versions prior to 7.9.
527
528     hash: fingerprint
529             Revokes a key using a fingerprint hash, as obtained from a
530             sshd(8) authentication log message or the ssh-keygen -l flag.
531             Only SHA256 fingerprints are supported here and resultant KRLs
532             are not supported by OpenSSH versions prior to 7.9.
533
534     KRLs may be updated using the -u flag in addition to -k.  When this
535     option is specified, keys listed via the command line are merged into the
536     KRL, adding to those already there.
537
538     It is also possible, given a KRL, to test whether it revokes a particular
539     key (or keys).  The -Q flag will query an existing KRL, testing each key
540     specified on the command line.  If any key listed on the command line has
541     been revoked (or an error encountered) then ssh-keygen will exit with a
542     non-zero exit status.  A zero exit status will only be returned if no key
543     was revoked.
544

FILES

546     ~/.ssh/id_dsa
547     ~/.ssh/id_ecdsa
548     ~/.ssh/id_ed25519
549     ~/.ssh/id_rsa
550             Contains the DSA, ECDSA, Ed25519 or RSA authentication identity
551             of the user.  This file should not be readable by anyone but the
552             user.  It is possible to specify a passphrase when generating the
553             key; that passphrase will be used to encrypt the private part of
554             this file using 128-bit AES.  This file is not automatically
555             accessed by ssh-keygen but it is offered as the default file for
556             the private key.  ssh(1) will read this file when a login attempt
557             is made.
558
559     ~/.ssh/id_dsa.pub
560     ~/.ssh/id_ecdsa.pub
561     ~/.ssh/id_ed25519.pub
562     ~/.ssh/id_rsa.pub
563             Contains the DSA, ECDSA, Ed25519 or RSA public key for authenti‐
564             cation.  The contents of this file should be added to
565             ~/.ssh/authorized_keys on all machines where the user wishes to
566             log in using public key authentication.  There is no need to keep
567             the contents of this file secret.
568
569     /etc/gsissh/moduli
570             Contains Diffie-Hellman groups used for DH-GEX.  The file format
571             is described in moduli(5).
572

SEE ALSO

574     ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8)
575
576     The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006.
577

AUTHORS

579     OpenSSH is a derivative of the original and free ssh 1.2.12 release by
580     Tatu Ylonen.  Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
581     de Raadt and Dug Song removed many bugs, re-added newer features and cre‐
582     ated OpenSSH.  Markus Friedl contributed the support for SSH protocol
583     versions 1.5 and 2.0.
584
585BSD                              June 20, 2019                             BSD
Impressum