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

DESCRIPTION

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

MODULI GENERATION

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

CERTIFICATES

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

KEY REVOCATION LISTS

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

ALLOWED SIGNERS

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

ENVIRONMENT

734     SSH_SK_PROVIDER
735             Specifies a path to a library that will be used when loading any
736             FIDO authenticator-hosted keys, overriding the default of using
737             the built-in USB HID support.
738

FILES

740     ~/.ssh/id_dsa
741     ~/.ssh/id_ecdsa
742     ~/.ssh/id_ecdsa_sk
743     ~/.ssh/id_ed25519
744     ~/.ssh/id_ed25519_sk
745     ~/.ssh/id_rsa
746             Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519,
747             authenticator-hosted Ed25519 or RSA authentication identity of
748             the user.  This file should not be readable by anyone but the
749             user.  It is possible to specify a passphrase when generating the
750             key; that passphrase will be used to encrypt the private part of
751             this file using 128-bit AES.  This file is not automatically
752             accessed by ssh-keygen but it is offered as the default file for
753             the private key.  ssh(1) will read this file when a login attempt
754             is made.
755
756     ~/.ssh/id_dsa.pub
757     ~/.ssh/id_ecdsa.pub
758     ~/.ssh/id_ecdsa_sk.pub
759     ~/.ssh/id_ed25519.pub
760     ~/.ssh/id_ed25519_sk.pub
761     ~/.ssh/id_rsa.pub
762             Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519,
763             authenticator-hosted Ed25519 or RSA public key for authentica‐
764             tion.  The contents of this file should be added to
765             ~/.ssh/authorized_keys on all machines where the user wishes to
766             log in using public key authentication.  There is no need to keep
767             the contents of this file secret.
768
769     /etc/gsissh/moduli
770             Contains Diffie-Hellman groups used for DH-GEX.  The file format
771             is described in moduli(5).
772

SEE ALSO

774     ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8)
775
776     The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006.
777

AUTHORS

779     OpenSSH is a derivative of the original and free ssh 1.2.12 release by
780     Tatu Ylonen.  Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
781     de Raadt and Dug Song removed many bugs, re-added newer features and cre‐
782     ated OpenSSH.  Markus Friedl contributed the support for SSH protocol
783     versions 1.5 and 2.0.
784
785BSD                              May 10, 2020                              BSD
Impressum