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 -s signature_file -f allowed_signers_file
36     ssh-keygen -Y check-novalidate -n namespace -s signature_file
37     ssh-keygen -Y sign -f key_file -n namespace file ...
38     ssh-keygen -Y verify -f allowed_signers_file -I signer_identity -n
39                namespace -s signature_file [-r revocation_file]
40

DESCRIPTION

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

MODULI GENERATION

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

CERTIFICATES

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

KEY REVOCATION LISTS

652     ssh-keygen is able to manage OpenSSH format Key Revocation Lists (KRLs).
653     These binary files specify keys or certificates to be revoked using a
654     compact format, taking as little as one bit per certificate if they are
655     being revoked by serial number.
656
657     KRLs may be generated using the -k flag.  This option reads one or more
658     files from the command line and generates a new KRL.  The files may ei‐
659     ther contain a KRL specification (see below) or public keys, listed one
660     per line.  Plain public keys are revoked by listing their hash or con‐
661     tents in the KRL and certificates revoked by serial number or key ID (if
662     the serial is zero or not available).
663
664     Revoking keys using a KRL specification offers explicit control over the
665     types of record used to revoke keys and may be used to directly revoke
666     certificates by serial number or key ID without having the complete orig‐
667     inal certificate on hand.  A KRL specification consists of lines contain‐
668     ing one of the following directives followed by a colon and some direc‐
669     tive-specific information.
670
671     serial: serial_number[-serial_number]
672             Revokes a certificate with the specified serial number.  Serial
673             numbers are 64-bit values, not including zero and may be ex‐
674             pressed in decimal, hex or octal.  If two serial numbers are
675             specified separated by a hyphen, then the range of serial numbers
676             including and between each is revoked.  The CA key must have been
677             specified on the ssh-keygen command line using the -s option.
678
679     id: key_id
680             Revokes a certificate with the specified key ID string.  The CA
681             key must have been specified on the ssh-keygen command line using
682             the -s option.
683
684     key: public_key
685             Revokes the specified key.  If a certificate is listed, then it
686             is revoked as a plain public key.
687
688     sha1: public_key
689             Revokes the specified key by including its SHA1 hash in the KRL.
690
691     sha256: public_key
692             Revokes the specified key by including its SHA256 hash in the
693             KRL.  KRLs that revoke keys by SHA256 hash are not supported by
694             OpenSSH versions prior to 7.9.
695
696     hash: fingerprint
697             Revokes a key using a fingerprint hash, as obtained from a
698             sshd(8) authentication log message or the ssh-keygen -l flag.
699             Only SHA256 fingerprints are supported here and resultant KRLs
700             are not supported by OpenSSH versions prior to 7.9.
701
702     KRLs may be updated using the -u flag in addition to -k.  When this op‐
703     tion is specified, keys listed via the command line are merged into the
704     KRL, adding to those already there.
705
706     It is also possible, given a KRL, to test whether it revokes a particular
707     key (or keys).  The -Q flag will query an existing KRL, testing each key
708     specified on the command line.  If any key listed on the command line has
709     been revoked (or an error encountered) then ssh-keygen will exit with a
710     non-zero exit status.  A zero exit status will only be returned if no key
711     was revoked.
712

ALLOWED SIGNERS

714     When verifying signatures, ssh-keygen uses a simple list of identities
715     and keys to determine whether a signature comes from an authorized
716     source.  This "allowed signers" file uses a format patterned after the
717     AUTHORIZED_KEYS FILE FORMAT described in sshd(8).  Each line of the file
718     contains the following space-separated fields: principals, options, key‐
719     type, base64-encoded key.  Empty lines and lines starting with a ‘#’ are
720     ignored as comments.
721
722     The principals field is a pattern-list (see PATTERNS in ssh_config(5))
723     consisting of one or more comma-separated USER@DOMAIN identity patterns
724     that are accepted for signing.  When verifying, the identity presented
725     via the -I option must match a principals pattern in order for the corre‐
726     sponding key to be considered acceptable for verification.
727
728     The options (if present) consist of comma-separated option specifica‐
729     tions.  No spaces are permitted, except within double quotes.  The fol‐
730     lowing option specifications are supported (note that option keywords are
731     case-insensitive):
732
733     cert-authority
734             Indicates that this key is accepted as a certificate authority
735             (CA) and that certificates signed by this CA may be accepted for
736             verification.
737
738     namespaces="namespace-list"
739             Specifies a pattern-list of namespaces that are accepted for this
740             key.  If this option is present, the signature namespace embedded
741             in the signature object and presented on the verification com‐
742             mand-line must match the specified list before the key will be
743             considered acceptable.
744
745     When verifying signatures made by certificates, the expected principal
746     name must match both the principals pattern in the allowed signers file
747     and the principals embedded in the certificate itself.
748
749     An example allowed signers file:
750
751        # Comments allowed at start of line
752        user1@example.com,user2@example.com ssh-rsa AAAAX1...
753        # A certificate authority, trusted for all principals in a domain.
754        *@example.com cert-authority ssh-ed25519 AAAB4...
755        # A key that is accepted only for file signing.
756        user2@example.com namespaces="file" ssh-ed25519 AAA41...
757

ENVIRONMENT

759     SSH_SK_PROVIDER
760             Specifies a path to a library that will be used when loading any
761             FIDO authenticator-hosted keys, overriding the default of using
762             the built-in USB HID support.
763

FILES

765     ~/.ssh/id_dsa
766     ~/.ssh/id_ecdsa
767     ~/.ssh/id_ecdsa_sk
768     ~/.ssh/id_ed25519
769     ~/.ssh/id_ed25519_sk
770     ~/.ssh/id_rsa
771             Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, au‐
772             thenticator-hosted Ed25519 or RSA authentication identity of the
773             user.  This file should not be readable by anyone but the user.
774             It is possible to specify a passphrase when generating the key;
775             that passphrase will be used to encrypt the private part of this
776             file using 128-bit AES.  This file is not automatically accessed
777             by ssh-keygen but it is offered as the default file for the pri‐
778             vate key.  ssh(1) will read this file when a login attempt is
779             made.
780
781     ~/.ssh/id_dsa.pub
782     ~/.ssh/id_ecdsa.pub
783     ~/.ssh/id_ecdsa_sk.pub
784     ~/.ssh/id_ed25519.pub
785     ~/.ssh/id_ed25519_sk.pub
786     ~/.ssh/id_rsa.pub
787             Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, au‐
788             thenticator-hosted Ed25519 or RSA public key for authentication.
789             The contents of this file should be added to
790             ~/.ssh/authorized_keys on all machines where the user wishes to
791             log in using public key authentication.  There is no need to keep
792             the contents of this file secret.
793
794     /etc/ssh/moduli
795             Contains Diffie-Hellman groups used for DH-GEX.  The file format
796             is described in moduli(5).
797

SEE ALSO

799     ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8)
800
801     The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006.
802

AUTHORS

804     OpenSSH is a derivative of the original and free ssh 1.2.12 release by
805     Tatu Ylonen.  Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
806     de Raadt and Dug Song removed many bugs, re-added newer features and cre‐
807     ated OpenSSH.  Markus Friedl contributed the support for SSH protocol
808     versions 1.5 and 2.0.
809
810BSD                            November 27, 2020                           BSD
Impressum