1SSH-KEYGEN(1) BSD General Commands Manual SSH-KEYGEN(1)
2
4 ssh-keygen — authentication key generation, management and conversion
5
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
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 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 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 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 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 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 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 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 After a key is generated, instructions below detail where the keys should
78 be placed to be activated.
79 The options are as follows:
81 -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 -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 When screening DH-GEX candidates (using the -T command). This
97 option specifies the number of primality tests to perform.
98 -B Show the bubblebabble digest of specified private or public key
100 file.
101 -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 -C comment
114 Provides a new comment.
115 -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 -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 -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 -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 -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 -f filename
145 Specifies the filename of the key file.
146 -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 -g Use generic DNS format when printing fingerprint resource records
152 using the -r command.
153 -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 -h When signing a key, create a host certificate instead of a user
164 certificate. Please see the CERTIFICATES section for details.
165 -I certificate_identity
167 Specify the key identity when signing a public key. Please see
168 the CERTIFICATES section for details.
169 -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 -J num_lines
177 Exit after screening the specified number of lines while perform‐
178 ing DH candidate screening using the -T option.
179 -j start_line
181 Start screening at the specified line number while performing DH
182 candidate screening using the -T option.
183 -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 -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 -L Prints the contents of one or more certificates.
198 -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 -M memory
205 Specify the amount of memory to use (in megabytes) when generat‐
206 ing candidate moduli for DH-GEX.
207 -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 -N new_passphrase
218 Provides the new passphrase.
219 -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 -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 At present, no standard options are valid for host keys. The
232 options that are valid for user certificates are:
233 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 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 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 no-agent-forwarding
257 Disable ssh-agent(1) forwarding (permitted by default).
258 no-port-forwarding
260 Disable port forwarding (permitted by default).
261 no-pty Disable PTY allocation (permitted by default).
263 no-user-rc
265 Disable execution of ~/.ssh/rc by sshd(8) (permitted by
266 default).
267 no-x11-forwarding
269 Disable X11 forwarding (permitted by default).
270 permit-agent-forwarding
272 Allows ssh-agent(1) forwarding.
273 permit-port-forwarding
275 Allows port forwarding.
276 permit-pty
278 Allows PTY allocation.
279 permit-user-rc
281 Allows execution of ~/.ssh/rc by sshd(8).
282 permit-X11-forwarding
284 Allows X11 forwarding.
285 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 -P passphrase
293 Provides the (old) passphrase.
294 -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 -Q Test whether keys have been revoked in a KRL.
301 -q Silence ssh-keygen.
303 -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 -r hostname
310 Print the SSHFP fingerprint resource record named hostname for
311 the specified public key file.
312 -S start
314 Specify start point (in hex) when generating candidate moduli for
315 DH-GEX.
316 -s ca_key
318 Certify (sign) a public key using the specified CA key. Please
319 see the CERTIFICATES section for details.
320 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 -T output_file
326 Test DH group exchange candidate primes (generated using the -G
327 option) for safety.
328 -t dsa | ecdsa | ed25519 | rsa
330 Specifies the type of key to create. The possible values are
331 “dsa”, “ecdsa”, “ed25519”, or “rsa”.
332 -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 -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 -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 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 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 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 -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 -W generator
373 Specify desired generator when testing candidate moduli for DH-
374 GEX.
375 -y This option will read a private OpenSSH format file and print an
377 OpenSSH public key to stdout.
378 -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 When generating a KRL, the -z flag is used to specify a KRL ver‐
385 sion number.
386
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 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 # ssh-keygen -G moduli-2048.candidates -b 2048
398 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 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 # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
409 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 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
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 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 $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
435 The resultant certificate will be placed in /path/to/user_key-cert.pub.
437 A host certificate requires the -h option:
438 $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
440 The host certificate will be output to /path/to/host_key-cert.pub.
442 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 $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub
448 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 $ ssh-keygen -Us ca_key.pub -I key_id user_key.pub
454 In all cases, key_id is a "key identifier" that is logged by the server
456 when the certificate is used for authentication.
457 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 $ 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 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 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 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
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 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 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 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 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 key: public_key
517 Revokes the specified key. If a certificate is listed, then it
518 is revoked as a plain public key.
519 sha1: public_key
521 Revokes the specified key by including its SHA1 hash in the KRL.
522 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 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 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 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
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 ~/.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 /etc/gsissh/moduli
570 Contains Diffie-Hellman groups used for DH-GEX. The file format
571 is described in moduli(5).
572
574 ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8)
575 The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006.
577
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.
584BSD June 20, 2019 BSD