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

NAME

4     ssh-keygen — OpenSSH authentication key utility
5

SYNOPSIS

7     ssh-keygen [-q] [-a rounds] [-b bits] [-C comment] [-f output_keyfile]
8                [-m format] [-N new_passphrase] [-O option]
9                [-t dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa]
10                [-w provider] [-Z cipher]
11     ssh-keygen -p [-a rounds] [-f keyfile] [-m format] [-N new_passphrase]
12                [-P old_passphrase] [-Z cipher]
13     ssh-keygen -i [-f input_keyfile] [-m key_format]
14     ssh-keygen -e [-f input_keyfile] [-m key_format]
15     ssh-keygen -y [-f input_keyfile]
16     ssh-keygen -c [-a rounds] [-C comment] [-f keyfile] [-P passphrase]
17     ssh-keygen -l [-v] [-E fingerprint_hash] [-f input_keyfile]
18     ssh-keygen -B [-f input_keyfile]
19     ssh-keygen -D pkcs11
20     ssh-keygen -F hostname [-lv] [-f known_hosts_file]
21     ssh-keygen -H [-f known_hosts_file]
22     ssh-keygen -K [-a rounds] [-w provider]
23     ssh-keygen -R hostname [-f known_hosts_file]
24     ssh-keygen -r hostname [-g] [-f input_keyfile]
25     ssh-keygen -M generate [-O option] output_file
26     ssh-keygen -M screen [-f input_file] [-O option] output_file
27     ssh-keygen -I certificate_identity -s ca_key [-hU] [-D pkcs11_provider]
28                [-n principals] [-O option] [-V validity_interval]
29                [-z serial_number] file ...
30     ssh-keygen -L [-f input_keyfile]
31     ssh-keygen -A [-a rounds] [-f prefix_path]
32     ssh-keygen -k -f krl_file [-u] [-s ca_public] [-z version_number]
33                file ...
34     ssh-keygen -Q [-l] -f krl_file file ...
35     ssh-keygen -Y find-principals [-O option] -s signature_file -f
36                allowed_signers_file
37     ssh-keygen -Y match-principals -I signer_identity -f allowed_signers_file
38     ssh-keygen -Y check-novalidate [-O option] -n namespace -s signature_file
39     ssh-keygen -Y sign [-O option] -f key_file -n namespace file ...
40     ssh-keygen -Y verify [-O option] -f allowed_signers_file -I
41                signer_identity -n namespace -s signature_file
42                [-r revocation_file]
43

DESCRIPTION

45     ssh-keygen generates, manages and converts authentication keys for
46     ssh(1).  ssh-keygen can create keys for use by SSH protocol version 2.
47
48     The type of key to be generated is specified with the -t option.  If in‐
49     voked without any arguments, ssh-keygen will generate an RSA key.
50
51     ssh-keygen is also used to generate groups for use in Diffie-Hellman
52     group exchange (DH-GEX).  See the MODULI GENERATION section for details.
53
54     Finally, ssh-keygen can be used to generate and update Key Revocation
55     Lists, and to test whether given keys have been revoked by one.  See the
56     KEY REVOCATION LISTS section for details.
57
58     Normally each user wishing to use SSH with public key authentication runs
59     this once to create the authentication key in ~/.ssh/id_dsa,
60     ~/.ssh/id_ecdsa, ~/.ssh/id_ecdsa_sk, ~/.ssh/id_ed25519,
61     ~/.ssh/id_ed25519_sk or ~/.ssh/id_rsa.  Additionally, the system adminis‐
62     trator may use this to generate host keys, as seen in /etc/rc.
63
64     Normally this program generates the key and asks for a file in which to
65     store the private key.  The public key is stored in a file with the same
66     name but “.pub” appended.  The program also asks for a passphrase.  The
67     passphrase may be empty to indicate no passphrase (host keys must have an
68     empty passphrase), or it may be a string of arbitrary length.  A
69     passphrase is similar to a password, except it can be a phrase with a se‐
70     ries of words, punctuation, numbers, whitespace, or any string of charac‐
71     ters you want.  Good passphrases are 10-30 characters long, are not sim‐
72     ple sentences or otherwise easily guessable (English prose has only 1-2
73     bits of entropy per character, and provides very bad passphrases), and
74     contain a mix of upper and lowercase letters, numbers, and non-alphanu‐
75     meric characters.  The passphrase can be changed later by using the -p
76     option.
77
78     There is no way to recover a lost passphrase.  If the passphrase is lost
79     or forgotten, a new key must be generated and the corresponding public
80     key copied to other machines.
81
82     ssh-keygen will by default write keys in an OpenSSH-specific format.
83     This format is preferred as it offers better protection for keys at rest
84     as well as allowing storage of key comments within the private key file
85     itself.  The key comment may be useful to help identify the key.  The
86     comment is initialized to “user@host” when the key is created, but can be
87     changed using the -c option.
88
89     It is still possible for ssh-keygen to write the previously-used PEM for‐
90     mat private keys using the -m flag.  This may be used when generating new
91     keys, and existing new-format keys may be converted using this option in
92     conjunction with the -p (change passphrase) flag.
93
94     After a key is generated, ssh-keygen will ask where the keys should be
95     placed to be activated.
96
97     The options are as follows:
98
99     -A      Generate host keys of all default key types (rsa, ecdsa, and
100             ed25519) if they do not already exist.  The host keys are gener‐
101             ated with the default key file path, an empty passphrase, default
102             bits for the key type, and default comment.  If -f has also been
103             specified, its argument is used as a prefix to the default path
104             for the resulting host key files.  This is used by /etc/rc to
105             generate new host keys.
106
107     -a rounds
108             When saving a private key, this option specifies the number of
109             KDF (key derivation function, currently bcrypt_pbkdf(3)) rounds
110             used.  Higher numbers result in slower passphrase verification
111             and increased resistance to brute-force password cracking (should
112             the keys be stolen).  The default is 16 rounds.
113
114     -B      Show the bubblebabble digest of specified private or public key
115             file.
116
117     -b bits
118             Specifies the number of bits in the key to create.  For RSA keys,
119             the minimum size is 1024 bits and the default is 3072 bits.  Gen‐
120             erally, 3072 bits is considered sufficient.  DSA keys must be ex‐
121             actly 1024 bits as specified by FIPS 186-2.  For ECDSA keys, the
122             -b flag determines the key length by selecting from one of three
123             elliptic curve sizes: 256, 384 or 521 bits.  Attempting to use
124             bit lengths other than these three values for ECDSA keys will
125             fail.  ECDSA-SK, Ed25519 and Ed25519-SK keys have a fixed length
126             and the -b flag will be ignored.
127
128     -C comment
129             Provides a new comment.
130
131     -c      Requests changing the comment in the private and public key
132             files.  The program will prompt for the file containing the pri‐
133             vate keys, for the passphrase if the key has one, and for the new
134             comment.
135
136     -D pkcs11
137             Download the public keys provided by the PKCS#11 shared library
138             pkcs11.  When used in combination with -s, this option indicates
139             that a CA key resides in a PKCS#11 token (see the CERTIFICATES
140             section for details).
141
142     -E fingerprint_hash
143             Specifies the hash algorithm used when displaying key finger‐
144             prints.  Valid options are: “md5” and “sha256”.  The default is
145             “sha256”.
146
147     -e      This option will read a private or public OpenSSH key file and
148             print to stdout a public key in one of the formats specified by
149             the -m option.  The default export format is “RFC4716”.  This op‐
150             tion allows exporting OpenSSH keys for use by other programs, in‐
151             cluding several commercial SSH implementations.
152
153     -F hostname | [hostname]:port
154             Search for the specified hostname (with optional port number) in
155             a known_hosts file, listing any occurrences found.  This option
156             is useful to find hashed host names or addresses and may also be
157             used in conjunction with the -H option to print found keys in a
158             hashed format.
159
160     -f filename
161             Specifies the filename of the key file.
162
163     -g      Use generic DNS format when printing fingerprint resource records
164             using the -r command.
165
166     -H      Hash a known_hosts file.  This replaces all hostnames and ad‐
167             dresses with hashed representations within the specified file;
168             the original content is moved to a file with a .old suffix.
169             These hashes may be used normally by ssh and sshd, but they do
170             not reveal identifying information should the file's contents be
171             disclosed.  This option will not modify existing hashed hostnames
172             and is therefore safe to use on files that mix hashed and non-
173             hashed names.
174
175     -h      When signing a key, create a host certificate instead of a user
176             certificate.  See the CERTIFICATES section for details.
177
178     -I certificate_identity
179             Specify the key identity when signing a public key.  See the
180             CERTIFICATES section for details.
181
182     -i      This option will read an unencrypted private (or public) key file
183             in the format specified by the -m option and print an OpenSSH
184             compatible private (or public) key to stdout.  This option allows
185             importing keys from other software, including several commercial
186             SSH implementations.  The default import format is “RFC4716”.
187
188     -K      Download resident keys from a FIDO authenticator.  Public and
189             private key files will be written to the current directory for
190             each downloaded key.  If multiple FIDO authenticators are at‐
191             tached, keys will be downloaded from the first touched authenti‐
192             cator.  See the FIDO AUTHENTICATOR section for more information.
193
194     -k      Generate a KRL file.  In this mode, ssh-keygen will generate a
195             KRL file at the location specified via the -f flag that revokes
196             every key or certificate presented on the command line.
197             Keys/certificates to be revoked may be specified by public key
198             file or using the format described in the KEY REVOCATION LISTS
199             section.
200
201     -L      Prints the contents of one or more certificates.
202
203     -l      Show fingerprint of specified public key file.  For RSA and DSA
204             keys ssh-keygen tries to find the matching public key file and
205             prints its fingerprint.  If combined with -v, a visual ASCII art
206             representation of the key is supplied with the fingerprint.
207
208     -M generate
209             Generate candidate Diffie-Hellman Group Exchange (DH-GEX) parame‐
210             ters for eventual use by the ‘diffie-hellman-group-exchange-*’
211             key exchange methods.  The numbers generated by this operation
212             must be further screened before use.  See the MODULI GENERATION
213             section for more information.
214
215     -M screen
216             Screen candidate parameters for Diffie-Hellman Group Exchange.
217             This will accept a list of candidate numbers and test that they
218             are safe (Sophie Germain) primes with acceptable group genera‐
219             tors.  The results of this operation may be added to the
220             /etc/ssh/moduli file.  See the MODULI GENERATION section for more
221             information.
222
223     -m key_format
224             Specify a key format for key generation, the -i (import), -e (ex‐
225             port) conversion options, and the -p change passphrase operation.
226             The latter may be used to convert between OpenSSH private key and
227             PEM private key formats.  The supported key formats are:
228             “RFC4716” (RFC 4716/SSH2 public or private key), “PKCS8” (PKCS8
229             public or private key) or “PEM” (PEM public key).  By default
230             OpenSSH will write newly-generated private keys in its own for‐
231             mat, but when converting public keys for export the default for‐
232             mat is “RFC4716”.  Setting a format of “PEM” when generating or
233             updating a supported private key type will cause the key to be
234             stored in the legacy PEM private key format.
235
236     -N new_passphrase
237             Provides the new passphrase.
238
239     -n principals
240             Specify one or more principals (user or host names) to be in‐
241             cluded in a certificate when signing a key.  Multiple principals
242             may be specified, separated by commas.  See the CERTIFICATES sec‐
243             tion for details.
244
245     -O option
246             Specify a key/value option.  These are specific to the operation
247             that ssh-keygen has been requested to perform.
248
249             When signing certificates, one of the options listed in the
250             CERTIFICATES section may be specified here.
251
252             When performing moduli generation or screening, one of the op‐
253             tions listed in the MODULI GENERATION section may be specified.
254
255             When generating FIDO authenticator-backed keys, the options
256             listed in the FIDO AUTHENTICATOR section may be specified.
257
258             When performing signature-related options using the -Y flag, the
259             following options are accepted:
260
261             hashalg=algorithm
262                     Selects the hash algorithm to use for hashing the message
263                     to be signed.  Valid algorithms are “sha256” and
264                     “sha512.” The default is “sha512.”
265
266             print-pubkey
267                     Print the full public key to standard output after signa‐
268                     ture verification.
269
270             verify-time=timestamp
271                     Specifies a time to use when validating signatures in‐
272                     stead of the current time.  The time may be specified as
273                     a date or time in the YYYYMMDD[Z] or in YYYYMMD‐
274                     DHHMM[SS][Z] formats.  Dates and times will be inter‐
275                     preted in the current system time zone unless suffixed
276                     with a Z character, which causes them to be interpreted
277                     in the UTC time zone.
278
279             When generating SSHFP DNS records from public keys using the -r
280             flag, the following options are accepted:
281
282             hashalg=algorithm
283                     Selects a hash algorithm to use when printing SSHFP
284                     records using the -D flag.  Valid algorithms are “sha1”
285                     and “sha256”.  The default is to print both.
286
287             The -O option may be specified multiple times.
288
289     -P passphrase
290             Provides the (old) passphrase.
291
292     -p      Requests changing the passphrase of a private key file instead of
293             creating a new private key.  The program will prompt for the file
294             containing the private key, for the old passphrase, and twice for
295             the new passphrase.
296
297     -Q      Test whether keys have been revoked in a KRL.  If the -l option
298             is also specified then the contents of the KRL will be printed.
299
300     -q      Silence ssh-keygen.
301
302     -R hostname | [hostname]:port
303             Removes all keys belonging to the specified hostname (with op‐
304             tional port number) from a known_hosts file.  This option is use‐
305             ful to delete hashed hosts (see the -H option above).
306
307     -r hostname
308             Print the SSHFP fingerprint resource record named hostname for
309             the specified public key file.
310
311     -s ca_key
312             Certify (sign) a public key using the specified CA key.  See the
313             CERTIFICATES section for details.
314
315             When generating a KRL, -s specifies a path to a CA public key
316             file used to revoke certificates directly by key ID or serial
317             number.  See the KEY REVOCATION LISTS section for details.
318
319     -t dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa
320             Specifies the type of key to create.  The possible values are
321             “dsa”, “ecdsa”, “ecdsa-sk”, “ed25519”, “ed25519-sk”, or “rsa”.
322
323             This flag may also be used to specify the desired signature type
324             when signing certificates using an RSA CA key.  The available RSA
325             signature variants are “ssh-rsa” (SHA1 signatures, not recom‐
326             mended), “rsa-sha2-256”, and “rsa-sha2-512” (the default).
327
328     -U      When used in combination with -s or -Y sign, this option indi‐
329             cates that a CA key resides in a ssh-agent(1).  See the
330             CERTIFICATES section for more information.
331
332     -u      Update a KRL.  When specified with -k, keys listed via the com‐
333             mand line are added to the existing KRL rather than a new KRL be‐
334             ing created.
335
336     -V validity_interval
337             Specify a validity interval when signing a certificate.  A valid‐
338             ity interval may consist of a single time, indicating that the
339             certificate is valid beginning now and expiring at that time, or
340             may consist of two times separated by a colon to indicate an ex‐
341             plicit time interval.
342
343             The start time may be specified as:
344             The string “always” to indicate the certificate has no speci‐
345                 fied start time.
346             A date or time in the system time zone formatted as YYYYMMDD
347                 or YYYYMMDDHHMM[SS].
348             A date or time in the UTC time zone as YYYYMMDDZ or YYYYMMD‐
349                 DHHMM[SS]Z.
350             A relative time before the current system time consisting of
351                 a minus sign followed by an interval in the format described
352                 in the TIME FORMATS section of sshd_config(5).
353             A raw seconds since epoch (Jan 1 1970 00:00:00 UTC) as a
354                 hexadecimal number beginning with “0x”.
355
356             The end time may be specified similarly to the start time:
357             The string “forever” to indicate the certificate has no spec‐
358                 ified end time.
359             A date or time in the system time zone formatted as YYYYMMDD
360                 or YYYYMMDDHHMM[SS].
361             A date or time in the UTC time zone as YYYYMMDDZ or YYYYMMD‐
362                 DHHMM[SS]Z.
363             A relative time after the current system time consisting of a
364                 plus sign followed by an interval in the format described in
365                 the TIME FORMATS section of sshd_config(5).
366             A raw seconds since epoch (Jan 1 1970 00:00:00 UTC) as a
367                 hexadecimal number beginning with “0x”.
368
369             For example:
370
371             +52w1d  Valid from now to 52 weeks and one day from now.
372
373             -4w:+4w
374                     Valid from four weeks ago to four weeks from now.
375
376             20100101123000:20110101123000
377                     Valid from 12:30 PM, January 1st, 2010 to 12:30 PM, Janu‐
378                     ary 1st, 2011.
379
380             20100101123000Z:20110101123000Z
381                     Similar, but interpreted in the UTC time zone rather than
382                     the system time zone.
383
384             -1d:20110101
385                     Valid from yesterday to midnight, January 1st, 2011.
386
387             0x1:0x2000000000
388                     Valid from roughly early 1970 to May 2033.
389
390             -1m:forever
391                     Valid from one minute ago and never expiring.
392
393     -v      Verbose mode.  Causes ssh-keygen to print debugging messages
394             about its progress.  This is helpful for debugging moduli genera‐
395             tion.  Multiple -v options increase the verbosity.  The maximum
396             is 3.
397
398     -w provider
399             Specifies a path to a library that will be used when creating
400             FIDO authenticator-hosted keys, overriding the default of using
401             the internal USB HID support.
402
403     -Y find-principals
404             Find the principal(s) associated with the public key of a signa‐
405             ture, provided using the -s flag in an authorized signers file
406             provided using the -f flag.  The format of the allowed signers
407             file is documented in the ALLOWED SIGNERS section below.  If one
408             or more matching principals are found, they are returned on stan‐
409             dard output.
410
411     -Y match-principals
412             Find principal matching the principal name provided using the -I
413             flag in the authorized signers file specified using the -f flag.
414             If one or more matching principals are found, they are returned
415             on standard output.
416
417     -Y check-novalidate
418             Checks that a signature generated using ssh-keygen -Y sign has a
419             valid structure.  This does not validate if a signature comes
420             from an authorized signer.  When testing a signature, ssh-keygen
421             accepts a message on standard input and a signature namespace us‐
422             ing -n.  A file containing the corresponding signature must also
423             be supplied using the -s flag.  Successful testing of the signa‐
424             ture is signalled by ssh-keygen returning a zero exit status.
425
426     -Y sign
427             Cryptographically sign a file or some data using a SSH key.  When
428             signing, ssh-keygen accepts zero or more files to sign on the
429             command-line - if no files are specified then ssh-keygen will
430             sign data presented on standard input.  Signatures are written to
431             the path of the input file with “.sig” appended, or to standard
432             output if the message to be signed was read from standard input.
433
434             The key used for signing is specified using the -f option and may
435             refer to either a private key, or a public key with the private
436             half available via ssh-agent(1).  An additional signature name‐
437             space, used to prevent signature confusion across different do‐
438             mains of use (e.g. file signing vs email signing) must be pro‐
439             vided via the -n flag.  Namespaces are arbitrary strings, and may
440             include: “file” for file signing, “email” for email signing.  For
441             custom uses, it is recommended to use names following a NAME‐
442             SPACE@YOUR.DOMAIN pattern to generate unambiguous namespaces.
443
444     -Y verify
445             Request to verify a signature generated using ssh-keygen -Y sign
446             as described above.  When verifying a signature, ssh-keygen ac‐
447             cepts a message on standard input and a signature namespace using
448             -n.  A file containing the corresponding signature must also be
449             supplied using the -s flag, along with the identity of the signer
450             using -I and a list of allowed signers via the -f flag.  The for‐
451             mat of the allowed signers file is documented in the ALLOWED
452             SIGNERS section below.  A file containing revoked keys can be
453             passed using the -r flag.  The revocation file may be a KRL or a
454             one-per-line list of public keys.  Successful verification by an
455             authorized signer is signalled by ssh-keygen returning a zero
456             exit status.
457
458     -y      This option will read a private OpenSSH format file and print an
459             OpenSSH public key to stdout.
460
461     -Z cipher
462             Specifies the cipher to use for encryption when writing an
463             OpenSSH-format private key file.  The list of available ciphers
464             may be obtained using "ssh -Q cipher".  The default is
465             “aes256-ctr”.
466
467     -z serial_number
468             Specifies a serial number to be embedded in the certificate to
469             distinguish this certificate from others from the same CA.  If
470             the serial_number is prefixed with a ‘+’ character, then the se‐
471             rial number will be incremented for each certificate signed on a
472             single command-line.  The default serial number is zero.
473
474             When generating a KRL, the -z flag is used to specify a KRL ver‐
475             sion number.
476

MODULI GENERATION

478     ssh-keygen may be used to generate groups for the Diffie-Hellman Group
479     Exchange (DH-GEX) protocol.  Generating these groups is a two-step
480     process: first, candidate primes are generated using a fast, but memory
481     intensive process.  These candidate primes are then tested for suitabil‐
482     ity (a CPU-intensive process).
483
484     Generation of primes is performed using the -M generate option.  The de‐
485     sired length of the primes may be specified by the -O bits option.  For
486     example:
487
488           # ssh-keygen -M generate -O bits=2048 moduli-2048.candidates
489
490     By default, the search for primes begins at a random point in the desired
491     length range.  This may be overridden using the -O start option, which
492     specifies a different start point (in hex).
493
494     Once a set of candidates have been generated, they must be screened for
495     suitability.  This may be performed using the -M screen option.  In this
496     mode ssh-keygen will read candidates from standard input (or a file spec‐
497     ified using the -f option).  For example:
498
499           # ssh-keygen -M screen -f moduli-2048.candidates moduli-2048
500
501     By default, each candidate will be subjected to 100 primality tests.
502     This may be overridden using the -O prime-tests option.  The DH generator
503     value will be chosen automatically for the prime under consideration.  If
504     a specific generator is desired, it may be requested using the -O
505     generator option.  Valid generator values are 2, 3, and 5.
506
507     Screened DH groups may be installed in /etc/ssh/moduli.  It is important
508     that this file contains moduli of a range of bit lengths.
509
510     A number of options are available for moduli generation and screening via
511     the -O flag:
512
513     lines=number
514             Exit after screening the specified number of lines while perform‐
515             ing DH candidate screening.
516
517     start-line=line-number
518             Start screening at the specified line number while performing DH
519             candidate screening.
520
521     checkpoint=filename
522             Write the last line processed to the specified file while per‐
523             forming DH candidate screening.  This will be used to skip lines
524             in the input file that have already been processed if the job is
525             restarted.
526
527     memory=mbytes
528             Specify the amount of memory to use (in megabytes) when generat‐
529             ing candidate moduli for DH-GEX.
530
531     start=hex-value
532             Specify start point (in hex) when generating candidate moduli for
533             DH-GEX.
534
535     generator=value
536             Specify desired generator (in decimal) when testing candidate
537             moduli for DH-GEX.
538

CERTIFICATES

540     ssh-keygen supports signing of keys to produce certificates that may be
541     used for user or host authentication.  Certificates consist of a public
542     key, some identity information, zero or more principal (user or host)
543     names and a set of options that are signed by a Certification Authority
544     (CA) key.  Clients or servers may then trust only the CA key and verify
545     its signature on a certificate rather than trusting many user/host keys.
546     Note that OpenSSH certificates are a different, and much simpler, format
547     to the X.509 certificates used in ssl(8).
548
549     ssh-keygen supports two types of certificates: user and host.  User cer‐
550     tificates authenticate users to servers, whereas host certificates au‐
551     thenticate server hosts to users.  To generate a user certificate:
552
553           $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
554
555     The resultant certificate will be placed in /path/to/user_key-cert.pub.
556     A host certificate requires the -h option:
557
558           $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
559
560     The host certificate will be output to /path/to/host_key-cert.pub.
561
562     It is possible to sign using a CA key stored in a PKCS#11 token by pro‐
563     viding the token library using -D and identifying the CA key by providing
564     its public half as an argument to -s:
565
566           $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub
567
568     Similarly, it is possible for the CA key to be hosted in a ssh-agent(1).
569     This is indicated by the -U flag and, again, the CA key must be identi‐
570     fied by its public half.
571
572           $ ssh-keygen -Us ca_key.pub -I key_id user_key.pub
573
574     In all cases, key_id is a "key identifier" that is logged by the server
575     when the certificate is used for authentication.
576
577     Certificates may be limited to be valid for a set of principal
578     (user/host) names.  By default, generated certificates are valid for all
579     users or hosts.  To generate a certificate for a specified set of princi‐
580     pals:
581
582           $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
583           $ ssh-keygen -s ca_key -I key_id -h -n host.domain host_key.pub
584
585     Additional limitations on the validity and use of user certificates may
586     be specified through certificate options.  A certificate option may dis‐
587     able features of the SSH session, may be valid only when presented from
588     particular source addresses or may force the use of a specific command.
589
590     The options that are valid for user certificates are:
591
592     clear   Clear all enabled permissions.  This is useful for clearing the
593             default set of permissions so permissions may be added individu‐
594             ally.
595
596     critical:name[=contents]
597     extension:name[=contents]
598             Includes an arbitrary certificate critical option or extension.
599             The specified name should include a domain suffix, e.g.
600             “name@example.com”.  If contents is specified then it is included
601             as the contents of the extension/option encoded as a string, oth‐
602             erwise the extension/option is created with no contents (usually
603             indicating a flag).  Extensions may be ignored by a client or
604             server that does not recognise them, whereas unknown critical op‐
605             tions will cause the certificate to be refused.
606
607     force-command=command
608             Forces the execution of command instead of any shell or command
609             specified by the user when the certificate is used for authenti‐
610             cation.
611
612     no-agent-forwarding
613             Disable ssh-agent(1) forwarding (permitted by default).
614
615     no-port-forwarding
616             Disable port forwarding (permitted by default).
617
618     no-pty  Disable PTY allocation (permitted by default).
619
620     no-user-rc
621             Disable execution of ~/.ssh/rc by sshd(8) (permitted by default).
622
623     no-x11-forwarding
624             Disable X11 forwarding (permitted by default).
625
626     permit-agent-forwarding
627             Allows ssh-agent(1) forwarding.
628
629     permit-port-forwarding
630             Allows port forwarding.
631
632     permit-pty
633             Allows PTY allocation.
634
635     permit-user-rc
636             Allows execution of ~/.ssh/rc by sshd(8).
637
638     permit-X11-forwarding
639             Allows X11 forwarding.
640
641     no-touch-required
642             Do not require signatures made using this key include demonstra‐
643             tion of user presence (e.g. by having the user touch the authen‐
644             ticator).  This option only makes sense for the FIDO authentica‐
645             tor algorithms ecdsa-sk and ed25519-sk.
646
647     source-address=address_list
648             Restrict the source addresses from which the certificate is con‐
649             sidered valid.  The address_list is a comma-separated list of one
650             or more address/netmask pairs in CIDR format.
651
652     verify-required
653             Require signatures made using this key indicate that the user was
654             first verified.  This option only makes sense for the FIDO au‐
655             thenticator algorithms ecdsa-sk and ed25519-sk.  Currently PIN
656             authentication is the only supported verification method, but
657             other methods may be supported in the future.
658
659     At present, no standard options are valid for host keys.
660
661     Finally, certificates may be defined with a validity lifetime.  The -V
662     option allows specification of certificate start and end times.  A cer‐
663     tificate that is presented at a time outside this range will not be con‐
664     sidered valid.  By default, certificates are valid from the UNIX Epoch to
665     the distant future.
666
667     For certificates to be used for user or host authentication, the CA pub‐
668     lic key must be trusted by sshd(8) or ssh(1).  Refer to those manual
669     pages for details.
670

FIDO AUTHENTICATOR

672     ssh-keygen is able to generate FIDO authenticator-backed keys, after
673     which they may be used much like any other key type supported by OpenSSH,
674     so long as the hardware authenticator is attached when the keys are used.
675     FIDO authenticators generally require the user to explicitly authorise
676     operations by touching or tapping them.  FIDO keys consist of two parts:
677     a key handle part stored in the private key file on disk, and a per-de‐
678     vice private key that is unique to each FIDO authenticator and that can‐
679     not be exported from the authenticator hardware.  These are combined by
680     the hardware at authentication time to derive the real key that is used
681     to sign authentication challenges.  Supported key types are ecdsa-sk and
682     ed25519-sk.
683
684     The options that are valid for FIDO keys are:
685
686     application
687             Override the default FIDO application/origin string of “ssh:”.
688             This may be useful when generating host or domain-specific resi‐
689             dent keys.  The specified application string must begin with
690             “ssh:”.
691
692     challenge=path
693             Specifies a path to a challenge string that will be passed to the
694             FIDO authenticator during key generation.  The challenge string
695             may be used as part of an out-of-band protocol for key enrollment
696             (a random challenge is used by default).
697
698     device  Explicitly specify a fido(4) device to use, rather than letting
699             the authenticator middleware select one.
700
701     no-touch-required
702             Indicate that the generated private key should not require touch
703             events (user presence) when making signatures.  Note that sshd(8)
704             will refuse such signatures by default, unless overridden via an
705             authorized_keys option.
706
707     resident
708             Indicate that the key handle should be stored on the FIDO authen‐
709             ticator itself.  This makes it easier to use the authenticator on
710             multiple computers.  Resident keys may be supported on FIDO2 au‐
711             thenticators and typically require that a PIN be set on the au‐
712             thenticator prior to generation.  Resident keys may be loaded off
713             the authenticator using ssh-add(1).  Storing both parts of a key
714             on a FIDO authenticator increases the likelihood of an attacker
715             being able to use a stolen authenticator device.
716
717     user    A username to be associated with a resident key, overriding the
718             empty default username.  Specifying a username may be useful when
719             generating multiple resident keys for the same application name.
720
721     verify-required
722             Indicate that this private key should require user verification
723             for each signature.  Not all FIDO authenticators support this op‐
724             tion.  Currently PIN authentication is the only supported verifi‐
725             cation method, but other methods may be supported in the future.
726
727     write-attestation=path
728             May be used at key generation time to record the attestation data
729             returned from FIDO authenticators during key generation.  This
730             information is potentially sensitive.  By default, this informa‐
731             tion is discarded.
732

KEY REVOCATION LISTS

734     ssh-keygen is able to manage OpenSSH format Key Revocation Lists (KRLs).
735     These binary files specify keys or certificates to be revoked using a
736     compact format, taking as little as one bit per certificate if they are
737     being revoked by serial number.
738
739     KRLs may be generated using the -k flag.  This option reads one or more
740     files from the command line and generates a new KRL.  The files may ei‐
741     ther contain a KRL specification (see below) or public keys, listed one
742     per line.  Plain public keys are revoked by listing their hash or con‐
743     tents in the KRL and certificates revoked by serial number or key ID (if
744     the serial is zero or not available).
745
746     Revoking keys using a KRL specification offers explicit control over the
747     types of record used to revoke keys and may be used to directly revoke
748     certificates by serial number or key ID without having the complete orig‐
749     inal certificate on hand.  A KRL specification consists of lines contain‐
750     ing one of the following directives followed by a colon and some direc‐
751     tive-specific information.
752
753     serial: serial_number[-serial_number]
754             Revokes a certificate with the specified serial number.  Serial
755             numbers are 64-bit values, not including zero and may be ex‐
756             pressed in decimal, hex or octal.  If two serial numbers are
757             specified separated by a hyphen, then the range of serial numbers
758             including and between each is revoked.  The CA key must have been
759             specified on the ssh-keygen command line using the -s option.
760
761     id: key_id
762             Revokes a certificate with the specified key ID string.  The CA
763             key must have been specified on the ssh-keygen command line using
764             the -s option.
765
766     key: public_key
767             Revokes the specified key.  If a certificate is listed, then it
768             is revoked as a plain public key.
769
770     sha1: public_key
771             Revokes the specified key by including its SHA1 hash in the KRL.
772
773     sha256: public_key
774             Revokes the specified key by including its SHA256 hash in the
775             KRL.  KRLs that revoke keys by SHA256 hash are not supported by
776             OpenSSH versions prior to 7.9.
777
778     hash: fingerprint
779             Revokes a key using a fingerprint hash, as obtained from a
780             sshd(8) authentication log message or the ssh-keygen -l flag.
781             Only SHA256 fingerprints are supported here and resultant KRLs
782             are not supported by OpenSSH versions prior to 7.9.
783
784     KRLs may be updated using the -u flag in addition to -k.  When this op‐
785     tion is specified, keys listed via the command line are merged into the
786     KRL, adding to those already there.
787
788     It is also possible, given a KRL, to test whether it revokes a particular
789     key (or keys).  The -Q flag will query an existing KRL, testing each key
790     specified on the command line.  If any key listed on the command line has
791     been revoked (or an error encountered) then ssh-keygen will exit with a
792     non-zero exit status.  A zero exit status will only be returned if no key
793     was revoked.
794

ALLOWED SIGNERS

796     When verifying signatures, ssh-keygen uses a simple list of identities
797     and keys to determine whether a signature comes from an authorized
798     source.  This "allowed signers" file uses a format patterned after the
799     AUTHORIZED_KEYS FILE FORMAT described in sshd(8).  Each line of the file
800     contains the following space-separated fields: principals, options, key‐
801     type, base64-encoded key.  Empty lines and lines starting with a ‘#’ are
802     ignored as comments.
803
804     The principals field is a pattern-list (see PATTERNS in ssh_config(5))
805     consisting of one or more comma-separated USER@DOMAIN identity patterns
806     that are accepted for signing.  When verifying, the identity presented
807     via the -I option must match a principals pattern in order for the corre‐
808     sponding key to be considered acceptable for verification.
809
810     The options (if present) consist of comma-separated option specifica‐
811     tions.  No spaces are permitted, except within double quotes.  The fol‐
812     lowing option specifications are supported (note that option keywords are
813     case-insensitive):
814
815     cert-authority
816             Indicates that this key is accepted as a certificate authority
817             (CA) and that certificates signed by this CA may be accepted for
818             verification.
819
820     namespaces=namespace-list
821             Specifies a pattern-list of namespaces that are accepted for this
822             key.  If this option is present, the signature namespace embedded
823             in the signature object and presented on the verification com‐
824             mand-line must match the specified list before the key will be
825             considered acceptable.
826
827     valid-after=timestamp
828             Indicates that the key is valid for use at or after the specified
829             timestamp, which may be a date or time in the YYYYMMDD[Z] or
830             YYYYMMDDHHMM[SS][Z] formats.  Dates and times will be interpreted
831             in the current system time zone unless suffixed with a Z charac‐
832             ter, which causes them to be interpreted in the UTC time zone.
833
834     valid-before=timestamp
835             Indicates that the key is valid for use at or before the speci‐
836             fied timestamp.
837
838     When verifying signatures made by certificates, the expected principal
839     name must match both the principals pattern in the allowed signers file
840     and the principals embedded in the certificate itself.
841
842     An example allowed signers file:
843
844        # Comments allowed at start of line
845        user1@example.com,user2@example.com ssh-rsa AAAAX1...
846        # A certificate authority, trusted for all principals in a domain.
847        *@example.com cert-authority ssh-ed25519 AAAB4...
848        # A key that is accepted only for file signing.
849        user2@example.com namespaces="file" ssh-ed25519 AAA41...
850

ENVIRONMENT

852     SSH_SK_PROVIDER
853             Specifies a path to a library that will be used when loading any
854             FIDO authenticator-hosted keys, overriding the default of using
855             the built-in USB HID support.
856

FILES

858     ~/.ssh/id_dsa
859     ~/.ssh/id_ecdsa
860     ~/.ssh/id_ecdsa_sk
861     ~/.ssh/id_ed25519
862     ~/.ssh/id_ed25519_sk
863     ~/.ssh/id_rsa
864             Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, au‐
865             thenticator-hosted Ed25519 or RSA authentication identity of the
866             user.  This file should not be readable by anyone but the user.
867             It is possible to specify a passphrase when generating the key;
868             that passphrase will be used to encrypt the private part of this
869             file using 128-bit AES.  This file is not automatically accessed
870             by ssh-keygen but it is offered as the default file for the pri‐
871             vate key.  ssh(1) will read this file when a login attempt is
872             made.
873
874     ~/.ssh/id_dsa.pub
875     ~/.ssh/id_ecdsa.pub
876     ~/.ssh/id_ecdsa_sk.pub
877     ~/.ssh/id_ed25519.pub
878     ~/.ssh/id_ed25519_sk.pub
879     ~/.ssh/id_rsa.pub
880             Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, au‐
881             thenticator-hosted Ed25519 or RSA public key for authentication.
882             The contents of this file should be added to
883             ~/.ssh/authorized_keys on all machines where the user wishes to
884             log in using public key authentication.  There is no need to keep
885             the contents of this file secret.
886
887     /etc/ssh/moduli
888             Contains Diffie-Hellman groups used for DH-GEX.  The file format
889             is described in moduli(5).
890

SEE ALSO

892     ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8)
893
894     The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006.
895

AUTHORS

897     OpenSSH is a derivative of the original and free ssh 1.2.12 release by
898     Tatu Ylonen.  Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
899     de Raadt and Dug Song removed many bugs, re-added newer features and cre‐
900     ated OpenSSH.  Markus Friedl contributed the support for SSH protocol
901     versions 1.5 and 2.0.
902
903BSD                            February 10, 2023                           BSD
Impressum