xref: /openssh-portable/ssh-keygen.1 (revision 6ec74571)
1.\"	$OpenBSD: ssh-keygen.1,v 1.203 2020/04/03 02:26:56 djm Exp $
2.\"
3.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
4.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5.\"                    All rights reserved
6.\"
7.\" As far as I am concerned, the code I have written for this software
8.\" can be used freely for any purpose.  Any derived versions of this
9.\" software must be clearly marked as such, and if the derived work is
10.\" incompatible with the protocol description in the RFC file, it must be
11.\" called by a name other than "ssh" or "Secure Shell".
12.\"
13.\"
14.\" Copyright (c) 1999,2000 Markus Friedl.  All rights reserved.
15.\" Copyright (c) 1999 Aaron Campbell.  All rights reserved.
16.\" Copyright (c) 1999 Theo de Raadt.  All rights reserved.
17.\"
18.\" Redistribution and use in source and binary forms, with or without
19.\" modification, are permitted provided that the following conditions
20.\" are met:
21.\" 1. Redistributions of source code must retain the above copyright
22.\"    notice, this list of conditions and the following disclaimer.
23.\" 2. Redistributions in binary form must reproduce the above copyright
24.\"    notice, this list of conditions and the following disclaimer in the
25.\"    documentation and/or other materials provided with the distribution.
26.\"
27.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
28.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
29.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
30.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
31.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
32.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
33.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
34.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
35.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
36.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37.\"
38.Dd $Mdocdate: April 3 2020 $
39.Dt SSH-KEYGEN 1
40.Os
41.Sh NAME
42.Nm ssh-keygen
43.Nd OpenSSH authentication key utility
44.Sh SYNOPSIS
45.Nm ssh-keygen
46.Op Fl q
47.Op Fl b Ar bits
48.Op Fl C Ar comment
49.Op Fl f Ar output_keyfile
50.Op Fl m Ar format
51.Op Fl t Cm dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa
52.Op Fl N Ar new_passphrase
53.Op Fl O Ar option
54.Op Fl w Ar provider
55.Nm ssh-keygen
56.Fl p
57.Op Fl f Ar keyfile
58.Op Fl m Ar format
59.Op Fl N Ar new_passphrase
60.Op Fl P Ar old_passphrase
61.Nm ssh-keygen
62.Fl i
63.Op Fl f Ar input_keyfile
64.Op Fl m Ar key_format
65.Nm ssh-keygen
66.Fl e
67.Op Fl f Ar input_keyfile
68.Op Fl m Ar key_format
69.Nm ssh-keygen
70.Fl y
71.Op Fl f Ar input_keyfile
72.Nm ssh-keygen
73.Fl c
74.Op Fl C Ar comment
75.Op Fl f Ar keyfile
76.Op Fl P Ar passphrase
77.Nm ssh-keygen
78.Fl l
79.Op Fl v
80.Op Fl E Ar fingerprint_hash
81.Op Fl f Ar input_keyfile
82.Nm ssh-keygen
83.Fl B
84.Op Fl f Ar input_keyfile
85.Nm ssh-keygen
86.Fl D Ar pkcs11
87.Nm ssh-keygen
88.Fl F Ar hostname
89.Op Fl lv
90.Op Fl f Ar known_hosts_file
91.Nm ssh-keygen
92.Fl H
93.Op Fl f Ar known_hosts_file
94.Nm ssh-keygen
95.Fl K
96.Op Fl w Ar provider
97.Nm ssh-keygen
98.Fl R Ar hostname
99.Op Fl f Ar known_hosts_file
100.Nm ssh-keygen
101.Fl r Ar hostname
102.Op Fl g
103.Op Fl f Ar input_keyfile
104.Nm ssh-keygen
105.Fl M Cm generate
106.Op Fl O Ar option
107.Ar output_file
108.Nm ssh-keygen
109.Fl M Cm screen
110.Op Fl f Ar input_file
111.Op Fl O Ar option
112.Ar output_file
113.Nm ssh-keygen
114.Fl I Ar certificate_identity
115.Fl s Ar ca_key
116.Op Fl hU
117.Op Fl D Ar pkcs11_provider
118.Op Fl n Ar principals
119.Op Fl O Ar option
120.Op Fl V Ar validity_interval
121.Op Fl z Ar serial_number
122.Ar
123.Nm ssh-keygen
124.Fl L
125.Op Fl f Ar input_keyfile
126.Nm ssh-keygen
127.Fl A
128.Op Fl f Ar prefix_path
129.Nm ssh-keygen
130.Fl k
131.Fl f Ar krl_file
132.Op Fl u
133.Op Fl s Ar ca_public
134.Op Fl z Ar version_number
135.Ar
136.Nm ssh-keygen
137.Fl Q
138.Op Fl l
139.Fl f Ar krl_file
140.Ar
141.Nm ssh-keygen
142.Fl Y Cm find-principals
143.Fl s Ar signature_file
144.Fl f Ar allowed_signers_file
145.Nm ssh-keygen
146.Fl Y Cm check-novalidate
147.Fl n Ar namespace
148.Fl s Ar signature_file
149.Nm ssh-keygen
150.Fl Y Cm sign
151.Fl f Ar key_file
152.Fl n Ar namespace
153.Ar
154.Nm ssh-keygen
155.Fl Y Cm verify
156.Fl f Ar allowed_signers_file
157.Fl I Ar signer_identity
158.Fl n Ar namespace
159.Fl s Ar signature_file
160.Op Fl r Ar revocation_file
161.Sh DESCRIPTION
162.Nm
163generates, manages and converts authentication keys for
164.Xr ssh 1 .
165.Nm
166can create keys for use by SSH protocol version 2.
167.Pp
168The type of key to be generated is specified with the
169.Fl t
170option.
171If invoked without any arguments,
172.Nm
173will generate an RSA key.
174.Pp
175.Nm
176is also used to generate groups for use in Diffie-Hellman group
177exchange (DH-GEX).
178See the
179.Sx MODULI GENERATION
180section for details.
181.Pp
182Finally,
183.Nm
184can be used to generate and update Key Revocation Lists, and to test whether
185given keys have been revoked by one.
186See the
187.Sx KEY REVOCATION LISTS
188section for details.
189.Pp
190Normally each user wishing to use SSH
191with public key authentication runs this once to create the authentication
192key in
193.Pa ~/.ssh/id_dsa ,
194.Pa ~/.ssh/id_ecdsa ,
195.Pa ~/.ssh/id_ecdsa_sk ,
196.Pa ~/.ssh/id_ed25519 ,
197.Pa ~/.ssh/id_ed25519_sk
198or
199.Pa ~/.ssh/id_rsa .
200Additionally, the system administrator may use this to generate host keys,
201as seen in
202.Pa /etc/rc .
203.Pp
204Normally this program generates the key and asks for a file in which
205to store the private key.
206The public key is stored in a file with the same name but
207.Dq .pub
208appended.
209The program also asks for a passphrase.
210The passphrase may be empty to indicate no passphrase
211(host keys must have an empty passphrase), or it may be a string of
212arbitrary length.
213A passphrase is similar to a password, except it can be a phrase with a
214series of words, punctuation, numbers, whitespace, or any string of
215characters you want.
216Good passphrases are 10-30 characters long, are
217not simple sentences or otherwise easily guessable (English
218prose has only 1-2 bits of entropy per character, and provides very bad
219passphrases), and contain a mix of upper and lowercase letters,
220numbers, and non-alphanumeric characters.
221The passphrase can be changed later by using the
222.Fl p
223option.
224.Pp
225There is no way to recover a lost passphrase.
226If the passphrase is lost or forgotten, a new key must be generated
227and the corresponding public key copied to other machines.
228.Pp
229.Nm
230will by default write keys in an OpenSSH-specific format.
231This format is preferred as it offers better protection for
232keys at rest as well as allowing storage of key comments within
233the private key file itself.
234The key comment may be useful to help identify the key.
235The comment is initialized to
236.Dq user@host
237when the key is created, but can be changed using the
238.Fl c
239option.
240.Pp
241It is still possible for
242.Nm
243to write the previously-used PEM format private keys using the
244.Fl m
245flag.
246This may be used when generating new keys, and existing new-format
247keys may be converted using this option in conjunction with the
248.Fl p
249(change passphrase) flag.
250.Pp
251After a key is generated, instructions below detail where the keys
252should be placed to be activated.
253.Pp
254The options are as follows:
255.Bl -tag -width Ds
256.It Fl A
257For each of the key types (rsa, dsa, ecdsa and ed25519)
258for which host keys
259do not exist, generate the host keys with the default key file path,
260an empty passphrase, default bits for the key type, and default comment.
261If
262.Fl f
263has also been specified, its argument is used as a prefix to the
264default path for the resulting host key files.
265This is used by
266.Pa /etc/rc
267to generate new host keys.
268.It Fl a Ar rounds
269When saving a private key, this option specifies the number of KDF
270(key derivation function) rounds used.
271Higher numbers result in slower passphrase verification and increased
272resistance to brute-force password cracking (should the keys be stolen).
273.It Fl B
274Show the bubblebabble digest of specified private or public key file.
275.It Fl b Ar bits
276Specifies the number of bits in the key to create.
277For RSA keys, the minimum size is 1024 bits and the default is 3072 bits.
278Generally, 3072 bits is considered sufficient.
279DSA keys must be exactly 1024 bits as specified by FIPS 186-2.
280For ECDSA keys, the
281.Fl b
282flag determines the key length by selecting from one of three elliptic
283curve sizes: 256, 384 or 521 bits.
284Attempting to use bit lengths other than these three values for ECDSA keys
285will fail.
286ECDSA-SK, Ed25519 and Ed25519-SK keys have a fixed length and the
287.Fl b
288flag will be ignored.
289.It Fl C Ar comment
290Provides a new comment.
291.It Fl c
292Requests changing the comment in the private and public key files.
293The program will prompt for the file containing the private keys, for
294the passphrase if the key has one, and for the new comment.
295.It Fl D Ar pkcs11
296Download the public keys provided by the PKCS#11 shared library
297.Ar pkcs11 .
298When used in combination with
299.Fl s ,
300this option indicates that a CA key resides in a PKCS#11 token (see the
301.Sx CERTIFICATES
302section for details).
303.It Fl E Ar fingerprint_hash
304Specifies the hash algorithm used when displaying key fingerprints.
305Valid options are:
306.Dq md5
307and
308.Dq sha256 .
309The default is
310.Dq sha256 .
311.It Fl e
312This option will read a private or public OpenSSH key file and
313print to stdout a public key in one of the formats specified by the
314.Fl m
315option.
316The default export format is
317.Dq RFC4716 .
318This option allows exporting OpenSSH keys for use by other programs, including
319several commercial SSH implementations.
320.It Fl F Ar hostname | [hostname]:port
321Search for the specified
322.Ar hostname
323(with optional port number)
324in a
325.Pa known_hosts
326file, listing any occurrences found.
327This option is useful to find hashed host names or addresses and may also be
328used in conjunction with the
329.Fl H
330option to print found keys in a hashed format.
331.It Fl f Ar filename
332Specifies the filename of the key file.
333.It Fl g
334Use generic DNS format when printing fingerprint resource records using the
335.Fl r
336command.
337.It Fl H
338Hash a
339.Pa known_hosts
340file.
341This replaces all hostnames and addresses with hashed representations
342within the specified file; the original content is moved to a file with
343a .old suffix.
344These hashes may be used normally by
345.Nm ssh
346and
347.Nm sshd ,
348but they do not reveal identifying information should the file's contents
349be disclosed.
350This option will not modify existing hashed hostnames and is therefore safe
351to use on files that mix hashed and non-hashed names.
352.It Fl h
353When signing a key, create a host certificate instead of a user
354certificate.
355Please see the
356.Sx CERTIFICATES
357section for details.
358.It Fl I Ar certificate_identity
359Specify the key identity when signing a public key.
360Please see the
361.Sx CERTIFICATES
362section for details.
363.It Fl i
364This option will read an unencrypted private (or public) key file
365in the format specified by the
366.Fl m
367option and print an OpenSSH compatible private
368(or public) key to stdout.
369This option allows importing keys from other software, including several
370commercial SSH implementations.
371The default import format is
372.Dq RFC4716 .
373.It Fl K
374Download resident keys from a FIDO authenticator.
375Public and private key files will be written to the current directory for
376each downloaded key.
377.It Fl k
378Generate a KRL file.
379In this mode,
380.Nm
381will generate a KRL file at the location specified via the
382.Fl f
383flag that revokes every key or certificate presented on the command line.
384Keys/certificates to be revoked may be specified by public key file or
385using the format described in the
386.Sx KEY REVOCATION LISTS
387section.
388.It Fl L
389Prints the contents of one or more certificates.
390.It Fl l
391Show fingerprint of specified public key file.
392For RSA and DSA keys
393.Nm
394tries to find the matching public key file and prints its fingerprint.
395If combined with
396.Fl v ,
397a visual ASCII art representation of the key is supplied with the
398fingerprint.
399.It Fl M Cm generate
400Generate candidate Diffie-Hellman Group Exchange (DH-GEX) parameters for
401eventual use by the
402.Sq diffie-hellman-group-exchange-*
403key exchange methods.
404The numbers generated by this operation must be further screened before
405use.
406See the
407.Sx MODULI GENERATION
408section for more information.
409.It Fl M Cm screen
410Screen candidate parameters for Diffie-Hellman Group Exchange.
411This will accept a list of candidate numbers and test that they are
412safe (Sophie Germain) primes with acceptable group generators.
413The results of this operation may be added to the
414.Pa /etc/moduli
415file.
416See the
417.Sx MODULI GENERATION
418section for more information.
419.It Fl m Ar key_format
420Specify a key format for key generation, the
421.Fl i
422(import),
423.Fl e
424(export) conversion options, and the
425.Fl p
426change passphrase operation.
427The latter may be used to convert between OpenSSH private key and PEM
428private key formats.
429The supported key formats are:
430.Dq RFC4716
431(RFC 4716/SSH2 public or private key),
432.Dq PKCS8
433(PKCS8 public or private key)
434or
435.Dq PEM
436(PEM public key).
437By default OpenSSH will write newly-generated private keys in its own
438format, but when converting public keys for export the default format is
439.Dq RFC4716 .
440Setting a format of
441.Dq PEM
442when generating or updating a supported private key type will cause the
443key to be stored in the legacy PEM private key format.
444.It Fl N Ar new_passphrase
445Provides the new passphrase.
446.It Fl n Ar principals
447Specify one or more principals (user or host names) to be included in
448a certificate when signing a key.
449Multiple principals may be specified, separated by commas.
450Please see the
451.Sx CERTIFICATES
452section for details.
453.It Fl O Ar option
454Specify a key/value option.
455These are specific to the operation that
456.Nm
457has been requested to perform.
458.Pp
459When signing certificates, one of the options listed in the
460.Sx CERTIFICATES
461section may be specified here.
462.Pp
463When performing moduli generation or screening, one of the options
464listed in the
465.Sx MODULI GENERATION
466section may be specified.
467.Pp
468When generating a key that will be hosted on a FIDO authenticator,
469this flag may be used to specify key-specific options.
470Those supported at present are:
471.Bl -tag -width Ds
472.It Cm application
473Override the default FIDO application/origin string of
474.Dq ssh: .
475This may be useful when generating host or domain-specific resident keys.
476The specified application string must begin with
477.Dq ssh: .
478.It Cm challenge Ns = Ns Ar path
479Specifies a path to a challenge string that will be passed to the
480FIDO token during key generation.
481The challenge string may be used as part of an out-of-band
482protocol for key enrollment
483(a random challenge is used by default).
484.It Cm device
485Explicitly specify a
486.Xr fido 4
487device to use, rather than letting the token middleware select one.
488.It Cm no-touch-required
489Indicate that the generated private key should not require touch
490events (user presence) when making signatures.
491Note that
492.Xr sshd 8
493will refuse such signatures by default, unless overridden via
494an authorized_keys option.
495.It Cm resident
496Indicate that the key should be stored on the FIDO authenticator itself.
497Resident keys may be supported on FIDO2 tokens and typically require that
498a PIN be set on the token prior to generation.
499Resident keys may be loaded off the token using
500.Xr ssh-add 1 .
501.It Cm user
502A username to be associated with a resident key,
503overriding the empty default username.
504Specifying a username may be useful when generating multiple resident keys
505for the same application name.
506.It Cm write-attestation Ns = Ns Ar path
507May be used at key generation time to record the attestation certificate
508returned from FIDO tokens during key generation.
509By default this information is discarded.
510.El
511.Pp
512The
513.Fl O
514option may be specified multiple times.
515.It Fl P Ar passphrase
516Provides the (old) passphrase.
517.It Fl p
518Requests changing the passphrase of a private key file instead of
519creating a new private key.
520The program will prompt for the file
521containing the private key, for the old passphrase, and twice for the
522new passphrase.
523.It Fl Q
524Test whether keys have been revoked in a KRL.
525If the
526.Fl l
527option is also specified then the contents of the KRL will be printed.
528.It Fl q
529Silence
530.Nm ssh-keygen .
531.It Fl R Ar hostname | [hostname]:port
532Removes all keys belonging to the specified
533.Ar hostname
534(with optional port number)
535from a
536.Pa known_hosts
537file.
538This option is useful to delete hashed hosts (see the
539.Fl H
540option above).
541.It Fl r Ar hostname
542Print the SSHFP fingerprint resource record named
543.Ar hostname
544for the specified public key file.
545.It Fl s Ar ca_key
546Certify (sign) a public key using the specified CA key.
547Please see the
548.Sx CERTIFICATES
549section for details.
550.Pp
551When generating a KRL,
552.Fl s
553specifies a path to a CA public key file used to revoke certificates directly
554by key ID or serial number.
555See the
556.Sx KEY REVOCATION LISTS
557section for details.
558.It Fl t Cm dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa
559Specifies the type of key to create.
560The possible values are
561.Dq dsa ,
562.Dq ecdsa ,
563.Dq ecdsa-sk ,
564.Dq ed25519 ,
565.Dq ed25519-sk ,
566or
567.Dq rsa .
568.Pp
569This flag may also be used to specify the desired signature type when
570signing certificates using an RSA CA key.
571The available RSA signature variants are
572.Dq ssh-rsa
573(SHA1 signatures, not recommended),
574.Dq rsa-sha2-256 ,
575and
576.Dq rsa-sha2-512
577(the default).
578.It Fl U
579When used in combination with
580.Fl s ,
581this option indicates that a CA key resides in a
582.Xr ssh-agent 1 .
583See the
584.Sx CERTIFICATES
585section for more information.
586.It Fl u
587Update a KRL.
588When specified with
589.Fl k ,
590keys listed via the command line are added to the existing KRL rather than
591a new KRL being created.
592.It Fl V Ar validity_interval
593Specify a validity interval when signing a certificate.
594A validity interval may consist of a single time, indicating that the
595certificate is valid beginning now and expiring at that time, or may consist
596of two times separated by a colon to indicate an explicit time interval.
597.Pp
598The start time may be specified as the string
599.Dq always
600to indicate the certificate has no specified start time,
601a date in YYYYMMDD format, a time in YYYYMMDDHHMM[SS] format,
602a relative time (to the current time) consisting of a minus sign followed by
603an interval in the format described in the
604TIME FORMATS section of
605.Xr sshd_config 5 .
606.Pp
607The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMM[SS] time,
608a relative time starting with a plus character or the string
609.Dq forever
610to indicate that the certificate has no expiry date.
611.Pp
612For example:
613.Dq +52w1d
614(valid from now to 52 weeks and one day from now),
615.Dq -4w:+4w
616(valid from four weeks ago to four weeks from now),
617.Dq 20100101123000:20110101123000
618(valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011),
619.Dq -1d:20110101
620(valid from yesterday to midnight, January 1st, 2011).
621.Dq -1m:forever
622(valid from one minute ago and never expiring).
623.It Fl v
624Verbose mode.
625Causes
626.Nm
627to print debugging messages about its progress.
628This is helpful for debugging moduli generation.
629Multiple
630.Fl v
631options increase the verbosity.
632The maximum is 3.
633.It Fl w Ar provider
634Specifies a path to a library that will be used when creating
635FIDO authenticator-hosted keys, overriding the default of using
636the internal USB HID support.
637.It Fl Y Cm find-principals
638Find the principal(s) associated with the public key of a signature,
639provided using the
640.Fl s
641flag in an authorized signers file provided using the
642.Fl f
643flag.
644The format of the allowed signers file is documented in the
645.Sx ALLOWED SIGNERS
646section below.
647If one or more matching principals are found, they are returned on
648standard output.
649.It Fl Y Cm check-novalidate
650Checks that a signature generated using
651.Nm
652.Fl Y Cm sign
653has a valid structure.
654This does not validate if a signature comes from an authorized signer.
655When testing a signature,
656.Nm
657accepts a message on standard input and a signature namespace using
658.Fl n .
659A file containing the corresponding signature must also be supplied using the
660.Fl s
661flag.
662Successful testing of the signature is signalled by
663.Nm
664returning a zero exit status.
665.It Fl Y Cm sign
666Cryptographically sign a file or some data using a SSH key.
667When signing,
668.Nm
669accepts zero or more files to sign on the command-line - if no files
670are specified then
671.Nm
672will sign data presented on standard input.
673Signatures are written to the path of the input file with
674.Dq .sig
675appended, or to standard output if the message to be signed was read from
676standard input.
677.Pp
678The key used for signing is specified using the
679.Fl f
680option and may refer to either a private key, or a public key with the private
681half available via
682.Xr ssh-agent 1 .
683An additional signature namespace, used to prevent signature confusion across
684different domains of use (e.g. file signing vs email signing) must be provided
685via the
686.Fl n
687flag.
688Namespaces are arbitrary strings, and may include:
689.Dq file
690for file signing,
691.Dq email
692for email signing.
693For custom uses, it is recommended to use names following a
694NAMESPACE@YOUR.DOMAIN pattern to generate unambiguous namespaces.
695.It Fl Y Cm verify
696Request to verify a signature generated using
697.Nm
698.Fl Y Cm sign
699as described above.
700When verifying a signature,
701.Nm
702accepts a message on standard input and a signature namespace using
703.Fl n .
704A file containing the corresponding signature must also be supplied using the
705.Fl s
706flag, along with the identity of the signer using
707.Fl I
708and a list of allowed signers via the
709.Fl f
710flag.
711The format of the allowed signers file is documented in the
712.Sx ALLOWED SIGNERS
713section below.
714A file containing revoked keys can be passed using the
715.Fl r
716flag.
717The revocation file may be a KRL or a one-per-line list of public keys.
718Successful verification by an authorized signer is signalled by
719.Nm
720returning a zero exit status.
721.It Fl y
722This option will read a private
723OpenSSH format file and print an OpenSSH public key to stdout.
724.It Fl z Ar serial_number
725Specifies a serial number to be embedded in the certificate to distinguish
726this certificate from others from the same CA.
727If the
728.Ar serial_number
729is prefixed with a
730.Sq +
731character, then the serial number will be incremented for each certificate
732signed on a single command-line.
733The default serial number is zero.
734.Pp
735When generating a KRL, the
736.Fl z
737flag is used to specify a KRL version number.
738.El
739.Sh MODULI GENERATION
740.Nm
741may be used to generate groups for the Diffie-Hellman Group Exchange
742(DH-GEX) protocol.
743Generating these groups is a two-step process: first, candidate
744primes are generated using a fast, but memory intensive process.
745These candidate primes are then tested for suitability (a CPU-intensive
746process).
747.Pp
748Generation of primes is performed using the
749.Fl M Cm generate
750option.
751The desired length of the primes may be specified by the
752.Fl O Cm bits
753option.
754For example:
755.Pp
756.Dl # ssh-keygen -M generate -O bits=2048 moduli-2048.candidates
757.Pp
758By default, the search for primes begins at a random point in the
759desired length range.
760This may be overridden using the
761.Fl O Cm start
762option, which specifies a different start point (in hex).
763.Pp
764Once a set of candidates have been generated, they must be screened for
765suitability.
766This may be performed using the
767.Fl M Cm screen
768option.
769In this mode
770.Nm
771will read candidates from standard input (or a file specified using the
772.Fl f
773option).
774For example:
775.Pp
776.Dl # ssh-keygen -M screen -f moduli-2048.candidates moduli-2048
777.Pp
778By default, each candidate will be subjected to 100 primality tests.
779This may be overridden using the
780.Fl O Cm prime-tests
781option.
782The DH generator value will be chosen automatically for the
783prime under consideration.
784If a specific generator is desired, it may be requested using the
785.Fl O Cm generator
786option.
787Valid generator values are 2, 3, and 5.
788.Pp
789Screened DH groups may be installed in
790.Pa /etc/moduli .
791It is important that this file contains moduli of a range of bit lengths and
792that both ends of a connection share common moduli.
793.Pp
794A number of options are available for moduli generation and screening via the
795.Fl O
796flag:
797.Bl -tag -width Ds
798.It Ic lines Ns = Ns Ar number
799Exit after screening the specified number of lines while performing DH
800candidate screening.
801.It Ic start-line Ns = Ns Ar line-number
802Start screening at the specified line number while performing DH candidate
803screening.
804.It Ic checkpoint Ns = Ns Ar filename
805Write the last line processed to the specified file while performing DH
806candidate screening.
807This will be used to skip lines in the input file that have already been
808processed if the job is restarted.
809.It Ic memory Ns = Ns Ar mbytes
810Specify the amount of memory to use (in megabytes) when generating
811candidate moduli for DH-GEX.
812.It Ic start Ns = Ns Ar hex-value
813Specify start point (in hex) when generating candidate moduli for DH-GEX.
814.It Ic generator Ns = Ns Ar value
815Specify desired generator (in decimal) when testing candidate moduli for DH-GEX.
816.El
817.Sh CERTIFICATES
818.Nm
819supports signing of keys to produce certificates that may be used for
820user or host authentication.
821Certificates consist of a public key, some identity information, zero or
822more principal (user or host) names and a set of options that
823are signed by a Certification Authority (CA) key.
824Clients or servers may then trust only the CA key and verify its signature
825on a certificate rather than trusting many user/host keys.
826Note that OpenSSH certificates are a different, and much simpler, format to
827the X.509 certificates used in
828.Xr ssl 8 .
829.Pp
830.Nm
831supports two types of certificates: user and host.
832User certificates authenticate users to servers, whereas host certificates
833authenticate server hosts to users.
834To generate a user certificate:
835.Pp
836.Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
837.Pp
838The resultant certificate will be placed in
839.Pa /path/to/user_key-cert.pub .
840A host certificate requires the
841.Fl h
842option:
843.Pp
844.Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
845.Pp
846The host certificate will be output to
847.Pa /path/to/host_key-cert.pub .
848.Pp
849It is possible to sign using a CA key stored in a PKCS#11 token by
850providing the token library using
851.Fl D
852and identifying the CA key by providing its public half as an argument
853to
854.Fl s :
855.Pp
856.Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub
857.Pp
858Similarly, it is possible for the CA key to be hosted in a
859.Xr ssh-agent 1 .
860This is indicated by the
861.Fl U
862flag and, again, the CA key must be identified by its public half.
863.Pp
864.Dl $ ssh-keygen -Us ca_key.pub -I key_id user_key.pub
865.Pp
866In all cases,
867.Ar key_id
868is a "key identifier" that is logged by the server when the certificate
869is used for authentication.
870.Pp
871Certificates may be limited to be valid for a set of principal (user/host)
872names.
873By default, generated certificates are valid for all users or hosts.
874To generate a certificate for a specified set of principals:
875.Pp
876.Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
877.Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain host_key.pub"
878.Pp
879Additional limitations on the validity and use of user certificates may
880be specified through certificate options.
881A certificate option may disable features of the SSH session, may be
882valid only when presented from particular source addresses or may
883force the use of a specific command.
884.Pp
885The options that are valid for user certificates are:
886.Pp
887.Bl -tag -width Ds -compact
888.It Ic clear
889Clear all enabled permissions.
890This is useful for clearing the default set of permissions so permissions may
891be added individually.
892.Pp
893.It Ic critical : Ns Ar name Ns Op Ns = Ns Ar contents
894.It Ic extension : Ns Ar name Ns Op Ns = Ns Ar contents
895Includes an arbitrary certificate critical option or extension.
896The specified
897.Ar name
898should include a domain suffix, e.g.\&
899.Dq name@example.com .
900If
901.Ar contents
902is specified then it is included as the contents of the extension/option
903encoded as a string, otherwise the extension/option is created with no
904contents (usually indicating a flag).
905Extensions may be ignored by a client or server that does not recognise them,
906whereas unknown critical options will cause the certificate to be refused.
907.Pp
908.It Ic force-command Ns = Ns Ar command
909Forces the execution of
910.Ar command
911instead of any shell or command specified by the user when
912the certificate is used for authentication.
913.Pp
914.It Ic no-agent-forwarding
915Disable
916.Xr ssh-agent 1
917forwarding (permitted by default).
918.Pp
919.It Ic no-port-forwarding
920Disable port forwarding (permitted by default).
921.Pp
922.It Ic no-pty
923Disable PTY allocation (permitted by default).
924.Pp
925.It Ic no-user-rc
926Disable execution of
927.Pa ~/.ssh/rc
928by
929.Xr sshd 8
930(permitted by default).
931.Pp
932.It Ic no-x11-forwarding
933Disable X11 forwarding (permitted by default).
934.Pp
935.It Ic permit-agent-forwarding
936Allows
937.Xr ssh-agent 1
938forwarding.
939.Pp
940.It Ic permit-port-forwarding
941Allows port forwarding.
942.Pp
943.It Ic permit-pty
944Allows PTY allocation.
945.Pp
946.It Ic permit-user-rc
947Allows execution of
948.Pa ~/.ssh/rc
949by
950.Xr sshd 8 .
951.Pp
952.It Ic permit-X11-forwarding
953Allows X11 forwarding.
954.Pp
955.It Ic no-touch-required
956Do not require signatures made using this key require demonstration
957of user presence (e.g. by having the user touch the authenticator).
958This option only makes sense for the FIDO authenticator algorithms
959.Cm ecdsa-sk
960and
961.Cm ed25519-sk .
962.Pp
963.It Ic source-address Ns = Ns Ar address_list
964Restrict the source addresses from which the certificate is considered valid.
965The
966.Ar address_list
967is a comma-separated list of one or more address/netmask pairs in CIDR
968format.
969.El
970.Pp
971At present, no standard options are valid for host keys.
972.Pp
973Finally, certificates may be defined with a validity lifetime.
974The
975.Fl V
976option allows specification of certificate start and end times.
977A certificate that is presented at a time outside this range will not be
978considered valid.
979By default, certificates are valid from
980.Ux
981Epoch to the distant future.
982.Pp
983For certificates to be used for user or host authentication, the CA
984public key must be trusted by
985.Xr sshd 8
986or
987.Xr ssh 1 .
988Please refer to those manual pages for details.
989.Sh KEY REVOCATION LISTS
990.Nm
991is able to manage OpenSSH format Key Revocation Lists (KRLs).
992These binary files specify keys or certificates to be revoked using a
993compact format, taking as little as one bit per certificate if they are being
994revoked by serial number.
995.Pp
996KRLs may be generated using the
997.Fl k
998flag.
999This option reads one or more files from the command line and generates a new
1000KRL.
1001The files may either contain a KRL specification (see below) or public keys,
1002listed one per line.
1003Plain public keys are revoked by listing their hash or contents in the KRL and
1004certificates revoked by serial number or key ID (if the serial is zero or
1005not available).
1006.Pp
1007Revoking keys using a KRL specification offers explicit control over the
1008types of record used to revoke keys and may be used to directly revoke
1009certificates by serial number or key ID without having the complete original
1010certificate on hand.
1011A KRL specification consists of lines containing one of the following directives
1012followed by a colon and some directive-specific information.
1013.Bl -tag -width Ds
1014.It Cm serial : Ar serial_number Ns Op - Ns Ar serial_number
1015Revokes a certificate with the specified serial number.
1016Serial numbers are 64-bit values, not including zero and may be expressed
1017in decimal, hex or octal.
1018If two serial numbers are specified separated by a hyphen, then the range
1019of serial numbers including and between each is revoked.
1020The CA key must have been specified on the
1021.Nm
1022command line using the
1023.Fl s
1024option.
1025.It Cm id : Ar key_id
1026Revokes a certificate with the specified key ID string.
1027The CA key must have been specified on the
1028.Nm
1029command line using the
1030.Fl s
1031option.
1032.It Cm key : Ar public_key
1033Revokes the specified key.
1034If a certificate is listed, then it is revoked as a plain public key.
1035.It Cm sha1 : Ar public_key
1036Revokes the specified key by including its SHA1 hash in the KRL.
1037.It Cm sha256 : Ar public_key
1038Revokes the specified key by including its SHA256 hash in the KRL.
1039KRLs that revoke keys by SHA256 hash are not supported by OpenSSH versions
1040prior to 7.9.
1041.It Cm hash : Ar fingerprint
1042Revokes a key using a fingerprint hash, as obtained from a
1043.Xr sshd 8
1044authentication log message or the
1045.Nm
1046.Fl l
1047flag.
1048Only SHA256 fingerprints are supported here and resultant KRLs are
1049not supported by OpenSSH versions prior to 7.9.
1050.El
1051.Pp
1052KRLs may be updated using the
1053.Fl u
1054flag in addition to
1055.Fl k .
1056When this option is specified, keys listed via the command line are merged into
1057the KRL, adding to those already there.
1058.Pp
1059It is also possible, given a KRL, to test whether it revokes a particular key
1060(or keys).
1061The
1062.Fl Q
1063flag will query an existing KRL, testing each key specified on the command line.
1064If any key listed on the command line has been revoked (or an error encountered)
1065then
1066.Nm
1067will exit with a non-zero exit status.
1068A zero exit status will only be returned if no key was revoked.
1069.Sh ALLOWED SIGNERS
1070When verifying signatures,
1071.Nm
1072uses a simple list of identities and keys to determine whether a signature
1073comes from an authorized source.
1074This "allowed signers" file uses a format patterned after the
1075AUTHORIZED_KEYS FILE FORMAT described in
1076.Xr sshd 8 .
1077Each line of the file contains the following space-separated fields:
1078principals, options, keytype, base64-encoded key.
1079Empty lines and lines starting with a
1080.Ql #
1081are ignored as comments.
1082.Pp
1083The principals field is a pattern-list (See PATTERNS in
1084.Xr ssh_config 5 )
1085consisting of one or more comma-separated USER@DOMAIN identity patterns
1086that are accepted for signing.
1087When verifying, the identity presented via the
1088.Fl I
1089option must match a principals pattern in order for the corresponding key to be
1090considered acceptable for verification.
1091.Pp
1092The options (if present) consist of comma-separated option specifications.
1093No spaces are permitted, except within double quotes.
1094The following option specifications are supported (note that option keywords
1095are case-insensitive):
1096.Bl -tag -width Ds
1097.It Cm cert-authority
1098Indicates that this key is accepted as a certificate authority (CA) and
1099that certificates signed by this CA may be accepted for verification.
1100.It Cm namespaces="namespace-list"
1101Specifies a pattern-list of namespaces that are accepted for this key.
1102If this option is present, the signature namespace embedded in the
1103signature object and presented on the verification command-line must
1104match the specified list before the key will be considered acceptable.
1105.El
1106.Pp
1107When verifying signatures made by certificates, the expected principal
1108name must match both the principals pattern in the allowed signers file and
1109the principals embedded in the certificate itself.
1110.Pp
1111An example allowed signers file:
1112.Bd -literal -offset 3n
1113# Comments allowed at start of line
1114user1@example.com,user2@example.com ssh-rsa AAAAX1...
1115# A certificate authority, trusted for all principals in a domain.
1116*@example.com cert-authority ssh-ed25519 AAAB4...
1117# A key that is accepted only for file signing.
1118user2@example.com namespaces="file" ssh-ed25519 AAA41...
1119.Ed
1120.Sh ENVIRONMENT
1121.Bl -tag -width Ds
1122.It Ev SSH_SK_PROVIDER
1123Specifies a path to a library that will be used when loading any
1124FIDO authenticator-hosted keys, overriding the default of using
1125the built-in USB HID support.
1126.El
1127.Sh FILES
1128.Bl -tag -width Ds -compact
1129.It Pa ~/.ssh/id_dsa
1130.It Pa ~/.ssh/id_ecdsa
1131.It Pa ~/.ssh/id_ecdsa_sk
1132.It Pa ~/.ssh/id_ed25519
1133.It Pa ~/.ssh/id_ed25519_sk
1134.It Pa ~/.ssh/id_rsa
1135Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519,
1136authenticator-hosted Ed25519 or RSA authentication identity of the user.
1137This file should not be readable by anyone but the user.
1138It is possible to
1139specify a passphrase when generating the key; that passphrase will be
1140used to encrypt the private part of this file using 128-bit AES.
1141This file is not automatically accessed by
1142.Nm
1143but it is offered as the default file for the private key.
1144.Xr ssh 1
1145will read this file when a login attempt is made.
1146.Pp
1147.It Pa ~/.ssh/id_dsa.pub
1148.It Pa ~/.ssh/id_ecdsa.pub
1149.It Pa ~/.ssh/id_ecdsa_sk.pub
1150.It Pa ~/.ssh/id_ed25519.pub
1151.It Pa ~/.ssh/id_ed25519_sk.pub
1152.It Pa ~/.ssh/id_rsa.pub
1153Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519,
1154authenticator-hosted Ed25519 or RSA public key for authentication.
1155The contents of this file should be added to
1156.Pa ~/.ssh/authorized_keys
1157on all machines
1158where the user wishes to log in using public key authentication.
1159There is no need to keep the contents of this file secret.
1160.Pp
1161.It Pa /etc/moduli
1162Contains Diffie-Hellman groups used for DH-GEX.
1163The file format is described in
1164.Xr moduli 5 .
1165.El
1166.Sh SEE ALSO
1167.Xr ssh 1 ,
1168.Xr ssh-add 1 ,
1169.Xr ssh-agent 1 ,
1170.Xr moduli 5 ,
1171.Xr sshd 8
1172.Rs
1173.%R RFC 4716
1174.%T "The Secure Shell (SSH) Public Key File Format"
1175.%D 2006
1176.Re
1177.Sh AUTHORS
1178OpenSSH is a derivative of the original and free
1179ssh 1.2.12 release by Tatu Ylonen.
1180Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1181Theo de Raadt and Dug Song
1182removed many bugs, re-added newer features and
1183created OpenSSH.
1184Markus Friedl contributed the support for SSH
1185protocol versions 1.5 and 2.0.
1186