3.\"
4.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
5.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
6.\" All rights reserved
7.\"
8.\" As far as I am concerned, the code I have written for this software
9.\" can be used freely for any purpose. Any derived versions of this
10.\" software must be clearly marked as such, and if the derived work is
11.\" incompatible with the protocol description in the RFC file, it must be
12.\" called by a name other than "ssh" or "Secure Shell".
13.\"
14.\"
15.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
16.\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
17.\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
18.\"
19.\" Redistribution and use in source and binary forms, with or without
20.\" modification, are permitted provided that the following conditions
21.\" are met:
22.\" 1. Redistributions of source code must retain the above copyright
23.\" notice, this list of conditions and the following disclaimer.
24.\" 2. Redistributions in binary form must reproduce the above copyright
25.\" notice, this list of conditions and the following disclaimer in the
26.\" documentation and/or other materials provided with the distribution.
27.\"
28.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
29.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
30.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
31.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
32.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
33.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
34.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
35.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
36.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
37.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38.\"
| 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.\"
|
40.Dt SSH-KEYGEN 1
41.Os
42.Sh NAME
43.Nm ssh-keygen
44.Nd authentication key generation, management and conversion
45.Sh SYNOPSIS
46.Bk -words
47.Nm ssh-keygen
48.Op Fl q
49.Op Fl b Ar bits
50.Op Fl t Ar type
51.Op Fl N Ar new_passphrase
52.Op Fl C Ar comment
53.Op Fl f Ar output_keyfile
54.Nm ssh-keygen
55.Fl p
56.Op Fl P Ar old_passphrase
57.Op Fl N Ar new_passphrase
58.Op Fl f Ar keyfile
59.Nm ssh-keygen
60.Fl i
61.Op Fl m Ar key_format
62.Op Fl f Ar input_keyfile
63.Nm ssh-keygen
64.Fl e
65.Op Fl m Ar key_format
66.Op Fl f Ar input_keyfile
67.Nm ssh-keygen
68.Fl y
69.Op Fl f Ar input_keyfile
70.Nm ssh-keygen
71.Fl c
72.Op Fl P Ar passphrase
73.Op Fl C Ar comment
74.Op Fl f Ar keyfile
75.Nm ssh-keygen
76.Fl l
77.Op Fl f Ar input_keyfile
78.Nm ssh-keygen
79.Fl B
80.Op Fl f Ar input_keyfile
81.Nm ssh-keygen
82.Fl D Ar pkcs11
83.Nm ssh-keygen
84.Fl F Ar hostname
85.Op Fl f Ar known_hosts_file
86.Op Fl l
87.Nm ssh-keygen
88.Fl H
89.Op Fl f Ar known_hosts_file
90.Nm ssh-keygen
91.Fl R Ar hostname
92.Op Fl f Ar known_hosts_file
93.Nm ssh-keygen
94.Fl r Ar hostname
95.Op Fl f Ar input_keyfile
96.Op Fl g
97.Nm ssh-keygen
98.Fl G Ar output_file
99.Op Fl v
100.Op Fl b Ar bits
101.Op Fl M Ar memory
102.Op Fl S Ar start_point
103.Nm ssh-keygen
104.Fl T Ar output_file
105.Fl f Ar input_file
106.Op Fl v
107.Op Fl a Ar rounds
108.Op Fl J Ar num_lines
109.Op Fl j Ar start_line
110.Op Fl K Ar checkpt
111.Op Fl W Ar generator
112.Nm ssh-keygen
113.Fl s Ar ca_key
114.Fl I Ar certificate_identity
115.Op Fl h
116.Op Fl n Ar principals
117.Op Fl O Ar option
118.Op Fl V Ar validity_interval
119.Op Fl z Ar serial_number
120.Ar
121.Nm ssh-keygen
122.Fl L
123.Op Fl f Ar input_keyfile
124.Nm ssh-keygen
125.Fl A
126.Nm ssh-keygen
127.Fl k
128.Fl f Ar krl_file
129.Op Fl u
130.Op Fl s Ar ca_public
131.Op Fl z Ar version_number
132.Ar
133.Nm ssh-keygen
134.Fl Q
135.Fl f Ar krl_file
136.Ar
137.Ek
138.Sh DESCRIPTION
139.Nm
140generates, manages and converts authentication keys for
141.Xr ssh 1 .
142.Nm
143can create RSA keys for use by SSH protocol version 1 and
144DSA, ECDSA, ED25519 or RSA keys for use by SSH protocol version 2.
145The type of key to be generated is specified with the
146.Fl t
147option.
148If invoked without any arguments,
149.Nm
150will generate an RSA key for use in SSH protocol 2 connections.
151.Pp
152.Nm
153is also used to generate groups for use in Diffie-Hellman group
154exchange (DH-GEX).
155See the
156.Sx MODULI GENERATION
157section for details.
158.Pp
159Finally,
160.Nm
161can be used to generate and update Key Revocation Lists, and to test whether
162given keys have been revoked by one.
163See the
164.Sx KEY REVOCATION LISTS
165section for details.
166.Pp
167Normally each user wishing to use SSH
168with public key authentication runs this once to create the authentication
169key in
170.Pa ~/.ssh/identity ,
171.Pa ~/.ssh/id_dsa ,
172.Pa ~/.ssh/id_ecdsa ,
173.Pa ~/.ssh/id_ed25519
174or
175.Pa ~/.ssh/id_rsa .
176Additionally, the system administrator may use this to generate host keys,
177as seen in
178.Pa /etc/rc .
179.Pp
180Normally this program generates the key and asks for a file in which
181to store the private key.
182The public key is stored in a file with the same name but
183.Dq .pub
184appended.
185The program also asks for a passphrase.
186The passphrase may be empty to indicate no passphrase
187(host keys must have an empty passphrase), or it may be a string of
188arbitrary length.
189A passphrase is similar to a password, except it can be a phrase with a
190series of words, punctuation, numbers, whitespace, or any string of
191characters you want.
192Good passphrases are 10-30 characters long, are
193not simple sentences or otherwise easily guessable (English
194prose has only 1-2 bits of entropy per character, and provides very bad
195passphrases), and contain a mix of upper and lowercase letters,
196numbers, and non-alphanumeric characters.
197The passphrase can be changed later by using the
198.Fl p
199option.
200.Pp
201There is no way to recover a lost passphrase.
202If the passphrase is lost or forgotten, a new key must be generated
203and the corresponding public key copied to other machines.
204.Pp
205For RSA1 keys,
206there is also a comment field in the key file that is only for
207convenience to the user to help identify the key.
208The comment can tell what the key is for, or whatever is useful.
209The comment is initialized to
210.Dq user@host
211when the key is created, but can be changed using the
212.Fl c
213option.
214.Pp
215After a key is generated, instructions below detail where the keys
216should be placed to be activated.
217.Pp
218The options are as follows:
219.Bl -tag -width Ds
220.It Fl A
221For each of the key types (rsa1, rsa, dsa, ecdsa and ed25519)
222for which host keys
223do not exist, generate the host keys with the default key file path,
224an empty passphrase, default bits for the key type, and default comment.
225This is used by
226.Pa /etc/rc
227to generate new host keys.
228.It Fl a Ar rounds
229When saving a new-format private key (i.e. an ed25519 key or any SSH protocol
2302 key when the
231.Fl o
232flag is set), this option specifies the number of KDF (key derivation function)
233rounds used.
234Higher numbers result in slower passphrase verification and increased
235resistance to brute-force password cracking (should the keys be stolen).
236.Pp
237When screening DH-GEX candidates (
238using the
239.Fl T
240command).
241This option specifies the number of primality tests to perform.
242.It Fl B
243Show the bubblebabble digest of specified private or public key file.
244.It Fl b Ar bits
245Specifies the number of bits in the key to create.
246For RSA keys, the minimum size is 768 bits and the default is 2048 bits.
247Generally, 2048 bits is considered sufficient.
248DSA keys must be exactly 1024 bits as specified by FIPS 186-2.
249For ECDSA keys, the
250.Fl b
251flag determines the key length by selecting from one of three elliptic
252curve sizes: 256, 384 or 521 bits.
253Attempting to use bit lengths other than these three values for ECDSA keys
254will fail.
255ED25519 keys have a fixed length and the
256.Fl b
257flag will be ignored.
258.It Fl C Ar comment
259Provides a new comment.
260.It Fl c
261Requests changing the comment in the private and public key files.
262This operation is only supported for RSA1 keys.
263The program will prompt for the file containing the private keys, for
264the passphrase if the key has one, and for the new comment.
265.It Fl D Ar pkcs11
266Download the RSA public keys provided by the PKCS#11 shared library
267.Ar pkcs11 .
268When used in combination with
269.Fl s ,
270this option indicates that a CA key resides in a PKCS#11 token (see the
271.Sx CERTIFICATES
272section for details).
273.It Fl e
274This option will read a private or public OpenSSH key file and
275print to stdout the key in one of the formats specified by the
276.Fl m
277option.
278The default export format is
279.Dq RFC4716 .
280This option allows exporting OpenSSH keys for use by other programs, including
281several commercial SSH implementations.
282.It Fl F Ar hostname
283Search for the specified
284.Ar hostname
285in a
286.Pa known_hosts
287file, listing any occurrences found.
288This option is useful to find hashed host names or addresses and may also be
289used in conjunction with the
290.Fl H
291option to print found keys in a hashed format.
292.It Fl f Ar filename
293Specifies the filename of the key file.
294.It Fl G Ar output_file
295Generate candidate primes for DH-GEX.
296These primes must be screened for
297safety (using the
298.Fl T
299option) before use.
300.It Fl g
301Use generic DNS format when printing fingerprint resource records using the
302.Fl r
303command.
304.It Fl H
305Hash a
306.Pa known_hosts
307file.
308This replaces all hostnames and addresses with hashed representations
309within the specified file; the original content is moved to a file with
310a .old suffix.
311These hashes may be used normally by
312.Nm ssh
313and
314.Nm sshd ,
315but they do not reveal identifying information should the file's contents
316be disclosed.
317This option will not modify existing hashed hostnames and is therefore safe
318to use on files that mix hashed and non-hashed names.
319.It Fl h
320When signing a key, create a host certificate instead of a user
321certificate.
322Please see the
323.Sx CERTIFICATES
324section for details.
325.It Fl I Ar certificate_identity
326Specify the key identity when signing a public key.
327Please see the
328.Sx CERTIFICATES
329section for details.
330.It Fl i
331This option will read an unencrypted private (or public) key file
332in the format specified by the
333.Fl m
334option and print an OpenSSH compatible private
335(or public) key to stdout.
336.It Fl J Ar num_lines
337Exit after screening the specified number of lines
338while performing DH candidate screening using the
339.Fl T
340option.
341.It Fl j Ar start_line
342Start screening at the specified line number
343while performing DH candidate screening using the
344.Fl T
345option.
346.It Fl K Ar checkpt
347Write the last line processed to the file
348.Ar checkpt
349while performing DH candidate screening using the
350.Fl T
351option.
352This will be used to skip lines in the input file that have already been
353processed if the job is restarted.
354This option allows importing keys from other software, including several
355commercial SSH implementations.
356The default import format is
357.Dq RFC4716 .
358.It Fl k
359Generate a KRL file.
360In this mode,
361.Nm
362will generate a KRL file at the location specified via the
363.Fl f
364flag that revokes every key or certificate presented on the command line.
365Keys/certificates to be revoked may be specified by public key file or
366using the format described in the
367.Sx KEY REVOCATION LISTS
368section.
369.It Fl L
370Prints the contents of a certificate.
371.It Fl l
372Show fingerprint of specified public key file.
373Private RSA1 keys are also supported.
374For RSA and DSA keys
375.Nm
376tries to find the matching public key file and prints its fingerprint.
377If combined with
378.Fl v ,
379an ASCII art representation of the key is supplied with the fingerprint.
380.It Fl M Ar memory
381Specify the amount of memory to use (in megabytes) when generating
382candidate moduli for DH-GEX.
383.It Fl m Ar key_format
384Specify a key format for the
385.Fl i
386(import) or
387.Fl e
388(export) conversion options.
389The supported key formats are:
390.Dq RFC4716
391(RFC 4716/SSH2 public or private key),
392.Dq PKCS8
393(PEM PKCS8 public key)
394or
395.Dq PEM
396(PEM public key).
397The default conversion format is
398.Dq RFC4716 .
399.It Fl N Ar new_passphrase
400Provides the new passphrase.
401.It Fl n Ar principals
402Specify one or more principals (user or host names) to be included in
403a certificate when signing a key.
404Multiple principals may be specified, separated by commas.
405Please see the
406.Sx CERTIFICATES
407section for details.
408.It Fl O Ar option
409Specify a certificate option when signing a key.
410This option may be specified multiple times.
411Please see the
412.Sx CERTIFICATES
413section for details.
414The options that are valid for user certificates are:
415.Bl -tag -width Ds
416.It Ic clear
417Clear all enabled permissions.
418This is useful for clearing the default set of permissions so permissions may
419be added individually.
420.It Ic force-command Ns = Ns Ar command
421Forces the execution of
422.Ar command
423instead of any shell or command specified by the user when
424the certificate is used for authentication.
425.It Ic no-agent-forwarding
426Disable
427.Xr ssh-agent 1
428forwarding (permitted by default).
429.It Ic no-port-forwarding
430Disable port forwarding (permitted by default).
431.It Ic no-pty
432Disable PTY allocation (permitted by default).
433.It Ic no-user-rc
434Disable execution of
435.Pa ~/.ssh/rc
436by
437.Xr sshd 8
438(permitted by default).
439.It Ic no-x11-forwarding
440Disable X11 forwarding (permitted by default).
441.It Ic permit-agent-forwarding
442Allows
443.Xr ssh-agent 1
444forwarding.
445.It Ic permit-port-forwarding
446Allows port forwarding.
447.It Ic permit-pty
448Allows PTY allocation.
449.It Ic permit-user-rc
450Allows execution of
451.Pa ~/.ssh/rc
452by
453.Xr sshd 8 .
454.It Ic permit-x11-forwarding
455Allows X11 forwarding.
456.It Ic source-address Ns = Ns Ar address_list
457Restrict the source addresses from which the certificate is considered valid.
458The
459.Ar address_list
460is a comma-separated list of one or more address/netmask pairs in CIDR
461format.
462.El
463.Pp
464At present, no options are valid for host keys.
465.It Fl o
466Causes
467.Nm
468to save SSH protocol 2 private keys using the new OpenSSH format rather than
469the more compatible PEM format.
470The new format has increased resistance to brute-force password cracking
471but is not supported by versions of OpenSSH prior to 6.5.
472Ed25519 keys always use the new private key format.
473.It Fl P Ar passphrase
474Provides the (old) passphrase.
475.It Fl p
476Requests changing the passphrase of a private key file instead of
477creating a new private key.
478The program will prompt for the file
479containing the private key, for the old passphrase, and twice for the
480new passphrase.
481.It Fl Q
482Test whether keys have been revoked in a KRL.
483.It Fl q
484Silence
485.Nm ssh-keygen .
486.It Fl R Ar hostname
487Removes all keys belonging to
488.Ar hostname
489from a
490.Pa known_hosts
491file.
492This option is useful to delete hashed hosts (see the
493.Fl H
494option above).
495.It Fl r Ar hostname
496Print the SSHFP fingerprint resource record named
497.Ar hostname
498for the specified public key file.
499.It Fl S Ar start
500Specify start point (in hex) when generating candidate moduli for DH-GEX.
501.It Fl s Ar ca_key
502Certify (sign) a public key using the specified CA key.
503Please see the
504.Sx CERTIFICATES
505section for details.
506.Pp
507When generating a KRL,
508.Fl s
509specifies a path to a CA public key file used to revoke certificates directly
510by key ID or serial number.
511See the
512.Sx KEY REVOCATION LISTS
513section for details.
514.It Fl T Ar output_file
515Test DH group exchange candidate primes (generated using the
516.Fl G
517option) for safety.
518.It Fl t Ar type
519Specifies the type of key to create.
520The possible values are
521.Dq rsa1
522for protocol version 1 and
523.Dq dsa ,
524.Dq ecdsa ,
525.Dq ed25519 ,
526or
527.Dq rsa
528for protocol version 2.
529.It Fl u
530Update a KRL.
531When specified with
532.Fl k ,
533keys listed via the command line are added to the existing KRL rather than
534a new KRL being created.
535.It Fl V Ar validity_interval
536Specify a validity interval when signing a certificate.
537A validity interval may consist of a single time, indicating that the
538certificate is valid beginning now and expiring at that time, or may consist
539of two times separated by a colon to indicate an explicit time interval.
540The start time may be specified as a date in YYYYMMDD format, a time
541in YYYYMMDDHHMMSS format or a relative time (to the current time) consisting
542of a minus sign followed by a relative time in the format described in the
543TIME FORMATS section of
544.Xr sshd_config 5 .
545The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMMSS time or
546a relative time starting with a plus character.
547.Pp
548For example:
549.Dq +52w1d
550(valid from now to 52 weeks and one day from now),
551.Dq -4w:+4w
552(valid from four weeks ago to four weeks from now),
553.Dq 20100101123000:20110101123000
554(valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011),
555.Dq -1d:20110101
556(valid from yesterday to midnight, January 1st, 2011).
557.It Fl v
558Verbose mode.
559Causes
560.Nm
561to print debugging messages about its progress.
562This is helpful for debugging moduli generation.
563Multiple
564.Fl v
565options increase the verbosity.
566The maximum is 3.
567.It Fl W Ar generator
568Specify desired generator when testing candidate moduli for DH-GEX.
569.It Fl y
570This option will read a private
571OpenSSH format file and print an OpenSSH public key to stdout.
572.It Fl z Ar serial_number
573Specifies a serial number to be embedded in the certificate to distinguish
574this certificate from others from the same CA.
575The default serial number is zero.
576.Pp
577When generating a KRL, the
578.Fl z
579flag is used to specify a KRL version number.
580.El
581.Sh MODULI GENERATION
582.Nm
583may be used to generate groups for the Diffie-Hellman Group Exchange
584(DH-GEX) protocol.
585Generating these groups is a two-step process: first, candidate
586primes are generated using a fast, but memory intensive process.
587These candidate primes are then tested for suitability (a CPU-intensive
588process).
589.Pp
590Generation of primes is performed using the
591.Fl G
592option.
593The desired length of the primes may be specified by the
594.Fl b
595option.
596For example:
597.Pp
598.Dl # ssh-keygen -G moduli-2048.candidates -b 2048
599.Pp
600By default, the search for primes begins at a random point in the
601desired length range.
602This may be overridden using the
603.Fl S
604option, which specifies a different start point (in hex).
605.Pp
606Once a set of candidates have been generated, they must be screened for
607suitability.
608This may be performed using the
609.Fl T
610option.
611In this mode
612.Nm
613will read candidates from standard input (or a file specified using the
614.Fl f
615option).
616For example:
617.Pp
618.Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
619.Pp
620By default, each candidate will be subjected to 100 primality tests.
621This may be overridden using the
622.Fl a
623option.
624The DH generator value will be chosen automatically for the
625prime under consideration.
626If a specific generator is desired, it may be requested using the
627.Fl W
628option.
629Valid generator values are 2, 3, and 5.
630.Pp
631Screened DH groups may be installed in
632.Pa /etc/moduli .
633It is important that this file contains moduli of a range of bit lengths and
634that both ends of a connection share common moduli.
635.Sh CERTIFICATES
636.Nm
637supports signing of keys to produce certificates that may be used for
638user or host authentication.
639Certificates consist of a public key, some identity information, zero or
640more principal (user or host) names and a set of options that
641are signed by a Certification Authority (CA) key.
642Clients or servers may then trust only the CA key and verify its signature
643on a certificate rather than trusting many user/host keys.
644Note that OpenSSH certificates are a different, and much simpler, format to
645the X.509 certificates used in
646.Xr ssl 8 .
647.Pp
648.Nm
649supports two types of certificates: user and host.
650User certificates authenticate users to servers, whereas host certificates
651authenticate server hosts to users.
652To generate a user certificate:
653.Pp
654.Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
655.Pp
656The resultant certificate will be placed in
657.Pa /path/to/user_key-cert.pub .
658A host certificate requires the
659.Fl h
660option:
661.Pp
662.Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
663.Pp
664The host certificate will be output to
665.Pa /path/to/host_key-cert.pub .
666.Pp
667It is possible to sign using a CA key stored in a PKCS#11 token by
668providing the token library using
669.Fl D
670and identifying the CA key by providing its public half as an argument
671to
672.Fl s :
673.Pp
674.Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub
675.Pp
676In all cases,
677.Ar key_id
678is a "key identifier" that is logged by the server when the certificate
679is used for authentication.
680.Pp
681Certificates may be limited to be valid for a set of principal (user/host)
682names.
683By default, generated certificates are valid for all users or hosts.
684To generate a certificate for a specified set of principals:
685.Pp
686.Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
687.Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub"
688.Pp
689Additional limitations on the validity and use of user certificates may
690be specified through certificate options.
691A certificate option may disable features of the SSH session, may be
692valid only when presented from particular source addresses or may
693force the use of a specific command.
694For a list of valid certificate options, see the documentation for the
695.Fl O
696option above.
697.Pp
698Finally, certificates may be defined with a validity lifetime.
699The
700.Fl V
701option allows specification of certificate start and end times.
702A certificate that is presented at a time outside this range will not be
703considered valid.
704By default, certificates are valid from
705.Ux
706Epoch to the distant future.
707.Pp
708For certificates to be used for user or host authentication, the CA
709public key must be trusted by
710.Xr sshd 8
711or
712.Xr ssh 1 .
713Please refer to those manual pages for details.
714.Sh KEY REVOCATION LISTS
715.Nm
716is able to manage OpenSSH format Key Revocation Lists (KRLs).
717These binary files specify keys or certificates to be revoked using a
718compact format, taking as little as one bit per certificate if they are being
719revoked by serial number.
720.Pp
721KRLs may be generated using the
722.Fl k
723flag.
724This option reads one or more files from the command line and generates a new
725KRL.
726The files may either contain a KRL specification (see below) or public keys,
727listed one per line.
728Plain public keys are revoked by listing their hash or contents in the KRL and
729certificates revoked by serial number or key ID (if the serial is zero or
730not available).
731.Pp
732Revoking keys using a KRL specification offers explicit control over the
733types of record used to revoke keys and may be used to directly revoke
734certificates by serial number or key ID without having the complete original
735certificate on hand.
736A KRL specification consists of lines containing one of the following directives
737followed by a colon and some directive-specific information.
738.Bl -tag -width Ds
739.It Cm serial : Ar serial_number Ns Op - Ns Ar serial_number
740Revokes a certificate with the specified serial number.
741Serial numbers are 64-bit values, not including zero and may be expressed
742in decimal, hex or octal.
743If two serial numbers are specified separated by a hyphen, then the range
744of serial numbers including and between each is revoked.
745The CA key must have been specified on the
746.Nm
747command line using the
748.Fl s
749option.
750.It Cm id : Ar key_id
751Revokes a certificate with the specified key ID string.
752The CA key must have been specified on the
753.Nm
754command line using the
755.Fl s
756option.
757.It Cm key : Ar public_key
758Revokes the specified key.
759If a certificate is listed, then it is revoked as a plain public key.
760.It Cm sha1 : Ar public_key
761Revokes the specified key by its SHA1 hash.
762.El
763.Pp
764KRLs may be updated using the
765.Fl u
766flag in addition to
767.Fl k .
768When this option is specified, keys listed via the command line are merged into
769the KRL, adding to those already there.
770.Pp
771It is also possible, given a KRL, to test whether it revokes a particular key
772(or keys).
773The
774.Fl Q
775flag will query an existing KRL, testing each key specified on the commandline.
776If any key listed on the command line has been revoked (or an error encountered)
777then
778.Nm
779will exit with a non-zero exit status.
780A zero exit status will only be returned if no key was revoked.
781.Sh FILES
782.Bl -tag -width Ds -compact
783.It Pa ~/.ssh/identity
784Contains the protocol version 1 RSA authentication identity of the user.
785This file should not be readable by anyone but the user.
786It is possible to
787specify a passphrase when generating the key; that passphrase will be
788used to encrypt the private part of this file using 3DES.
789This file is not automatically accessed by
790.Nm
791but it is offered as the default file for the private key.
792.Xr ssh 1
793will read this file when a login attempt is made.
794.Pp
795.It Pa ~/.ssh/identity.pub
796Contains the protocol version 1 RSA public key for authentication.
797The contents of this file should be added to
798.Pa ~/.ssh/authorized_keys
799on all machines
800where the user wishes to log in using RSA authentication.
801There is no need to keep the contents of this file secret.
802.Pp
803.It Pa ~/.ssh/id_dsa
804.It Pa ~/.ssh/id_ecdsa
805.It Pa ~/.ssh/id_ed25519
806.It Pa ~/.ssh/id_rsa
807Contains the protocol version 2 DSA, ECDSA, ED25519 or RSA
808authentication identity of the user.
809This file should not be readable by anyone but the user.
810It is possible to
811specify a passphrase when generating the key; that passphrase will be
812used to encrypt the private part of this file using 128-bit AES.
813This file is not automatically accessed by
814.Nm
815but it is offered as the default file for the private key.
816.Xr ssh 1
817will read this file when a login attempt is made.
818.Pp
819.It Pa ~/.ssh/id_dsa.pub
820.It Pa ~/.ssh/id_ecdsa.pub
821.It Pa ~/.ssh/id_ed25519.pub
822.It Pa ~/.ssh/id_rsa.pub
823Contains the protocol version 2 DSA, ECDSA, ED25519 or RSA
824public key for authentication.
825The contents of this file should be added to
826.Pa ~/.ssh/authorized_keys
827on all machines
828where the user wishes to log in using public key authentication.
829There is no need to keep the contents of this file secret.
830.Pp
831.It Pa /etc/moduli
832Contains Diffie-Hellman groups used for DH-GEX.
833The file format is described in
834.Xr moduli 5 .
835.El
836.Sh SEE ALSO
837.Xr ssh 1 ,
838.Xr ssh-add 1 ,
839.Xr ssh-agent 1 ,
840.Xr moduli 5 ,
841.Xr sshd 8
842.Rs
843.%R RFC 4716
844.%T "The Secure Shell (SSH) Public Key File Format"
845.%D 2006
846.Re
847.Sh AUTHORS
848OpenSSH is a derivative of the original and free
849ssh 1.2.12 release by Tatu Ylonen.
850Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
851Theo de Raadt and Dug Song
852removed many bugs, re-added newer features and
853created OpenSSH.
854Markus Friedl contributed the support for SSH
855protocol versions 1.5 and 2.0.
| 39.Dt SSH-KEYGEN 1
40.Os
41.Sh NAME
42.Nm ssh-keygen
43.Nd authentication key generation, management and conversion
44.Sh SYNOPSIS
45.Bk -words
46.Nm ssh-keygen
47.Op Fl q
48.Op Fl b Ar bits
49.Op Fl t Ar type
50.Op Fl N Ar new_passphrase
51.Op Fl C Ar comment
52.Op Fl f Ar output_keyfile
53.Nm ssh-keygen
54.Fl p
55.Op Fl P Ar old_passphrase
56.Op Fl N Ar new_passphrase
57.Op Fl f Ar keyfile
58.Nm ssh-keygen
59.Fl i
60.Op Fl m Ar key_format
61.Op Fl f Ar input_keyfile
62.Nm ssh-keygen
63.Fl e
64.Op Fl m Ar key_format
65.Op Fl f Ar input_keyfile
66.Nm ssh-keygen
67.Fl y
68.Op Fl f Ar input_keyfile
69.Nm ssh-keygen
70.Fl c
71.Op Fl P Ar passphrase
72.Op Fl C Ar comment
73.Op Fl f Ar keyfile
74.Nm ssh-keygen
75.Fl l
76.Op Fl f Ar input_keyfile
77.Nm ssh-keygen
78.Fl B
79.Op Fl f Ar input_keyfile
80.Nm ssh-keygen
81.Fl D Ar pkcs11
82.Nm ssh-keygen
83.Fl F Ar hostname
84.Op Fl f Ar known_hosts_file
85.Op Fl l
86.Nm ssh-keygen
87.Fl H
88.Op Fl f Ar known_hosts_file
89.Nm ssh-keygen
90.Fl R Ar hostname
91.Op Fl f Ar known_hosts_file
92.Nm ssh-keygen
93.Fl r Ar hostname
94.Op Fl f Ar input_keyfile
95.Op Fl g
96.Nm ssh-keygen
97.Fl G Ar output_file
98.Op Fl v
99.Op Fl b Ar bits
100.Op Fl M Ar memory
101.Op Fl S Ar start_point
102.Nm ssh-keygen
103.Fl T Ar output_file
104.Fl f Ar input_file
105.Op Fl v
106.Op Fl a Ar rounds
107.Op Fl J Ar num_lines
108.Op Fl j Ar start_line
109.Op Fl K Ar checkpt
110.Op Fl W Ar generator
111.Nm ssh-keygen
112.Fl s Ar ca_key
113.Fl I Ar certificate_identity
114.Op Fl h
115.Op Fl n Ar principals
116.Op Fl O Ar option
117.Op Fl V Ar validity_interval
118.Op Fl z Ar serial_number
119.Ar
120.Nm ssh-keygen
121.Fl L
122.Op Fl f Ar input_keyfile
123.Nm ssh-keygen
124.Fl A
125.Nm ssh-keygen
126.Fl k
127.Fl f Ar krl_file
128.Op Fl u
129.Op Fl s Ar ca_public
130.Op Fl z Ar version_number
131.Ar
132.Nm ssh-keygen
133.Fl Q
134.Fl f Ar krl_file
135.Ar
136.Ek
137.Sh DESCRIPTION
138.Nm
139generates, manages and converts authentication keys for
140.Xr ssh 1 .
141.Nm
142can create RSA keys for use by SSH protocol version 1 and
143DSA, ECDSA, ED25519 or RSA keys for use by SSH protocol version 2.
144The type of key to be generated is specified with the
145.Fl t
146option.
147If invoked without any arguments,
148.Nm
149will generate an RSA key for use in SSH protocol 2 connections.
150.Pp
151.Nm
152is also used to generate groups for use in Diffie-Hellman group
153exchange (DH-GEX).
154See the
155.Sx MODULI GENERATION
156section for details.
157.Pp
158Finally,
159.Nm
160can be used to generate and update Key Revocation Lists, and to test whether
161given keys have been revoked by one.
162See the
163.Sx KEY REVOCATION LISTS
164section for details.
165.Pp
166Normally each user wishing to use SSH
167with public key authentication runs this once to create the authentication
168key in
169.Pa ~/.ssh/identity ,
170.Pa ~/.ssh/id_dsa ,
171.Pa ~/.ssh/id_ecdsa ,
172.Pa ~/.ssh/id_ed25519
173or
174.Pa ~/.ssh/id_rsa .
175Additionally, the system administrator may use this to generate host keys,
176as seen in
177.Pa /etc/rc .
178.Pp
179Normally this program generates the key and asks for a file in which
180to store the private key.
181The public key is stored in a file with the same name but
182.Dq .pub
183appended.
184The program also asks for a passphrase.
185The passphrase may be empty to indicate no passphrase
186(host keys must have an empty passphrase), or it may be a string of
187arbitrary length.
188A passphrase is similar to a password, except it can be a phrase with a
189series of words, punctuation, numbers, whitespace, or any string of
190characters you want.
191Good passphrases are 10-30 characters long, are
192not simple sentences or otherwise easily guessable (English
193prose has only 1-2 bits of entropy per character, and provides very bad
194passphrases), and contain a mix of upper and lowercase letters,
195numbers, and non-alphanumeric characters.
196The passphrase can be changed later by using the
197.Fl p
198option.
199.Pp
200There is no way to recover a lost passphrase.
201If the passphrase is lost or forgotten, a new key must be generated
202and the corresponding public key copied to other machines.
203.Pp
204For RSA1 keys,
205there is also a comment field in the key file that is only for
206convenience to the user to help identify the key.
207The comment can tell what the key is for, or whatever is useful.
208The comment is initialized to
209.Dq user@host
210when the key is created, but can be changed using the
211.Fl c
212option.
213.Pp
214After a key is generated, instructions below detail where the keys
215should be placed to be activated.
216.Pp
217The options are as follows:
218.Bl -tag -width Ds
219.It Fl A
220For each of the key types (rsa1, rsa, dsa, ecdsa and ed25519)
221for which host keys
222do not exist, generate the host keys with the default key file path,
223an empty passphrase, default bits for the key type, and default comment.
224This is used by
225.Pa /etc/rc
226to generate new host keys.
227.It Fl a Ar rounds
228When saving a new-format private key (i.e. an ed25519 key or any SSH protocol
2292 key when the
230.Fl o
231flag is set), this option specifies the number of KDF (key derivation function)
232rounds used.
233Higher numbers result in slower passphrase verification and increased
234resistance to brute-force password cracking (should the keys be stolen).
235.Pp
236When screening DH-GEX candidates (
237using the
238.Fl T
239command).
240This option specifies the number of primality tests to perform.
241.It Fl B
242Show the bubblebabble digest of specified private or public key file.
243.It Fl b Ar bits
244Specifies the number of bits in the key to create.
245For RSA keys, the minimum size is 768 bits and the default is 2048 bits.
246Generally, 2048 bits is considered sufficient.
247DSA keys must be exactly 1024 bits as specified by FIPS 186-2.
248For ECDSA keys, the
249.Fl b
250flag determines the key length by selecting from one of three elliptic
251curve sizes: 256, 384 or 521 bits.
252Attempting to use bit lengths other than these three values for ECDSA keys
253will fail.
254ED25519 keys have a fixed length and the
255.Fl b
256flag will be ignored.
257.It Fl C Ar comment
258Provides a new comment.
259.It Fl c
260Requests changing the comment in the private and public key files.
261This operation is only supported for RSA1 keys.
262The program will prompt for the file containing the private keys, for
263the passphrase if the key has one, and for the new comment.
264.It Fl D Ar pkcs11
265Download the RSA public keys provided by the PKCS#11 shared library
266.Ar pkcs11 .
267When used in combination with
268.Fl s ,
269this option indicates that a CA key resides in a PKCS#11 token (see the
270.Sx CERTIFICATES
271section for details).
272.It Fl e
273This option will read a private or public OpenSSH key file and
274print to stdout the key in one of the formats specified by the
275.Fl m
276option.
277The default export format is
278.Dq RFC4716 .
279This option allows exporting OpenSSH keys for use by other programs, including
280several commercial SSH implementations.
281.It Fl F Ar hostname
282Search for the specified
283.Ar hostname
284in a
285.Pa known_hosts
286file, listing any occurrences found.
287This option is useful to find hashed host names or addresses and may also be
288used in conjunction with the
289.Fl H
290option to print found keys in a hashed format.
291.It Fl f Ar filename
292Specifies the filename of the key file.
293.It Fl G Ar output_file
294Generate candidate primes for DH-GEX.
295These primes must be screened for
296safety (using the
297.Fl T
298option) before use.
299.It Fl g
300Use generic DNS format when printing fingerprint resource records using the
301.Fl r
302command.
303.It Fl H
304Hash a
305.Pa known_hosts
306file.
307This replaces all hostnames and addresses with hashed representations
308within the specified file; the original content is moved to a file with
309a .old suffix.
310These hashes may be used normally by
311.Nm ssh
312and
313.Nm sshd ,
314but they do not reveal identifying information should the file's contents
315be disclosed.
316This option will not modify existing hashed hostnames and is therefore safe
317to use on files that mix hashed and non-hashed names.
318.It Fl h
319When signing a key, create a host certificate instead of a user
320certificate.
321Please see the
322.Sx CERTIFICATES
323section for details.
324.It Fl I Ar certificate_identity
325Specify the key identity when signing a public key.
326Please see the
327.Sx CERTIFICATES
328section for details.
329.It Fl i
330This option will read an unencrypted private (or public) key file
331in the format specified by the
332.Fl m
333option and print an OpenSSH compatible private
334(or public) key to stdout.
335.It Fl J Ar num_lines
336Exit after screening the specified number of lines
337while performing DH candidate screening using the
338.Fl T
339option.
340.It Fl j Ar start_line
341Start screening at the specified line number
342while performing DH candidate screening using the
343.Fl T
344option.
345.It Fl K Ar checkpt
346Write the last line processed to the file
347.Ar checkpt
348while performing DH candidate screening using the
349.Fl T
350option.
351This will be used to skip lines in the input file that have already been
352processed if the job is restarted.
353This option allows importing keys from other software, including several
354commercial SSH implementations.
355The default import format is
356.Dq RFC4716 .
357.It Fl k
358Generate a KRL file.
359In this mode,
360.Nm
361will generate a KRL file at the location specified via the
362.Fl f
363flag that revokes every key or certificate presented on the command line.
364Keys/certificates to be revoked may be specified by public key file or
365using the format described in the
366.Sx KEY REVOCATION LISTS
367section.
368.It Fl L
369Prints the contents of a certificate.
370.It Fl l
371Show fingerprint of specified public key file.
372Private RSA1 keys are also supported.
373For RSA and DSA keys
374.Nm
375tries to find the matching public key file and prints its fingerprint.
376If combined with
377.Fl v ,
378an ASCII art representation of the key is supplied with the fingerprint.
379.It Fl M Ar memory
380Specify the amount of memory to use (in megabytes) when generating
381candidate moduli for DH-GEX.
382.It Fl m Ar key_format
383Specify a key format for the
384.Fl i
385(import) or
386.Fl e
387(export) conversion options.
388The supported key formats are:
389.Dq RFC4716
390(RFC 4716/SSH2 public or private key),
391.Dq PKCS8
392(PEM PKCS8 public key)
393or
394.Dq PEM
395(PEM public key).
396The default conversion format is
397.Dq RFC4716 .
398.It Fl N Ar new_passphrase
399Provides the new passphrase.
400.It Fl n Ar principals
401Specify one or more principals (user or host names) to be included in
402a certificate when signing a key.
403Multiple principals may be specified, separated by commas.
404Please see the
405.Sx CERTIFICATES
406section for details.
407.It Fl O Ar option
408Specify a certificate option when signing a key.
409This option may be specified multiple times.
410Please see the
411.Sx CERTIFICATES
412section for details.
413The options that are valid for user certificates are:
414.Bl -tag -width Ds
415.It Ic clear
416Clear all enabled permissions.
417This is useful for clearing the default set of permissions so permissions may
418be added individually.
419.It Ic force-command Ns = Ns Ar command
420Forces the execution of
421.Ar command
422instead of any shell or command specified by the user when
423the certificate is used for authentication.
424.It Ic no-agent-forwarding
425Disable
426.Xr ssh-agent 1
427forwarding (permitted by default).
428.It Ic no-port-forwarding
429Disable port forwarding (permitted by default).
430.It Ic no-pty
431Disable PTY allocation (permitted by default).
432.It Ic no-user-rc
433Disable execution of
434.Pa ~/.ssh/rc
435by
436.Xr sshd 8
437(permitted by default).
438.It Ic no-x11-forwarding
439Disable X11 forwarding (permitted by default).
440.It Ic permit-agent-forwarding
441Allows
442.Xr ssh-agent 1
443forwarding.
444.It Ic permit-port-forwarding
445Allows port forwarding.
446.It Ic permit-pty
447Allows PTY allocation.
448.It Ic permit-user-rc
449Allows execution of
450.Pa ~/.ssh/rc
451by
452.Xr sshd 8 .
453.It Ic permit-x11-forwarding
454Allows X11 forwarding.
455.It Ic source-address Ns = Ns Ar address_list
456Restrict the source addresses from which the certificate is considered valid.
457The
458.Ar address_list
459is a comma-separated list of one or more address/netmask pairs in CIDR
460format.
461.El
462.Pp
463At present, no options are valid for host keys.
464.It Fl o
465Causes
466.Nm
467to save SSH protocol 2 private keys using the new OpenSSH format rather than
468the more compatible PEM format.
469The new format has increased resistance to brute-force password cracking
470but is not supported by versions of OpenSSH prior to 6.5.
471Ed25519 keys always use the new private key format.
472.It Fl P Ar passphrase
473Provides the (old) passphrase.
474.It Fl p
475Requests changing the passphrase of a private key file instead of
476creating a new private key.
477The program will prompt for the file
478containing the private key, for the old passphrase, and twice for the
479new passphrase.
480.It Fl Q
481Test whether keys have been revoked in a KRL.
482.It Fl q
483Silence
484.Nm ssh-keygen .
485.It Fl R Ar hostname
486Removes all keys belonging to
487.Ar hostname
488from a
489.Pa known_hosts
490file.
491This option is useful to delete hashed hosts (see the
492.Fl H
493option above).
494.It Fl r Ar hostname
495Print the SSHFP fingerprint resource record named
496.Ar hostname
497for the specified public key file.
498.It Fl S Ar start
499Specify start point (in hex) when generating candidate moduli for DH-GEX.
500.It Fl s Ar ca_key
501Certify (sign) a public key using the specified CA key.
502Please see the
503.Sx CERTIFICATES
504section for details.
505.Pp
506When generating a KRL,
507.Fl s
508specifies a path to a CA public key file used to revoke certificates directly
509by key ID or serial number.
510See the
511.Sx KEY REVOCATION LISTS
512section for details.
513.It Fl T Ar output_file
514Test DH group exchange candidate primes (generated using the
515.Fl G
516option) for safety.
517.It Fl t Ar type
518Specifies the type of key to create.
519The possible values are
520.Dq rsa1
521for protocol version 1 and
522.Dq dsa ,
523.Dq ecdsa ,
524.Dq ed25519 ,
525or
526.Dq rsa
527for protocol version 2.
528.It Fl u
529Update a KRL.
530When specified with
531.Fl k ,
532keys listed via the command line are added to the existing KRL rather than
533a new KRL being created.
534.It Fl V Ar validity_interval
535Specify a validity interval when signing a certificate.
536A validity interval may consist of a single time, indicating that the
537certificate is valid beginning now and expiring at that time, or may consist
538of two times separated by a colon to indicate an explicit time interval.
539The start time may be specified as a date in YYYYMMDD format, a time
540in YYYYMMDDHHMMSS format or a relative time (to the current time) consisting
541of a minus sign followed by a relative time in the format described in the
542TIME FORMATS section of
543.Xr sshd_config 5 .
544The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMMSS time or
545a relative time starting with a plus character.
546.Pp
547For example:
548.Dq +52w1d
549(valid from now to 52 weeks and one day from now),
550.Dq -4w:+4w
551(valid from four weeks ago to four weeks from now),
552.Dq 20100101123000:20110101123000
553(valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011),
554.Dq -1d:20110101
555(valid from yesterday to midnight, January 1st, 2011).
556.It Fl v
557Verbose mode.
558Causes
559.Nm
560to print debugging messages about its progress.
561This is helpful for debugging moduli generation.
562Multiple
563.Fl v
564options increase the verbosity.
565The maximum is 3.
566.It Fl W Ar generator
567Specify desired generator when testing candidate moduli for DH-GEX.
568.It Fl y
569This option will read a private
570OpenSSH format file and print an OpenSSH public key to stdout.
571.It Fl z Ar serial_number
572Specifies a serial number to be embedded in the certificate to distinguish
573this certificate from others from the same CA.
574The default serial number is zero.
575.Pp
576When generating a KRL, the
577.Fl z
578flag is used to specify a KRL version number.
579.El
580.Sh MODULI GENERATION
581.Nm
582may be used to generate groups for the Diffie-Hellman Group Exchange
583(DH-GEX) protocol.
584Generating these groups is a two-step process: first, candidate
585primes are generated using a fast, but memory intensive process.
586These candidate primes are then tested for suitability (a CPU-intensive
587process).
588.Pp
589Generation of primes is performed using the
590.Fl G
591option.
592The desired length of the primes may be specified by the
593.Fl b
594option.
595For example:
596.Pp
597.Dl # ssh-keygen -G moduli-2048.candidates -b 2048
598.Pp
599By default, the search for primes begins at a random point in the
600desired length range.
601This may be overridden using the
602.Fl S
603option, which specifies a different start point (in hex).
604.Pp
605Once a set of candidates have been generated, they must be screened for
606suitability.
607This may be performed using the
608.Fl T
609option.
610In this mode
611.Nm
612will read candidates from standard input (or a file specified using the
613.Fl f
614option).
615For example:
616.Pp
617.Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
618.Pp
619By default, each candidate will be subjected to 100 primality tests.
620This may be overridden using the
621.Fl a
622option.
623The DH generator value will be chosen automatically for the
624prime under consideration.
625If a specific generator is desired, it may be requested using the
626.Fl W
627option.
628Valid generator values are 2, 3, and 5.
629.Pp
630Screened DH groups may be installed in
631.Pa /etc/moduli .
632It is important that this file contains moduli of a range of bit lengths and
633that both ends of a connection share common moduli.
634.Sh CERTIFICATES
635.Nm
636supports signing of keys to produce certificates that may be used for
637user or host authentication.
638Certificates consist of a public key, some identity information, zero or
639more principal (user or host) names and a set of options that
640are signed by a Certification Authority (CA) key.
641Clients or servers may then trust only the CA key and verify its signature
642on a certificate rather than trusting many user/host keys.
643Note that OpenSSH certificates are a different, and much simpler, format to
644the X.509 certificates used in
645.Xr ssl 8 .
646.Pp
647.Nm
648supports two types of certificates: user and host.
649User certificates authenticate users to servers, whereas host certificates
650authenticate server hosts to users.
651To generate a user certificate:
652.Pp
653.Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
654.Pp
655The resultant certificate will be placed in
656.Pa /path/to/user_key-cert.pub .
657A host certificate requires the
658.Fl h
659option:
660.Pp
661.Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
662.Pp
663The host certificate will be output to
664.Pa /path/to/host_key-cert.pub .
665.Pp
666It is possible to sign using a CA key stored in a PKCS#11 token by
667providing the token library using
668.Fl D
669and identifying the CA key by providing its public half as an argument
670to
671.Fl s :
672.Pp
673.Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub
674.Pp
675In all cases,
676.Ar key_id
677is a "key identifier" that is logged by the server when the certificate
678is used for authentication.
679.Pp
680Certificates may be limited to be valid for a set of principal (user/host)
681names.
682By default, generated certificates are valid for all users or hosts.
683To generate a certificate for a specified set of principals:
684.Pp
685.Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
686.Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub"
687.Pp
688Additional limitations on the validity and use of user certificates may
689be specified through certificate options.
690A certificate option may disable features of the SSH session, may be
691valid only when presented from particular source addresses or may
692force the use of a specific command.
693For a list of valid certificate options, see the documentation for the
694.Fl O
695option above.
696.Pp
697Finally, certificates may be defined with a validity lifetime.
698The
699.Fl V
700option allows specification of certificate start and end times.
701A certificate that is presented at a time outside this range will not be
702considered valid.
703By default, certificates are valid from
704.Ux
705Epoch to the distant future.
706.Pp
707For certificates to be used for user or host authentication, the CA
708public key must be trusted by
709.Xr sshd 8
710or
711.Xr ssh 1 .
712Please refer to those manual pages for details.
713.Sh KEY REVOCATION LISTS
714.Nm
715is able to manage OpenSSH format Key Revocation Lists (KRLs).
716These binary files specify keys or certificates to be revoked using a
717compact format, taking as little as one bit per certificate if they are being
718revoked by serial number.
719.Pp
720KRLs may be generated using the
721.Fl k
722flag.
723This option reads one or more files from the command line and generates a new
724KRL.
725The files may either contain a KRL specification (see below) or public keys,
726listed one per line.
727Plain public keys are revoked by listing their hash or contents in the KRL and
728certificates revoked by serial number or key ID (if the serial is zero or
729not available).
730.Pp
731Revoking keys using a KRL specification offers explicit control over the
732types of record used to revoke keys and may be used to directly revoke
733certificates by serial number or key ID without having the complete original
734certificate on hand.
735A KRL specification consists of lines containing one of the following directives
736followed by a colon and some directive-specific information.
737.Bl -tag -width Ds
738.It Cm serial : Ar serial_number Ns Op - Ns Ar serial_number
739Revokes a certificate with the specified serial number.
740Serial numbers are 64-bit values, not including zero and may be expressed
741in decimal, hex or octal.
742If two serial numbers are specified separated by a hyphen, then the range
743of serial numbers including and between each is revoked.
744The CA key must have been specified on the
745.Nm
746command line using the
747.Fl s
748option.
749.It Cm id : Ar key_id
750Revokes a certificate with the specified key ID string.
751The CA key must have been specified on the
752.Nm
753command line using the
754.Fl s
755option.
756.It Cm key : Ar public_key
757Revokes the specified key.
758If a certificate is listed, then it is revoked as a plain public key.
759.It Cm sha1 : Ar public_key
760Revokes the specified key by its SHA1 hash.
761.El
762.Pp
763KRLs may be updated using the
764.Fl u
765flag in addition to
766.Fl k .
767When this option is specified, keys listed via the command line are merged into
768the KRL, adding to those already there.
769.Pp
770It is also possible, given a KRL, to test whether it revokes a particular key
771(or keys).
772The
773.Fl Q
774flag will query an existing KRL, testing each key specified on the commandline.
775If any key listed on the command line has been revoked (or an error encountered)
776then
777.Nm
778will exit with a non-zero exit status.
779A zero exit status will only be returned if no key was revoked.
780.Sh FILES
781.Bl -tag -width Ds -compact
782.It Pa ~/.ssh/identity
783Contains the protocol version 1 RSA authentication identity of the user.
784This file should not be readable by anyone but the user.
785It is possible to
786specify a passphrase when generating the key; that passphrase will be
787used to encrypt the private part of this file using 3DES.
788This file is not automatically accessed by
789.Nm
790but it is offered as the default file for the private key.
791.Xr ssh 1
792will read this file when a login attempt is made.
793.Pp
794.It Pa ~/.ssh/identity.pub
795Contains the protocol version 1 RSA public key for authentication.
796The contents of this file should be added to
797.Pa ~/.ssh/authorized_keys
798on all machines
799where the user wishes to log in using RSA authentication.
800There is no need to keep the contents of this file secret.
801.Pp
802.It Pa ~/.ssh/id_dsa
803.It Pa ~/.ssh/id_ecdsa
804.It Pa ~/.ssh/id_ed25519
805.It Pa ~/.ssh/id_rsa
806Contains the protocol version 2 DSA, ECDSA, ED25519 or RSA
807authentication identity of the user.
808This file should not be readable by anyone but the user.
809It is possible to
810specify a passphrase when generating the key; that passphrase will be
811used to encrypt the private part of this file using 128-bit AES.
812This file is not automatically accessed by
813.Nm
814but it is offered as the default file for the private key.
815.Xr ssh 1
816will read this file when a login attempt is made.
817.Pp
818.It Pa ~/.ssh/id_dsa.pub
819.It Pa ~/.ssh/id_ecdsa.pub
820.It Pa ~/.ssh/id_ed25519.pub
821.It Pa ~/.ssh/id_rsa.pub
822Contains the protocol version 2 DSA, ECDSA, ED25519 or RSA
823public key for authentication.
824The contents of this file should be added to
825.Pa ~/.ssh/authorized_keys
826on all machines
827where the user wishes to log in using public key authentication.
828There is no need to keep the contents of this file secret.
829.Pp
830.It Pa /etc/moduli
831Contains Diffie-Hellman groups used for DH-GEX.
832The file format is described in
833.Xr moduli 5 .
834.El
835.Sh SEE ALSO
836.Xr ssh 1 ,
837.Xr ssh-add 1 ,
838.Xr ssh-agent 1 ,
839.Xr moduli 5 ,
840.Xr sshd 8
841.Rs
842.%R RFC 4716
843.%T "The Secure Shell (SSH) Public Key File Format"
844.%D 2006
845.Re
846.Sh AUTHORS
847OpenSSH is a derivative of the original and free
848ssh 1.2.12 release by Tatu Ylonen.
849Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
850Theo de Raadt and Dug Song
851removed many bugs, re-added newer features and
852created OpenSSH.
853Markus Friedl contributed the support for SSH
854protocol versions 1.5 and 2.0.
|