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]
11     ssh-keygen -p [-a rounds] [-f keyfile] [-m format] [-N new_passphrase]
12                [-P old_passphrase]
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
46     invoked 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
67     series of words, punctuation, numbers, whitespace, or any string of char‐
68     acters you want.  Good passphrases are 10-30 characters long, are not
69     simple sentences or otherwise easily guessable (English prose has only
70     1-2 bits of entropy per character, and provides very bad passphrases),
71     and contain a mix of upper and lowercase letters, numbers, and non-
72     alphanumeric characters.  The passphrase can be changed later by using
73     the -p 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) rounds used.  Higher numbers result
107             in slower passphrase verification and increased resistance to
108             brute-force password cracking (should the keys be stolen).  The
109             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
118             exactly 1024 bits as specified by FIPS 186-2.  For ECDSA keys,
119             the -b flag determines the key length by selecting from one of
120             three elliptic curve sizes: 256, 384 or 521 bits.  Attempting to
121             use 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
147             option allows exporting OpenSSH keys for use by other programs,
148             including 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
164             addresses 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
188             attached, keys will be downloaded from the first touched authen‐
189             ticator.
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/gsissh/moduli file.  See the MODULI GENERATION section for
218             more information.
219
220     -m key_format
221             Specify a key format for key generation, the -i (import), -e
222             (export) conversion options, and the -p change passphrase opera‐
223             tion.  The latter may be used to convert between OpenSSH private
224             key and 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
238             included in a certificate when signing a key.  Multiple princi‐
239             pals 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
250             options 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
259                     domain-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
274                     require 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
280                     authenticator 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
320             optional port number) from a known_hosts file.  This option is
321             useful 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
350             being 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
357             explicit 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
369             expiry 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
401             using -n.  A file containing the corresponding signature must
402             also be supplied using the -s flag.  Successful testing of the
403             signature is signalled by ssh-keygen returning a zero exit sta‐
404             tus.
405
406     -Y sign
407             Cryptographically sign a file or some data using a SSH key.  When
408             signing, ssh-keygen accepts zero or more files to sign on the
409             command-line - if no files are specified then ssh-keygen will
410             sign data presented on standard input.  Signatures are written to
411             the path of the input file with “.sig” appended, or to standard
412             output if the message to be signed was read from standard input.
413
414             The key used for signing is specified using the -f option and may
415             refer to either a private key, or a public key with the private
416             half available via ssh-agent(1).  An additional signature names‐
417             pace, used to prevent signature confusion across different
418             domains of use (e.g. file signing vs email signing) must be pro‐
419             vided via the -n flag.  Namespaces are arbitrary strings, and may
420             include: “file” for file signing, “email” for email signing.  For
421             custom uses, it is recommended to use names following a NAMES‐
422             PACE@YOUR.DOMAIN pattern to generate unambiguous namespaces.
423
424     -Y verify
425             Request to verify a signature generated using ssh-keygen -Y sign
426             as described above.  When verifying a signature, ssh-keygen
427             accepts a message on standard input and a signature namespace
428             using -n.  A file containing the corresponding signature must
429             also be supplied using the -s flag, along with the identity of
430             the signer using -I and a list of allowed signers via the -f
431             flag.  The format of the allowed signers file is documented in
432             the ALLOWED SIGNERS section below.  A file containing revoked
433             keys can be passed using the -r flag.  The revocation file may be
434             a KRL or a one-per-line list of public keys.  Successful verifi‐
435             cation by an authorized signer is signalled by ssh-keygen return‐
436             ing a zero exit status.
437
438     -y      This option will read a private OpenSSH format file and print an
439             OpenSSH public key to stdout.
440
441     -z serial_number
442             Specifies a serial number to be embedded in the certificate to
443             distinguish this certificate from others from the same CA.  If
444             the serial_number is prefixed with a ‘+’ character, then the
445             serial number will be incremented for each certificate signed on
446             a single command-line.  The default serial number is zero.
447
448             When generating a KRL, the -z flag is used to specify a KRL ver‐
449             sion number.
450

MODULI GENERATION

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

CERTIFICATES

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

KEY REVOCATION LISTS

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

ALLOWED SIGNERS

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

ENVIRONMENT

754     SSH_SK_PROVIDER
755             Specifies a path to a library that will be used when loading any
756             FIDO authenticator-hosted keys, overriding the default of using
757             the built-in USB HID support.
758

FILES

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

SEE ALSO

794     ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8)
795
796     The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006.
797

AUTHORS

799     OpenSSH is a derivative of the original and free ssh 1.2.12 release by
800     Tatu Ylonen.  Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
801     de Raadt and Dug Song removed many bugs, re-added newer features and cre‐
802     ated OpenSSH.  Markus Friedl contributed the support for SSH protocol
803     versions 1.5 and 2.0.
804
805BSD                            September 9, 2020                           BSD
Impressum