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

DESCRIPTION

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

MODULI GENERATION

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

CERTIFICATES

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

KEY REVOCATION LISTS

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

ALLOWED SIGNERS

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

ENVIRONMENT

782     SSH_SK_PROVIDER
783             Specifies a path to a library that will be used when loading any
784             FIDO authenticator-hosted keys, overriding the default of using
785             the built-in USB HID support.
786

FILES

788     ~/.ssh/id_dsa
789     ~/.ssh/id_ecdsa
790     ~/.ssh/id_ecdsa_sk
791     ~/.ssh/id_ed25519
792     ~/.ssh/id_ed25519_sk
793     ~/.ssh/id_rsa
794             Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, au‐
795             thenticator-hosted Ed25519 or RSA authentication identity of the
796             user.  This file should not be readable by anyone but the user.
797             It is possible to specify a passphrase when generating the key;
798             that passphrase will be used to encrypt the private part of this
799             file using 128-bit AES.  This file is not automatically accessed
800             by ssh-keygen but it is offered as the default file for the pri‐
801             vate key.  ssh(1) will read this file when a login attempt is
802             made.
803
804     ~/.ssh/id_dsa.pub
805     ~/.ssh/id_ecdsa.pub
806     ~/.ssh/id_ecdsa_sk.pub
807     ~/.ssh/id_ed25519.pub
808     ~/.ssh/id_ed25519_sk.pub
809     ~/.ssh/id_rsa.pub
810             Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, au‐
811             thenticator-hosted Ed25519 or RSA public key for authentication.
812             The contents of this file should be added to
813             ~/.ssh/authorized_keys on all machines where the user wishes to
814             log in using public key authentication.  There is no need to keep
815             the contents of this file secret.
816
817     /etc/ssh/moduli
818             Contains Diffie-Hellman groups used for DH-GEX.  The file format
819             is described in moduli(5).
820

SEE ALSO

822     ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8)
823
824     The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006.
825

AUTHORS

827     OpenSSH is a derivative of the original and free ssh 1.2.12 release by
828     Tatu Ylonen.  Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
829     de Raadt and Dug Song removed many bugs, re-added newer features and cre‐
830     ated OpenSSH.  Markus Friedl contributed the support for SSH protocol
831     versions 1.5 and 2.0.
832
833BSD                             August 11, 2021                            BSD
Impressum