blob: 7da73e07cd9185ba200e29956b8ba1f18642c870 [file] [log] [blame]
Damien Millera0a7ee82013-01-20 22:35:06 +11001.\" $OpenBSD: ssh-keygen.1,v 1.115 2013/01/19 07:13:25 jmc Exp $
Damien Miller32aa1441999-10-29 09:15:49 +10002.\"
Damien Miller32aa1441999-10-29 09:15:49 +10003.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
Damien Miller32aa1441999-10-29 09:15:49 +10004.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5.\" All rights reserved
6.\"
Damien Millere4340be2000-09-16 13:29:08 +11007.\" 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".
Damien Miller32aa1441999-10-29 09:15:49 +100012.\"
Damien Millere4340be2000-09-16 13:29:08 +110013.\"
Ben Lindstrom92a2e382001-03-05 06:59:27 +000014.\" 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.
Damien Millere4340be2000-09-16 13:29:08 +110017.\"
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.
Damien Miller32aa1441999-10-29 09:15:49 +100037.\"
Damien Millera0a7ee82013-01-20 22:35:06 +110038.Dd $Mdocdate: January 19 2013 $
Damien Miller32aa1441999-10-29 09:15:49 +100039.Dt SSH-KEYGEN 1
40.Os
41.Sh NAME
42.Nm ssh-keygen
Ben Lindstrom5a707822001-04-22 17:15:46 +000043.Nd authentication key generation, management and conversion
Damien Miller32aa1441999-10-29 09:15:49 +100044.Sh SYNOPSIS
Damien Miller495dca32003-04-01 21:42:14 +100045.Bk -words
Damien Millerbad5e032010-07-16 13:59:59 +100046.Nm ssh-keygen
Damien Miller0bc1bd82000-11-13 22:57:25 +110047.Op Fl q
Damien Miller32aa1441999-10-29 09:15:49 +100048.Op Fl b Ar bits
Damien Miller55fafa02002-02-19 15:22:07 +110049.Fl t Ar type
Damien Miller32aa1441999-10-29 09:15:49 +100050.Op Fl N Ar new_passphrase
51.Op Fl C Ar comment
Damien Miller1a425f32000-09-02 10:08:09 +110052.Op Fl f Ar output_keyfile
Damien Miller32aa1441999-10-29 09:15:49 +100053.Nm ssh-keygen
54.Fl p
55.Op Fl P Ar old_passphrase
56.Op Fl N Ar new_passphrase
Damien Miller10f6f6b1999-11-17 17:29:08 +110057.Op Fl f Ar keyfile
Damien Miller32aa1441999-10-29 09:15:49 +100058.Nm ssh-keygen
Ben Lindstrom5a707822001-04-22 17:15:46 +000059.Fl i
Damien Miller44b25042010-07-02 13:35:01 +100060.Op Fl m Ar key_format
Damien Miller1a425f32000-09-02 10:08:09 +110061.Op Fl f Ar input_keyfile
Damien Millere247cc42000-05-07 12:03:14 +100062.Nm ssh-keygen
Ben Lindstrom5a707822001-04-22 17:15:46 +000063.Fl e
Damien Miller44b25042010-07-02 13:35:01 +100064.Op Fl m Ar key_format
Damien Miller1a425f32000-09-02 10:08:09 +110065.Op Fl f Ar input_keyfile
Damien Millere247cc42000-05-07 12:03:14 +100066.Nm ssh-keygen
67.Fl y
Damien Miller1a425f32000-09-02 10:08:09 +110068.Op Fl f Ar input_keyfile
Damien Millere247cc42000-05-07 12:03:14 +100069.Nm ssh-keygen
Damien Miller32aa1441999-10-29 09:15:49 +100070.Fl c
71.Op Fl P Ar passphrase
72.Op Fl C Ar comment
Damien Miller10f6f6b1999-11-17 17:29:08 +110073.Op Fl f Ar keyfile
74.Nm ssh-keygen
75.Fl l
Ben Lindstrom8fd372b2001-03-12 03:02:17 +000076.Op Fl f Ar input_keyfile
77.Nm ssh-keygen
78.Fl B
Damien Miller1a425f32000-09-02 10:08:09 +110079.Op Fl f Ar input_keyfile
Ben Lindstroma1ec4a92001-08-06 21:51:34 +000080.Nm ssh-keygen
Damien Miller048dc932010-02-12 09:22:04 +110081.Fl D Ar pkcs11
Ben Lindstroma1ec4a92001-08-06 21:51:34 +000082.Nm ssh-keygen
Damien Miller4b42d7f2005-03-01 21:48:35 +110083.Fl F Ar hostname
84.Op Fl f Ar known_hosts_file
Damien Miller718ed502008-11-03 19:15:20 +110085.Op Fl l
Damien Miller4b42d7f2005-03-01 21:48:35 +110086.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
Damien Miller37876e92003-05-15 10:19:46 +100093.Fl r Ar hostname
94.Op Fl f Ar input_keyfile
95.Op Fl g
Darren Tucker019cefe2003-08-02 22:40:07 +100096.Nm ssh-keygen
97.Fl G Ar output_file
Darren Tucker06930c72003-12-31 11:34:51 +110098.Op Fl v
Darren Tucker019cefe2003-08-02 22:40:07 +100099.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
Darren Tucker06930c72003-12-31 11:34:51 +1100105.Op Fl v
Darren Tucker019cefe2003-08-02 22:40:07 +1000106.Op Fl a Ar num_trials
Damien Millerdfceafe2012-07-06 13:44:19 +1000107.Op Fl J Ar num_lines
108.Op Fl j Ar start_line
Damien Miller390d0562011-10-18 16:05:19 +1100109.Op Fl K Ar checkpt
Darren Tucker019cefe2003-08-02 22:40:07 +1000110.Op Fl W Ar generator
Damien Miller0a80ca12010-02-27 07:55:05 +1100111.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
Damien Miller4e270b02010-04-16 15:56:21 +1000116.Op Fl O Ar option
Damien Miller0a80ca12010-02-27 07:55:05 +1100117.Op Fl V Ar validity_interval
Damien Miller4e270b02010-04-16 15:56:21 +1000118.Op Fl z Ar serial_number
Damien Miller0a80ca12010-02-27 07:55:05 +1100119.Ar
Damien Millerf2b70ca2010-03-05 07:39:35 +1100120.Nm ssh-keygen
Damien Millerf2b70ca2010-03-05 07:39:35 +1100121.Fl L
122.Op Fl f Ar input_keyfile
Damien Miller58f1baf2011-05-05 14:06:15 +1000123.Nm ssh-keygen
124.Fl A
Damien Millerf3747bf2013-01-18 11:44:04 +1100125.Nm ssh-keygen
126.Fl k
127.Fl f Ar krl_file
128.Op Fl u
Damien Millerac5542b2013-01-20 22:33:02 +1100129.Op Fl s Ar ca_public
130.Op Fl z Ar version_number
Damien Millerf3747bf2013-01-18 11:44:04 +1100131.Ar
132.Nm ssh-keygen
133.Fl Q
134.Fl f Ar krl_file
135.Ar
Damien Miller15f5b562010-03-03 10:25:21 +1100136.Ek
Damien Miller22c77262000-04-13 12:26:34 +1000137.Sh DESCRIPTION
Damien Miller32aa1441999-10-29 09:15:49 +1000138.Nm
Ben Lindstrom5a707822001-04-22 17:15:46 +0000139generates, manages and converts authentication keys for
Damien Miller32aa1441999-10-29 09:15:49 +1000140.Xr ssh 1 .
Damien Millere247cc42000-05-07 12:03:14 +1000141.Nm
Damien Miller6186bbc2010-09-24 22:00:54 +1000142can create RSA keys for use by SSH protocol version 1 and DSA, ECDSA or RSA
Damien Millerfbf486b2003-05-23 18:44:23 +1000143keys for use by SSH protocol version 2.
144The type of key to be generated is specified with the
Damien Miller0bc1bd82000-11-13 22:57:25 +1100145.Fl t
Damien Millera41c8b12002-01-22 23:05:08 +1100146option.
Damien Millerf14be5c2005-11-05 15:15:49 +1100147If invoked without any arguments,
148.Nm
Damien Miller83d0d392005-11-05 15:16:27 +1100149will generate an RSA key for use in SSH protocol 2 connections.
Damien Millere247cc42000-05-07 12:03:14 +1000150.Pp
Darren Tucker019cefe2003-08-02 22:40:07 +1000151.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
Damien Millerf3747bf2013-01-18 11:44:04 +1100158Finally,
159.Nm
160can be used to generate and update Key Revocation Lists, and to test whether
Damien Millerac5542b2013-01-20 22:33:02 +1100161given keys have been revoked by one.
162See the
Damien Millerf3747bf2013-01-18 11:44:04 +1100163.Sx KEY REVOCATION LISTS
164section for details.
165.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000166Normally each user wishing to use SSH
Damien Millereb8b60e2010-08-31 22:41:14 +1000167with public key authentication runs this once to create the authentication
Damien Miller32aa1441999-10-29 09:15:49 +1000168key in
Damien Miller167ea5d2005-05-26 12:04:02 +1000169.Pa ~/.ssh/identity ,
Damien Millereb8b60e2010-08-31 22:41:14 +1000170.Pa ~/.ssh/id_ecdsa ,
Damien Miller167ea5d2005-05-26 12:04:02 +1000171.Pa ~/.ssh/id_dsa
Damien Millere247cc42000-05-07 12:03:14 +1000172or
Damien Miller167ea5d2005-05-26 12:04:02 +1000173.Pa ~/.ssh/id_rsa .
Damien Millere247cc42000-05-07 12:03:14 +1000174Additionally, the system administrator may use this to generate host keys,
175as seen in
176.Pa /etc/rc .
Damien Miller32aa1441999-10-29 09:15:49 +1000177.Pp
178Normally this program generates the key and asks for a file in which
Damien Miller450a7a12000-03-26 13:04:51 +1000179to store the private key.
180The public key is stored in a file with the same name but
Damien Miller32aa1441999-10-29 09:15:49 +1000181.Dq .pub
Damien Miller450a7a12000-03-26 13:04:51 +1000182appended.
183The program also asks for a passphrase.
184The passphrase may be empty to indicate no passphrase
Ben Lindstrombf555ba2001-01-18 02:04:35 +0000185(host keys must have an empty passphrase), or it may be a string of
Damien Miller450a7a12000-03-26 13:04:51 +1000186arbitrary length.
Ben Lindstrom4e366d52001-12-06 16:43:21 +0000187A passphrase is similar to a password, except it can be a phrase with a
188series of words, punctuation, numbers, whitespace, or any string of
189characters you want.
190Good passphrases are 10-30 characters long, are
Damien Miller32aa1441999-10-29 09:15:49 +1000191not simple sentences or otherwise easily guessable (English
Ben Lindstrom2a097a42001-06-09 01:13:40 +0000192prose has only 1-2 bits of entropy per character, and provides very bad
Ben Lindstrom4e366d52001-12-06 16:43:21 +0000193passphrases), and contain a mix of upper and lowercase letters,
194numbers, and non-alphanumeric characters.
Damien Miller450a7a12000-03-26 13:04:51 +1000195The passphrase can be changed later by using the
Damien Miller32aa1441999-10-29 09:15:49 +1000196.Fl p
197option.
198.Pp
Damien Miller450a7a12000-03-26 13:04:51 +1000199There is no way to recover a lost passphrase.
Damien Miller085c90f2011-05-05 14:15:33 +1000200If the passphrase is lost or forgotten, a new key must be generated
201and the corresponding public key copied to other machines.
Damien Miller32aa1441999-10-29 09:15:49 +1000202.Pp
Ben Lindstrom5a707822001-04-22 17:15:46 +0000203For RSA1 keys,
204there is also a comment field in the key file that is only for
Damien Miller450a7a12000-03-26 13:04:51 +1000205convenience to the user to help identify the key.
206The comment can tell what the key is for, or whatever is useful.
207The comment is initialized to
Damien Miller32aa1441999-10-29 09:15:49 +1000208.Dq user@host
209when the key is created, but can be changed using the
210.Fl c
211option.
212.Pp
Damien Millere247cc42000-05-07 12:03:14 +1000213After a key is generated, instructions below detail where the keys
214should be placed to be activated.
215.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000216The options are as follows:
217.Bl -tag -width Ds
Damien Miller58f1baf2011-05-05 14:06:15 +1000218.It Fl A
219For each of the key types (rsa1, rsa, dsa and ecdsa) for which host keys
220do not exist, generate the host keys with the default key file path,
221an empty passphrase, default bits for the key type, and default comment.
Damien Miller3ca1eb32011-05-05 14:13:50 +1000222This is used by
Damien Miller58f1baf2011-05-05 14:06:15 +1000223.Pa /etc/rc
224to generate new host keys.
Darren Tucker019cefe2003-08-02 22:40:07 +1000225.It Fl a Ar trials
226Specifies the number of primality tests to perform when screening DH-GEX
227candidates using the
228.Fl T
229command.
Damien Miller265d3092005-03-02 12:05:06 +1100230.It Fl B
231Show the bubblebabble digest of specified private or public key file.
Damien Miller32aa1441999-10-29 09:15:49 +1000232.It Fl b Ar bits
Damien Miller450a7a12000-03-26 13:04:51 +1000233Specifies the number of bits in the key to create.
Darren Tucker9f647332005-11-28 16:41:46 +1100234For RSA keys, the minimum size is 768 bits and the default is 2048 bits.
Damien Millerac7ef6a2005-06-16 13:19:06 +1000235Generally, 2048 bits is considered sufficient.
Darren Tucker9f647332005-11-28 16:41:46 +1100236DSA keys must be exactly 1024 bits as specified by FIPS 186-2.
Damien Millerad210322011-05-05 14:15:54 +1000237For ECDSA keys, the
238.Fl b
Damien Miller6232a162011-09-22 21:36:00 +1000239flag determines the key length by selecting from one of three elliptic
Damien Millerad210322011-05-05 14:15:54 +1000240curve sizes: 256, 384 or 521 bits.
241Attempting to use bit lengths other than these three values for ECDSA keys
242will fail.
Damien Miller265d3092005-03-02 12:05:06 +1100243.It Fl C Ar comment
244Provides a new comment.
Damien Miller32aa1441999-10-29 09:15:49 +1000245.It Fl c
246Requests changing the comment in the private and public key files.
Damien Millereb5fec62001-11-12 10:52:44 +1100247This operation is only supported for RSA1 keys.
Damien Miller32aa1441999-10-29 09:15:49 +1000248The program will prompt for the file containing the private keys, for
Ben Lindstromaafff9c2001-05-06 03:01:02 +0000249the passphrase if the key has one, and for the new comment.
Damien Miller7ea845e2010-02-12 09:21:02 +1100250.It Fl D Ar pkcs11
Damien Millera7618442010-02-12 09:26:02 +1100251Download the RSA public keys provided by the PKCS#11 shared library
252.Ar pkcs11 .
Damien Miller757f34e2010-08-05 13:05:31 +1000253When used in combination with
254.Fl s ,
255this option indicates that a CA key resides in a PKCS#11 token (see the
256.Sx CERTIFICATES
257section for details).
Ben Lindstrom5a707822001-04-22 17:15:46 +0000258.It Fl e
Ben Lindstrom46c264f2001-04-24 16:56:58 +0000259This option will read a private or public OpenSSH key file and
Damien Miller44b25042010-07-02 13:35:01 +1000260print to stdout the key in one of the formats specified by the
261.Fl m
262option.
263The default export format is
264.Dq RFC4716 .
Damien Millerea727282010-07-02 13:35:34 +1000265This option allows exporting OpenSSH keys for use by other programs, including
Damien Miller44b25042010-07-02 13:35:01 +1000266several commercial SSH implementations.
Damien Miller265d3092005-03-02 12:05:06 +1100267.It Fl F Ar hostname
268Search for the specified
269.Ar hostname
270in a
271.Pa known_hosts
272file, listing any occurrences found.
273This option is useful to find hashed host names or addresses and may also be
274used in conjunction with the
275.Fl H
276option to print found keys in a hashed format.
277.It Fl f Ar filename
278Specifies the filename of the key file.
279.It Fl G Ar output_file
280Generate candidate primes for DH-GEX.
281These primes must be screened for
282safety (using the
283.Fl T
284option) before use.
Damien Miller37876e92003-05-15 10:19:46 +1000285.It Fl g
Darren Tucker0b42e6d2004-08-13 21:22:40 +1000286Use generic DNS format when printing fingerprint resource records using the
Darren Tucker6e370372004-08-13 21:23:25 +1000287.Fl r
Darren Tucker0b42e6d2004-08-13 21:22:40 +1000288command.
Damien Miller265d3092005-03-02 12:05:06 +1100289.It Fl H
290Hash a
291.Pa known_hosts
Darren Tuckerda1adbc2005-03-14 23:15:58 +1100292file.
293This replaces all hostnames and addresses with hashed representations
294within the specified file; the original content is moved to a file with
295a .old suffix.
Damien Miller265d3092005-03-02 12:05:06 +1100296These hashes may be used normally by
297.Nm ssh
298and
299.Nm sshd ,
300but they do not reveal identifying information should the file's contents
301be disclosed.
302This option will not modify existing hashed hostnames and is therefore safe
303to use on files that mix hashed and non-hashed names.
Damien Miller0a80ca12010-02-27 07:55:05 +1100304.It Fl h
305When signing a key, create a host certificate instead of a user
306certificate.
307Please see the
308.Sx CERTIFICATES
309section for details.
Damien Miller15f5b562010-03-03 10:25:21 +1100310.It Fl I Ar certificate_identity
Damien Miller0a80ca12010-02-27 07:55:05 +1100311Specify the key identity when signing a public key.
312Please see the
313.Sx CERTIFICATES
314section for details.
Ben Lindstrom5a707822001-04-22 17:15:46 +0000315.It Fl i
316This option will read an unencrypted private (or public) key file
Damien Miller44b25042010-07-02 13:35:01 +1000317in the format specified by the
318.Fl m
319option and print an OpenSSH compatible private
Ben Lindstrom5a707822001-04-22 17:15:46 +0000320(or public) key to stdout.
Damien Millerdfceafe2012-07-06 13:44:19 +1000321.It Fl J Ar num_lines
322Exit after screening the specified number of lines
323while performing DH candidate screening using the
324.Fl T
325option.
326.It Fl j Ar start_line
327Start screening at the specified line number
328while performing DH candidate screening using the
329.Fl T
330option.
Damien Miller390d0562011-10-18 16:05:19 +1100331.It Fl K Ar checkpt
332Write the last line processed to the file
333.Ar checkpt
334while performing DH candidate screening using the
335.Fl T
336option.
337This will be used to skip lines in the input file that have already been
338processed if the job is restarted.
Damien Miller44b25042010-07-02 13:35:01 +1000339This option allows importing keys from other software, including several
340commercial SSH implementations.
341The default import format is
342.Dq RFC4716 .
Damien Millerf3747bf2013-01-18 11:44:04 +1100343.It Fl k
344Generate a KRL file.
345In this mode,
346.Nm
347will generate a KRL file at the location specified via the
348.Fl f
Damien Miller881a7a22013-01-20 22:34:46 +1100349flag that revokes every key or certificate presented on the command line.
Damien Millerf3747bf2013-01-18 11:44:04 +1100350Keys/certificates to be revoked may be specified by public key file or
351using the format described in the
352.Sx KEY REVOCATION LISTS
353section.
Damien Millerf2b70ca2010-03-05 07:39:35 +1100354.It Fl L
355Prints the contents of a certificate.
Damien Miller10f6f6b1999-11-17 17:29:08 +1100356.It Fl l
Darren Tucker35c45532008-06-13 04:43:15 +1000357Show fingerprint of specified public key file.
Damien Millereb5fec62001-11-12 10:52:44 +1100358Private RSA1 keys are also supported.
359For RSA and DSA keys
360.Nm
Darren Tuckerf09e8252008-06-13 05:18:03 +1000361tries to find the matching public key file and prints its fingerprint.
362If combined with
363.Fl v ,
364an ASCII art representation of the key is supplied with the fingerprint.
Damien Millerea727282010-07-02 13:35:34 +1000365.It Fl M Ar memory
366Specify the amount of memory to use (in megabytes) when generating
367candidate moduli for DH-GEX.
Damien Miller44b25042010-07-02 13:35:01 +1000368.It Fl m Ar key_format
369Specify a key format for the
370.Fl i
371(import) or
372.Fl e
Damien Millerea727282010-07-02 13:35:34 +1000373(export) conversion options.
Damien Miller44b25042010-07-02 13:35:01 +1000374The supported key formats are:
375.Dq RFC4716
Damien Millerea727282010-07-02 13:35:34 +1000376(RFC 4716/SSH2 public or private key),
Damien Miller44b25042010-07-02 13:35:01 +1000377.Dq PKCS8
378(PEM PKCS8 public key)
379or
380.Dq PEM
381(PEM public key).
382The default conversion format is
383.Dq RFC4716 .
Damien Miller265d3092005-03-02 12:05:06 +1100384.It Fl N Ar new_passphrase
385Provides the new passphrase.
Damien Miller0a80ca12010-02-27 07:55:05 +1100386.It Fl n Ar principals
387Specify one or more principals (user or host names) to be included in
388a certificate when signing a key.
389Multiple principals may be specified, separated by commas.
390Please see the
391.Sx CERTIFICATES
392section for details.
Damien Miller4e270b02010-04-16 15:56:21 +1000393.It Fl O Ar option
394Specify a certificate option when signing a key.
Damien Miller0a80ca12010-02-27 07:55:05 +1100395This option may be specified multiple times.
396Please see the
397.Sx CERTIFICATES
398section for details.
Damien Miller4e270b02010-04-16 15:56:21 +1000399The options that are valid for user certificates are:
Damien Miller0a80ca12010-02-27 07:55:05 +1100400.Bl -tag -width Ds
Damien Millerc59e2442010-03-22 05:50:31 +1100401.It Ic clear
402Clear all enabled permissions.
403This is useful for clearing the default set of permissions so permissions may
404be added individually.
405.It Ic force-command Ns = Ns Ar command
406Forces the execution of
407.Ar command
408instead of any shell or command specified by the user when
409the certificate is used for authentication.
Damien Miller0a80ca12010-02-27 07:55:05 +1100410.It Ic no-agent-forwarding
411Disable
412.Xr ssh-agent 1
Damien Miller15f5b562010-03-03 10:25:21 +1100413forwarding (permitted by default).
Damien Miller0a80ca12010-02-27 07:55:05 +1100414.It Ic no-port-forwarding
Damien Miller15f5b562010-03-03 10:25:21 +1100415Disable port forwarding (permitted by default).
Damien Miller0a80ca12010-02-27 07:55:05 +1100416.It Ic no-pty
Damien Miller15f5b562010-03-03 10:25:21 +1100417Disable PTY allocation (permitted by default).
Damien Miller0a80ca12010-02-27 07:55:05 +1100418.It Ic no-user-rc
419Disable execution of
420.Pa ~/.ssh/rc
421by
Damien Miller15f5b562010-03-03 10:25:21 +1100422.Xr sshd 8
423(permitted by default).
Damien Millerc59e2442010-03-22 05:50:31 +1100424.It Ic no-x11-forwarding
425Disable X11 forwarding (permitted by default).
Damien Miller081c9762010-03-08 11:30:00 +1100426.It Ic permit-agent-forwarding
427Allows
428.Xr ssh-agent 1
429forwarding.
Damien Miller0a80ca12010-02-27 07:55:05 +1100430.It Ic permit-port-forwarding
431Allows port forwarding.
432.It Ic permit-pty
433Allows PTY allocation.
434.It Ic permit-user-rc
435Allows execution of
436.Pa ~/.ssh/rc
437by
438.Xr sshd 8 .
Damien Millerc59e2442010-03-22 05:50:31 +1100439.It Ic permit-x11-forwarding
440Allows X11 forwarding.
441.It Ic source-address Ns = Ns Ar address_list
Damien Miller77497e12010-03-22 05:50:51 +1100442Restrict the source addresses from which the certificate is considered valid.
Damien Miller0a80ca12010-02-27 07:55:05 +1100443The
444.Ar address_list
445is a comma-separated list of one or more address/netmask pairs in CIDR
446format.
447.El
448.Pp
Damien Miller4e270b02010-04-16 15:56:21 +1000449At present, no options are valid for host keys.
Damien Miller265d3092005-03-02 12:05:06 +1100450.It Fl P Ar passphrase
451Provides the (old) passphrase.
Damien Miller32aa1441999-10-29 09:15:49 +1000452.It Fl p
453Requests changing the passphrase of a private key file instead of
Damien Miller450a7a12000-03-26 13:04:51 +1000454creating a new private key.
455The program will prompt for the file
Damien Miller32aa1441999-10-29 09:15:49 +1000456containing the private key, for the old passphrase, and twice for the
457new passphrase.
Damien Miller072fdcd2013-01-20 22:34:04 +1100458.It Fl Q
459Test whether keys have been revoked in a KRL.
Damien Miller32aa1441999-10-29 09:15:49 +1000460.It Fl q
461Silence
462.Nm ssh-keygen .
Damien Miller4b42d7f2005-03-01 21:48:35 +1100463.It Fl R Ar hostname
464Removes all keys belonging to
465.Ar hostname
Damien Miller4c9c6fd2005-03-02 12:03:43 +1100466from a
Damien Miller4b42d7f2005-03-01 21:48:35 +1100467.Pa known_hosts
468file.
Damien Miller4c9c6fd2005-03-02 12:03:43 +1100469This option is useful to delete hashed hosts (see the
Damien Miller4b42d7f2005-03-01 21:48:35 +1100470.Fl H
471option above).
Damien Miller265d3092005-03-02 12:05:06 +1100472.It Fl r Ar hostname
473Print the SSHFP fingerprint resource record named
474.Ar hostname
475for the specified public key file.
Darren Tucker019cefe2003-08-02 22:40:07 +1000476.It Fl S Ar start
477Specify start point (in hex) when generating candidate moduli for DH-GEX.
Damien Miller0a80ca12010-02-27 07:55:05 +1100478.It Fl s Ar ca_key
479Certify (sign) a public key using the specified CA key.
480Please see the
481.Sx CERTIFICATES
482section for details.
Damien Millerf3747bf2013-01-18 11:44:04 +1100483.Pp
484When generating a KRL,
485.Fl s
Damien Millerac5542b2013-01-20 22:33:02 +1100486specifies a path to a CA public key file used to revoke certificates directly
Damien Millerf3747bf2013-01-18 11:44:04 +1100487by key ID or serial number.
488See the
489.Sx KEY REVOCATION LISTS
490section for details.
Darren Tucker019cefe2003-08-02 22:40:07 +1000491.It Fl T Ar output_file
492Test DH group exchange candidate primes (generated using the
493.Fl G
494option) for safety.
Damien Miller265d3092005-03-02 12:05:06 +1100495.It Fl t Ar type
496Specifies the type of key to create.
497The possible values are
498.Dq rsa1
499for protocol version 1 and
Damien Miller6186bbc2010-09-24 22:00:54 +1000500.Dq dsa ,
501.Dq ecdsa
Damien Miller265d3092005-03-02 12:05:06 +1100502or
Damien Miller6186bbc2010-09-24 22:00:54 +1000503.Dq rsa
Damien Miller265d3092005-03-02 12:05:06 +1100504for protocol version 2.
Damien Millerac5542b2013-01-20 22:33:02 +1100505.It Fl u
506Update a KRL.
507When specified with
508.Fl k ,
Damien Miller881a7a22013-01-20 22:34:46 +1100509keys listed via the command line are added to the existing KRL rather than
Damien Millerac5542b2013-01-20 22:33:02 +1100510a new KRL being created.
Damien Miller0a80ca12010-02-27 07:55:05 +1100511.It Fl V Ar validity_interval
512Specify a validity interval when signing a certificate.
513A validity interval may consist of a single time, indicating that the
514certificate is valid beginning now and expiring at that time, or may consist
515of two times separated by a colon to indicate an explicit time interval.
516The start time may be specified as a date in YYYYMMDD format, a time
517in YYYYMMDDHHMMSS format or a relative time (to the current time) consisting
518of a minus sign followed by a relative time in the format described in the
519.Sx TIME FORMATS
520section of
Damien Miller77497e12010-03-22 05:50:51 +1100521.Xr sshd_config 5 .
Damien Miller0a80ca12010-02-27 07:55:05 +1100522The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMMSS time or
523a relative time starting with a plus character.
524.Pp
525For example:
526.Dq +52w1d
527(valid from now to 52 weeks and one day from now),
528.Dq -4w:+4w
529(valid from four weeks ago to four weeks from now),
530.Dq 20100101123000:20110101123000
531(valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011),
532.Dq -1d:20110101
533(valid from yesterday to midnight, January 1st, 2011).
Darren Tucker06930c72003-12-31 11:34:51 +1100534.It Fl v
535Verbose mode.
536Causes
537.Nm
538to print debugging messages about its progress.
539This is helpful for debugging moduli generation.
540Multiple
541.Fl v
542options increase the verbosity.
543The maximum is 3.
Damien Miller265d3092005-03-02 12:05:06 +1100544.It Fl W Ar generator
545Specify desired generator when testing candidate moduli for DH-GEX.
546.It Fl y
547This option will read a private
548OpenSSH format file and print an OpenSSH public key to stdout.
Damien Miller4e270b02010-04-16 15:56:21 +1000549.It Fl z Ar serial_number
550Specifies a serial number to be embedded in the certificate to distinguish
551this certificate from others from the same CA.
552The default serial number is zero.
Damien Millerf3747bf2013-01-18 11:44:04 +1100553.Pp
554When generating a KRL, the
555.Fl z
556flag is used to specify a KRL version number.
Damien Miller32aa1441999-10-29 09:15:49 +1000557.El
Darren Tucker019cefe2003-08-02 22:40:07 +1000558.Sh MODULI GENERATION
559.Nm
560may be used to generate groups for the Diffie-Hellman Group Exchange
561(DH-GEX) protocol.
562Generating these groups is a two-step process: first, candidate
563primes are generated using a fast, but memory intensive process.
564These candidate primes are then tested for suitability (a CPU-intensive
565process).
566.Pp
567Generation of primes is performed using the
568.Fl G
569option.
570The desired length of the primes may be specified by the
571.Fl b
572option.
573For example:
574.Pp
Damien Miller265d3092005-03-02 12:05:06 +1100575.Dl # ssh-keygen -G moduli-2048.candidates -b 2048
Darren Tucker019cefe2003-08-02 22:40:07 +1000576.Pp
577By default, the search for primes begins at a random point in the
578desired length range.
579This may be overridden using the
580.Fl S
581option, which specifies a different start point (in hex).
582.Pp
Damien Millerdfceafe2012-07-06 13:44:19 +1000583Once a set of candidates have been generated, they must be screened for
Darren Tucker019cefe2003-08-02 22:40:07 +1000584suitability.
585This may be performed using the
586.Fl T
587option.
588In this mode
589.Nm
590will read candidates from standard input (or a file specified using the
591.Fl f
592option).
593For example:
594.Pp
Damien Miller265d3092005-03-02 12:05:06 +1100595.Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
Darren Tucker019cefe2003-08-02 22:40:07 +1000596.Pp
597By default, each candidate will be subjected to 100 primality tests.
598This may be overridden using the
599.Fl a
600option.
601The DH generator value will be chosen automatically for the
602prime under consideration.
603If a specific generator is desired, it may be requested using the
604.Fl W
605option.
Damien Miller265d3092005-03-02 12:05:06 +1100606Valid generator values are 2, 3, and 5.
Darren Tucker019cefe2003-08-02 22:40:07 +1000607.Pp
608Screened DH groups may be installed in
609.Pa /etc/moduli .
610It is important that this file contains moduli of a range of bit lengths and
611that both ends of a connection share common moduli.
Damien Miller0a80ca12010-02-27 07:55:05 +1100612.Sh CERTIFICATES
613.Nm
614supports signing of keys to produce certificates that may be used for
615user or host authentication.
616Certificates consist of a public key, some identity information, zero or
Damien Miller1f181422010-04-18 08:08:03 +1000617more principal (user or host) names and a set of options that
Damien Miller0a80ca12010-02-27 07:55:05 +1100618are signed by a Certification Authority (CA) key.
619Clients or servers may then trust only the CA key and verify its signature
620on a certificate rather than trusting many user/host keys.
621Note that OpenSSH certificates are a different, and much simpler, format to
622the X.509 certificates used in
623.Xr ssl 8 .
624.Pp
625.Nm
626supports two types of certificates: user and host.
627User certificates authenticate users to servers, whereas host certificates
Damien Miller15f5b562010-03-03 10:25:21 +1100628authenticate server hosts to users.
629To generate a user certificate:
Damien Miller0a80ca12010-02-27 07:55:05 +1100630.Pp
631.Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
632.Pp
633The resultant certificate will be placed in
Damien Miller1b61a282010-03-22 05:55:06 +1100634.Pa /path/to/user_key-cert.pub .
Damien Miller0a80ca12010-02-27 07:55:05 +1100635A host certificate requires the
636.Fl h
637option:
638.Pp
639.Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
640.Pp
641The host certificate will be output to
Damien Miller1b61a282010-03-22 05:55:06 +1100642.Pa /path/to/host_key-cert.pub .
Damien Miller757f34e2010-08-05 13:05:31 +1000643.Pp
644It is possible to sign using a CA key stored in a PKCS#11 token by
645providing the token library using
646.Fl D
647and identifying the CA key by providing its public half as an argument
648to
649.Fl s :
650.Pp
651.Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub
652.Pp
653In all cases,
Damien Miller0a80ca12010-02-27 07:55:05 +1100654.Ar key_id
655is a "key identifier" that is logged by the server when the certificate
656is used for authentication.
657.Pp
658Certificates may be limited to be valid for a set of principal (user/host)
659names.
660By default, generated certificates are valid for all users or hosts.
661To generate a certificate for a specified set of principals:
662.Pp
663.Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
Damien Miller5a5d94b2010-03-22 05:57:49 +1100664.Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub"
Damien Miller0a80ca12010-02-27 07:55:05 +1100665.Pp
666Additional limitations on the validity and use of user certificates may
Damien Miller1f181422010-04-18 08:08:03 +1000667be specified through certificate options.
Damien Miller4e270b02010-04-16 15:56:21 +1000668A certificate option may disable features of the SSH session, may be
Damien Miller0a80ca12010-02-27 07:55:05 +1100669valid only when presented from particular source addresses or may
670force the use of a specific command.
Damien Miller4e270b02010-04-16 15:56:21 +1000671For a list of valid certificate options, see the documentation for the
Damien Miller0a80ca12010-02-27 07:55:05 +1100672.Fl O
673option above.
674.Pp
675Finally, certificates may be defined with a validity lifetime.
676The
677.Fl V
678option allows specification of certificate start and end times.
679A certificate that is presented at a time outside this range will not be
680considered valid.
Darren Tucker3ee50c52012-09-06 21:18:11 +1000681By default, certificates are valid from
682.Ux
683Epoch to the distant future.
Damien Miller0a80ca12010-02-27 07:55:05 +1100684.Pp
685For certificates to be used for user or host authentication, the CA
686public key must be trusted by
687.Xr sshd 8
688or
689.Xr ssh 1 .
690Please refer to those manual pages for details.
Damien Millerf3747bf2013-01-18 11:44:04 +1100691.Sh KEY REVOCATION LISTS
692.Nm
693is able to manage OpenSSH format Key Revocation Lists (KRLs).
694These binary files specify keys or certificates to be revoked using a
Damien Millerac5542b2013-01-20 22:33:02 +1100695compact format, taking as little a one bit per certificate if they are being
Damien Millerf3747bf2013-01-18 11:44:04 +1100696revoked by serial number.
697.Pp
698KRLs may be generated using the
699.Fl k
700flag.
Damien Miller881a7a22013-01-20 22:34:46 +1100701This option reads one or more files from the command line and generates a new
Damien Millerf3747bf2013-01-18 11:44:04 +1100702KRL.
703The files may either contain a KRL specification (see below) or public keys,
704listed one per line.
705Plain public keys are revoked by listing their hash or contents in the KRL and
706certificates revoked by serial number or key ID (if the serial is zero or
707not available).
708.Pp
709Revoking keys using a KRL specification offers explicit control over the
710types of record used to revoke keys and may be used to directly revoke
711certificates by serial number or key ID without having the complete original
712certificate on hand.
713A KRL specification consists of lines containing one of the following directives
714followed by a colon and some directive-specific information.
715.Bl -tag -width Ds
Damien Millera0a7ee82013-01-20 22:35:06 +1100716.It Cm serial : Ar serial_number Ns Op - Ns Ar serial_number
Damien Millerf3747bf2013-01-18 11:44:04 +1100717Revokes a certificate with the specified serial number.
Damien Millerac5542b2013-01-20 22:33:02 +1100718Serial numbers are 64-bit values, not including zero and may be expressed
Damien Millerf3747bf2013-01-18 11:44:04 +1100719in decimal, hex or octal.
720If two serial numbers are specified separated by a hyphen, then the range
721of serial numbers including and between each is revoked.
722The CA key must have been specified on the
723.Nm
Damien Miller881a7a22013-01-20 22:34:46 +1100724command line using the
Damien Millerf3747bf2013-01-18 11:44:04 +1100725.Fl s
726option.
727.It Cm id : Ar key_id
728Revokes a certificate with the specified key ID string.
729The CA key must have been specified on the
730.Nm
Damien Miller881a7a22013-01-20 22:34:46 +1100731command line using the
Damien Millerf3747bf2013-01-18 11:44:04 +1100732.Fl s
733option.
734.It Cm key : Ar public_key
735Revokes the specified key.
Damien Millerac5542b2013-01-20 22:33:02 +1100736If a certificate is listed, then it is revoked as a plain public key.
Damien Millerf3747bf2013-01-18 11:44:04 +1100737.It Cm sha1 : Ar public_key
738Revokes the specified key by its SHA1 hash.
739.El
740.Pp
741KRLs may be updated using the
742.Fl u
743flag in addition to
744.Fl k .
Damien Miller881a7a22013-01-20 22:34:46 +1100745When this option is specified, keys listed via the command line are merged into
Damien Millerf3747bf2013-01-18 11:44:04 +1100746the KRL, adding to those already there.
747.Pp
748It is also possible, given a KRL, to test whether it revokes a particular key
749(or keys).
750The
751.Fl Q
752flag will query an existing KRL, testing each key specified on the commandline.
Damien Miller881a7a22013-01-20 22:34:46 +1100753If any key listed on the command line has been revoked (or an error encountered)
Damien Millerf3747bf2013-01-18 11:44:04 +1100754then
755.Nm
756will exit with a non-zero exit status.
757A zero exit status will only be returned if no key was revoked.
Damien Miller32aa1441999-10-29 09:15:49 +1000758.Sh FILES
Damien Miller6186bbc2010-09-24 22:00:54 +1000759.Bl -tag -width Ds -compact
Damien Miller167ea5d2005-05-26 12:04:02 +1000760.It Pa ~/.ssh/identity
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000761Contains the protocol version 1 RSA authentication identity of the user.
Damien Miller450a7a12000-03-26 13:04:51 +1000762This file should not be readable by anyone but the user.
763It is possible to
Damien Miller32aa1441999-10-29 09:15:49 +1000764specify a passphrase when generating the key; that passphrase will be
Damien Miller6186bbc2010-09-24 22:00:54 +1000765used to encrypt the private part of this file using 3DES.
Damien Miller450a7a12000-03-26 13:04:51 +1000766This file is not automatically accessed by
Damien Miller32aa1441999-10-29 09:15:49 +1000767.Nm
768but it is offered as the default file for the private key.
Ben Lindstrombda98b02001-07-04 03:35:24 +0000769.Xr ssh 1
Damien Millere247cc42000-05-07 12:03:14 +1000770will read this file when a login attempt is made.
Damien Miller6186bbc2010-09-24 22:00:54 +1000771.Pp
Damien Miller167ea5d2005-05-26 12:04:02 +1000772.It Pa ~/.ssh/identity.pub
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000773Contains the protocol version 1 RSA public key for authentication.
Damien Miller450a7a12000-03-26 13:04:51 +1000774The contents of this file should be added to
Damien Miller167ea5d2005-05-26 12:04:02 +1000775.Pa ~/.ssh/authorized_keys
Damien Miller32aa1441999-10-29 09:15:49 +1000776on all machines
Ben Lindstrom594e2032001-09-12 18:35:30 +0000777where the user wishes to log in using RSA authentication.
Damien Miller450a7a12000-03-26 13:04:51 +1000778There is no need to keep the contents of this file secret.
Damien Miller6186bbc2010-09-24 22:00:54 +1000779.Pp
Damien Miller167ea5d2005-05-26 12:04:02 +1000780.It Pa ~/.ssh/id_dsa
Damien Miller6186bbc2010-09-24 22:00:54 +1000781.It Pa ~/.ssh/id_ecdsa
Damien Miller167ea5d2005-05-26 12:04:02 +1000782.It Pa ~/.ssh/id_rsa
Damien Miller6186bbc2010-09-24 22:00:54 +1000783Contains the protocol version 2 DSA, ECDSA or RSA authentication identity of the user.
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000784This 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
Darren Tucker199ee6f2009-10-24 11:50:17 +1100787used to encrypt the private part of this file using 128-bit AES.
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000788This file is not automatically accessed by
789.Nm
790but it is offered as the default file for the private key.
Ben Lindstrombda98b02001-07-04 03:35:24 +0000791.Xr ssh 1
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000792will read this file when a login attempt is made.
Damien Miller6186bbc2010-09-24 22:00:54 +1000793.Pp
794.It Pa ~/.ssh/id_dsa.pub
795.It Pa ~/.ssh/id_ecdsa.pub
Damien Miller167ea5d2005-05-26 12:04:02 +1000796.It Pa ~/.ssh/id_rsa.pub
Damien Miller6186bbc2010-09-24 22:00:54 +1000797Contains the protocol version 2 DSA, ECDSA or RSA public key for authentication.
Damien Millere247cc42000-05-07 12:03:14 +1000798The contents of this file should be added to
Damien Miller167ea5d2005-05-26 12:04:02 +1000799.Pa ~/.ssh/authorized_keys
Damien Millere247cc42000-05-07 12:03:14 +1000800on all machines
Ben Lindstrom594e2032001-09-12 18:35:30 +0000801where the user wishes to log in using public key authentication.
Damien Millere247cc42000-05-07 12:03:14 +1000802There is no need to keep the contents of this file secret.
Damien Miller6186bbc2010-09-24 22:00:54 +1000803.Pp
Darren Tucker019cefe2003-08-02 22:40:07 +1000804.It Pa /etc/moduli
805Contains Diffie-Hellman groups used for DH-GEX.
806The file format is described in
807.Xr moduli 5 .
Damien Miller37023962000-07-11 17:31:38 +1000808.El
Damien Miller32aa1441999-10-29 09:15:49 +1000809.Sh SEE ALSO
810.Xr ssh 1 ,
811.Xr ssh-add 1 ,
Damien Miller2e8b1c81999-11-15 23:33:56 +1100812.Xr ssh-agent 1 ,
Darren Tucker019cefe2003-08-02 22:40:07 +1000813.Xr moduli 5 ,
Ben Lindstrom77788dc2001-02-10 23:10:33 +0000814.Xr sshd 8
Ben Lindstrom5a707822001-04-22 17:15:46 +0000815.Rs
Damien Millerc0367fb2007-01-05 16:25:46 +1100816.%R RFC 4716
817.%T "The Secure Shell (SSH) Public Key File Format"
818.%D 2006
Ben Lindstrom5a707822001-04-22 17:15:46 +0000819.Re
Damien Millerf1ce5052003-06-11 22:04:39 +1000820.Sh AUTHORS
821OpenSSH is a derivative of the original and free
822ssh 1.2.12 release by Tatu Ylonen.
823Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
824Theo de Raadt and Dug Song
825removed many bugs, re-added newer features and
826created OpenSSH.
827Markus Friedl contributed the support for SSH
828protocol versions 1.5 and 2.0.