blob: ede37921c50e182dfa8b5e7fc384ea37ec3ac4fa [file] [log] [blame]
Damien Millerad210322011-05-05 14:15:54 +10001.\" $OpenBSD: ssh-keygen.1,v 1.106 2011/04/13 04:09:37 djm 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 Miller085c90f2011-05-05 14:15:33 +100038.Dd $Mdocdate: April 13 2011 $
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
107.Op Fl W Ar generator
Damien Miller0a80ca12010-02-27 07:55:05 +1100108.Nm ssh-keygen
109.Fl s Ar ca_key
110.Fl I Ar certificate_identity
111.Op Fl h
112.Op Fl n Ar principals
Damien Miller4e270b02010-04-16 15:56:21 +1000113.Op Fl O Ar option
Damien Miller0a80ca12010-02-27 07:55:05 +1100114.Op Fl V Ar validity_interval
Damien Miller4e270b02010-04-16 15:56:21 +1000115.Op Fl z Ar serial_number
Damien Miller0a80ca12010-02-27 07:55:05 +1100116.Ar
Damien Millerf2b70ca2010-03-05 07:39:35 +1100117.Nm ssh-keygen
Damien Millerf2b70ca2010-03-05 07:39:35 +1100118.Fl L
119.Op Fl f Ar input_keyfile
Damien Miller58f1baf2011-05-05 14:06:15 +1000120.Nm ssh-keygen
121.Fl A
Damien Miller15f5b562010-03-03 10:25:21 +1100122.Ek
Damien Miller22c77262000-04-13 12:26:34 +1000123.Sh DESCRIPTION
Damien Miller32aa1441999-10-29 09:15:49 +1000124.Nm
Ben Lindstrom5a707822001-04-22 17:15:46 +0000125generates, manages and converts authentication keys for
Damien Miller32aa1441999-10-29 09:15:49 +1000126.Xr ssh 1 .
Damien Millere247cc42000-05-07 12:03:14 +1000127.Nm
Damien Miller6186bbc2010-09-24 22:00:54 +1000128can create RSA keys for use by SSH protocol version 1 and DSA, ECDSA or RSA
Damien Millerfbf486b2003-05-23 18:44:23 +1000129keys for use by SSH protocol version 2.
130The type of key to be generated is specified with the
Damien Miller0bc1bd82000-11-13 22:57:25 +1100131.Fl t
Damien Millera41c8b12002-01-22 23:05:08 +1100132option.
Damien Millerf14be5c2005-11-05 15:15:49 +1100133If invoked without any arguments,
134.Nm
Damien Miller83d0d392005-11-05 15:16:27 +1100135will generate an RSA key for use in SSH protocol 2 connections.
Damien Millere247cc42000-05-07 12:03:14 +1000136.Pp
Darren Tucker019cefe2003-08-02 22:40:07 +1000137.Nm
138is also used to generate groups for use in Diffie-Hellman group
139exchange (DH-GEX).
140See the
141.Sx MODULI GENERATION
142section for details.
143.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000144Normally each user wishing to use SSH
Damien Millereb8b60e2010-08-31 22:41:14 +1000145with public key authentication runs this once to create the authentication
Damien Miller32aa1441999-10-29 09:15:49 +1000146key in
Damien Miller167ea5d2005-05-26 12:04:02 +1000147.Pa ~/.ssh/identity ,
Damien Millereb8b60e2010-08-31 22:41:14 +1000148.Pa ~/.ssh/id_ecdsa ,
Damien Miller167ea5d2005-05-26 12:04:02 +1000149.Pa ~/.ssh/id_dsa
Damien Millere247cc42000-05-07 12:03:14 +1000150or
Damien Miller167ea5d2005-05-26 12:04:02 +1000151.Pa ~/.ssh/id_rsa .
Damien Millere247cc42000-05-07 12:03:14 +1000152Additionally, the system administrator may use this to generate host keys,
153as seen in
154.Pa /etc/rc .
Damien Miller32aa1441999-10-29 09:15:49 +1000155.Pp
156Normally this program generates the key and asks for a file in which
Damien Miller450a7a12000-03-26 13:04:51 +1000157to store the private key.
158The public key is stored in a file with the same name but
Damien Miller32aa1441999-10-29 09:15:49 +1000159.Dq .pub
Damien Miller450a7a12000-03-26 13:04:51 +1000160appended.
161The program also asks for a passphrase.
162The passphrase may be empty to indicate no passphrase
Ben Lindstrombf555ba2001-01-18 02:04:35 +0000163(host keys must have an empty passphrase), or it may be a string of
Damien Miller450a7a12000-03-26 13:04:51 +1000164arbitrary length.
Ben Lindstrom4e366d52001-12-06 16:43:21 +0000165A passphrase is similar to a password, except it can be a phrase with a
166series of words, punctuation, numbers, whitespace, or any string of
167characters you want.
168Good passphrases are 10-30 characters long, are
Damien Miller32aa1441999-10-29 09:15:49 +1000169not simple sentences or otherwise easily guessable (English
Ben Lindstrom2a097a42001-06-09 01:13:40 +0000170prose has only 1-2 bits of entropy per character, and provides very bad
Ben Lindstrom4e366d52001-12-06 16:43:21 +0000171passphrases), and contain a mix of upper and lowercase letters,
172numbers, and non-alphanumeric characters.
Damien Miller450a7a12000-03-26 13:04:51 +1000173The passphrase can be changed later by using the
Damien Miller32aa1441999-10-29 09:15:49 +1000174.Fl p
175option.
176.Pp
Damien Miller450a7a12000-03-26 13:04:51 +1000177There is no way to recover a lost passphrase.
Damien Miller085c90f2011-05-05 14:15:33 +1000178If the passphrase is lost or forgotten, a new key must be generated
179and the corresponding public key copied to other machines.
Damien Miller32aa1441999-10-29 09:15:49 +1000180.Pp
Ben Lindstrom5a707822001-04-22 17:15:46 +0000181For RSA1 keys,
182there is also a comment field in the key file that is only for
Damien Miller450a7a12000-03-26 13:04:51 +1000183convenience to the user to help identify the key.
184The comment can tell what the key is for, or whatever is useful.
185The comment is initialized to
Damien Miller32aa1441999-10-29 09:15:49 +1000186.Dq user@host
187when the key is created, but can be changed using the
188.Fl c
189option.
190.Pp
Damien Millere247cc42000-05-07 12:03:14 +1000191After a key is generated, instructions below detail where the keys
192should be placed to be activated.
193.Pp
Damien Miller32aa1441999-10-29 09:15:49 +1000194The options are as follows:
195.Bl -tag -width Ds
Damien Miller58f1baf2011-05-05 14:06:15 +1000196.It Fl A
197For each of the key types (rsa1, rsa, dsa and ecdsa) for which host keys
198do not exist, generate the host keys with the default key file path,
199an empty passphrase, default bits for the key type, and default comment.
Damien Miller3ca1eb32011-05-05 14:13:50 +1000200This is used by
Damien Miller58f1baf2011-05-05 14:06:15 +1000201.Pa /etc/rc
202to generate new host keys.
Darren Tucker019cefe2003-08-02 22:40:07 +1000203.It Fl a Ar trials
204Specifies the number of primality tests to perform when screening DH-GEX
205candidates using the
206.Fl T
207command.
Damien Miller265d3092005-03-02 12:05:06 +1100208.It Fl B
209Show the bubblebabble digest of specified private or public key file.
Damien Miller32aa1441999-10-29 09:15:49 +1000210.It Fl b Ar bits
Damien Miller450a7a12000-03-26 13:04:51 +1000211Specifies the number of bits in the key to create.
Darren Tucker9f647332005-11-28 16:41:46 +1100212For RSA keys, the minimum size is 768 bits and the default is 2048 bits.
Damien Millerac7ef6a2005-06-16 13:19:06 +1000213Generally, 2048 bits is considered sufficient.
Darren Tucker9f647332005-11-28 16:41:46 +1100214DSA keys must be exactly 1024 bits as specified by FIPS 186-2.
Damien Millerad210322011-05-05 14:15:54 +1000215For ECDSA keys, the
216.Fl b
217flag determines they key length by selecting from one of three elliptic
218curve sizes: 256, 384 or 521 bits.
219Attempting to use bit lengths other than these three values for ECDSA keys
220will fail.
Damien Miller265d3092005-03-02 12:05:06 +1100221.It Fl C Ar comment
222Provides a new comment.
Damien Miller32aa1441999-10-29 09:15:49 +1000223.It Fl c
224Requests changing the comment in the private and public key files.
Damien Millereb5fec62001-11-12 10:52:44 +1100225This operation is only supported for RSA1 keys.
Damien Miller32aa1441999-10-29 09:15:49 +1000226The program will prompt for the file containing the private keys, for
Ben Lindstromaafff9c2001-05-06 03:01:02 +0000227the passphrase if the key has one, and for the new comment.
Damien Miller7ea845e2010-02-12 09:21:02 +1100228.It Fl D Ar pkcs11
Damien Millera7618442010-02-12 09:26:02 +1100229Download the RSA public keys provided by the PKCS#11 shared library
230.Ar pkcs11 .
Damien Miller757f34e2010-08-05 13:05:31 +1000231When used in combination with
232.Fl s ,
233this option indicates that a CA key resides in a PKCS#11 token (see the
234.Sx CERTIFICATES
235section for details).
Ben Lindstrom5a707822001-04-22 17:15:46 +0000236.It Fl e
Ben Lindstrom46c264f2001-04-24 16:56:58 +0000237This option will read a private or public OpenSSH key file and
Damien Miller44b25042010-07-02 13:35:01 +1000238print to stdout the key in one of the formats specified by the
239.Fl m
240option.
241The default export format is
242.Dq RFC4716 .
Damien Millerea727282010-07-02 13:35:34 +1000243This option allows exporting OpenSSH keys for use by other programs, including
Damien Miller44b25042010-07-02 13:35:01 +1000244several commercial SSH implementations.
Damien Miller265d3092005-03-02 12:05:06 +1100245.It Fl F Ar hostname
246Search for the specified
247.Ar hostname
248in a
249.Pa known_hosts
250file, listing any occurrences found.
251This option is useful to find hashed host names or addresses and may also be
252used in conjunction with the
253.Fl H
254option to print found keys in a hashed format.
255.It Fl f Ar filename
256Specifies the filename of the key file.
257.It Fl G Ar output_file
258Generate candidate primes for DH-GEX.
259These primes must be screened for
260safety (using the
261.Fl T
262option) before use.
Damien Miller37876e92003-05-15 10:19:46 +1000263.It Fl g
Darren Tucker0b42e6d2004-08-13 21:22:40 +1000264Use generic DNS format when printing fingerprint resource records using the
Darren Tucker6e370372004-08-13 21:23:25 +1000265.Fl r
Darren Tucker0b42e6d2004-08-13 21:22:40 +1000266command.
Damien Miller265d3092005-03-02 12:05:06 +1100267.It Fl H
268Hash a
269.Pa known_hosts
Darren Tuckerda1adbc2005-03-14 23:15:58 +1100270file.
271This replaces all hostnames and addresses with hashed representations
272within the specified file; the original content is moved to a file with
273a .old suffix.
Damien Miller265d3092005-03-02 12:05:06 +1100274These hashes may be used normally by
275.Nm ssh
276and
277.Nm sshd ,
278but they do not reveal identifying information should the file's contents
279be disclosed.
280This option will not modify existing hashed hostnames and is therefore safe
281to use on files that mix hashed and non-hashed names.
Damien Miller0a80ca12010-02-27 07:55:05 +1100282.It Fl h
283When signing a key, create a host certificate instead of a user
284certificate.
285Please see the
286.Sx CERTIFICATES
287section for details.
Damien Miller15f5b562010-03-03 10:25:21 +1100288.It Fl I Ar certificate_identity
Damien Miller0a80ca12010-02-27 07:55:05 +1100289Specify the key identity when signing a public key.
290Please see the
291.Sx CERTIFICATES
292section for details.
Ben Lindstrom5a707822001-04-22 17:15:46 +0000293.It Fl i
294This option will read an unencrypted private (or public) key file
Damien Miller44b25042010-07-02 13:35:01 +1000295in the format specified by the
296.Fl m
297option and print an OpenSSH compatible private
Ben Lindstrom5a707822001-04-22 17:15:46 +0000298(or public) key to stdout.
Damien Miller44b25042010-07-02 13:35:01 +1000299This option allows importing keys from other software, including several
300commercial SSH implementations.
301The default import format is
302.Dq RFC4716 .
Damien Millerf2b70ca2010-03-05 07:39:35 +1100303.It Fl L
304Prints the contents of a certificate.
Damien Miller10f6f6b1999-11-17 17:29:08 +1100305.It Fl l
Darren Tucker35c45532008-06-13 04:43:15 +1000306Show fingerprint of specified public key file.
Damien Millereb5fec62001-11-12 10:52:44 +1100307Private RSA1 keys are also supported.
308For RSA and DSA keys
309.Nm
Darren Tuckerf09e8252008-06-13 05:18:03 +1000310tries to find the matching public key file and prints its fingerprint.
311If combined with
312.Fl v ,
313an ASCII art representation of the key is supplied with the fingerprint.
Damien Millerea727282010-07-02 13:35:34 +1000314.It Fl M Ar memory
315Specify the amount of memory to use (in megabytes) when generating
316candidate moduli for DH-GEX.
Damien Miller44b25042010-07-02 13:35:01 +1000317.It Fl m Ar key_format
318Specify a key format for the
319.Fl i
320(import) or
321.Fl e
Damien Millerea727282010-07-02 13:35:34 +1000322(export) conversion options.
Damien Miller44b25042010-07-02 13:35:01 +1000323The supported key formats are:
324.Dq RFC4716
Damien Millerea727282010-07-02 13:35:34 +1000325(RFC 4716/SSH2 public or private key),
Damien Miller44b25042010-07-02 13:35:01 +1000326.Dq PKCS8
327(PEM PKCS8 public key)
328or
329.Dq PEM
330(PEM public key).
331The default conversion format is
332.Dq RFC4716 .
Damien Miller265d3092005-03-02 12:05:06 +1100333.It Fl N Ar new_passphrase
334Provides the new passphrase.
Damien Miller0a80ca12010-02-27 07:55:05 +1100335.It Fl n Ar principals
336Specify one or more principals (user or host names) to be included in
337a certificate when signing a key.
338Multiple principals may be specified, separated by commas.
339Please see the
340.Sx CERTIFICATES
341section for details.
Damien Miller4e270b02010-04-16 15:56:21 +1000342.It Fl O Ar option
343Specify a certificate option when signing a key.
Damien Miller0a80ca12010-02-27 07:55:05 +1100344This option may be specified multiple times.
345Please see the
346.Sx CERTIFICATES
347section for details.
Damien Miller4e270b02010-04-16 15:56:21 +1000348The options that are valid for user certificates are:
Damien Miller0a80ca12010-02-27 07:55:05 +1100349.Bl -tag -width Ds
Damien Millerc59e2442010-03-22 05:50:31 +1100350.It Ic clear
351Clear all enabled permissions.
352This is useful for clearing the default set of permissions so permissions may
353be added individually.
354.It Ic force-command Ns = Ns Ar command
355Forces the execution of
356.Ar command
357instead of any shell or command specified by the user when
358the certificate is used for authentication.
Damien Miller0a80ca12010-02-27 07:55:05 +1100359.It Ic no-agent-forwarding
360Disable
361.Xr ssh-agent 1
Damien Miller15f5b562010-03-03 10:25:21 +1100362forwarding (permitted by default).
Damien Miller0a80ca12010-02-27 07:55:05 +1100363.It Ic no-port-forwarding
Damien Miller15f5b562010-03-03 10:25:21 +1100364Disable port forwarding (permitted by default).
Damien Miller0a80ca12010-02-27 07:55:05 +1100365.It Ic no-pty
Damien Miller15f5b562010-03-03 10:25:21 +1100366Disable PTY allocation (permitted by default).
Damien Miller0a80ca12010-02-27 07:55:05 +1100367.It Ic no-user-rc
368Disable execution of
369.Pa ~/.ssh/rc
370by
Damien Miller15f5b562010-03-03 10:25:21 +1100371.Xr sshd 8
372(permitted by default).
Damien Millerc59e2442010-03-22 05:50:31 +1100373.It Ic no-x11-forwarding
374Disable X11 forwarding (permitted by default).
Damien Miller081c9762010-03-08 11:30:00 +1100375.It Ic permit-agent-forwarding
376Allows
377.Xr ssh-agent 1
378forwarding.
Damien Miller0a80ca12010-02-27 07:55:05 +1100379.It Ic permit-port-forwarding
380Allows port forwarding.
381.It Ic permit-pty
382Allows PTY allocation.
383.It Ic permit-user-rc
384Allows execution of
385.Pa ~/.ssh/rc
386by
387.Xr sshd 8 .
Damien Millerc59e2442010-03-22 05:50:31 +1100388.It Ic permit-x11-forwarding
389Allows X11 forwarding.
390.It Ic source-address Ns = Ns Ar address_list
Damien Miller77497e12010-03-22 05:50:51 +1100391Restrict the source addresses from which the certificate is considered valid.
Damien Miller0a80ca12010-02-27 07:55:05 +1100392The
393.Ar address_list
394is a comma-separated list of one or more address/netmask pairs in CIDR
395format.
396.El
397.Pp
Damien Miller4e270b02010-04-16 15:56:21 +1000398At present, no options are valid for host keys.
Damien Miller265d3092005-03-02 12:05:06 +1100399.It Fl P Ar passphrase
400Provides the (old) passphrase.
Damien Miller32aa1441999-10-29 09:15:49 +1000401.It Fl p
402Requests changing the passphrase of a private key file instead of
Damien Miller450a7a12000-03-26 13:04:51 +1000403creating a new private key.
404The program will prompt for the file
Damien Miller32aa1441999-10-29 09:15:49 +1000405containing the private key, for the old passphrase, and twice for the
406new passphrase.
407.It Fl q
408Silence
409.Nm ssh-keygen .
Damien Miller4b42d7f2005-03-01 21:48:35 +1100410.It Fl R Ar hostname
411Removes all keys belonging to
412.Ar hostname
Damien Miller4c9c6fd2005-03-02 12:03:43 +1100413from a
Damien Miller4b42d7f2005-03-01 21:48:35 +1100414.Pa known_hosts
415file.
Damien Miller4c9c6fd2005-03-02 12:03:43 +1100416This option is useful to delete hashed hosts (see the
Damien Miller4b42d7f2005-03-01 21:48:35 +1100417.Fl H
418option above).
Damien Miller265d3092005-03-02 12:05:06 +1100419.It Fl r Ar hostname
420Print the SSHFP fingerprint resource record named
421.Ar hostname
422for the specified public key file.
Darren Tucker019cefe2003-08-02 22:40:07 +1000423.It Fl S Ar start
424Specify start point (in hex) when generating candidate moduli for DH-GEX.
Damien Miller0a80ca12010-02-27 07:55:05 +1100425.It Fl s Ar ca_key
426Certify (sign) a public key using the specified CA key.
427Please see the
428.Sx CERTIFICATES
429section for details.
Darren Tucker019cefe2003-08-02 22:40:07 +1000430.It Fl T Ar output_file
431Test DH group exchange candidate primes (generated using the
432.Fl G
433option) for safety.
Damien Miller265d3092005-03-02 12:05:06 +1100434.It Fl t Ar type
435Specifies the type of key to create.
436The possible values are
437.Dq rsa1
438for protocol version 1 and
Damien Miller6186bbc2010-09-24 22:00:54 +1000439.Dq dsa ,
440.Dq ecdsa
Damien Miller265d3092005-03-02 12:05:06 +1100441or
Damien Miller6186bbc2010-09-24 22:00:54 +1000442.Dq rsa
Damien Miller265d3092005-03-02 12:05:06 +1100443for protocol version 2.
Damien Miller0a80ca12010-02-27 07:55:05 +1100444.It Fl V Ar validity_interval
445Specify a validity interval when signing a certificate.
446A validity interval may consist of a single time, indicating that the
447certificate is valid beginning now and expiring at that time, or may consist
448of two times separated by a colon to indicate an explicit time interval.
449The start time may be specified as a date in YYYYMMDD format, a time
450in YYYYMMDDHHMMSS format or a relative time (to the current time) consisting
451of a minus sign followed by a relative time in the format described in the
452.Sx TIME FORMATS
453section of
Damien Miller77497e12010-03-22 05:50:51 +1100454.Xr sshd_config 5 .
Damien Miller0a80ca12010-02-27 07:55:05 +1100455The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMMSS time or
456a relative time starting with a plus character.
457.Pp
458For example:
459.Dq +52w1d
460(valid from now to 52 weeks and one day from now),
461.Dq -4w:+4w
462(valid from four weeks ago to four weeks from now),
463.Dq 20100101123000:20110101123000
464(valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011),
465.Dq -1d:20110101
466(valid from yesterday to midnight, January 1st, 2011).
Darren Tucker06930c72003-12-31 11:34:51 +1100467.It Fl v
468Verbose mode.
469Causes
470.Nm
471to print debugging messages about its progress.
472This is helpful for debugging moduli generation.
473Multiple
474.Fl v
475options increase the verbosity.
476The maximum is 3.
Damien Miller265d3092005-03-02 12:05:06 +1100477.It Fl W Ar generator
478Specify desired generator when testing candidate moduli for DH-GEX.
479.It Fl y
480This option will read a private
481OpenSSH format file and print an OpenSSH public key to stdout.
Damien Miller4e270b02010-04-16 15:56:21 +1000482.It Fl z Ar serial_number
483Specifies a serial number to be embedded in the certificate to distinguish
484this certificate from others from the same CA.
485The default serial number is zero.
Damien Miller32aa1441999-10-29 09:15:49 +1000486.El
Darren Tucker019cefe2003-08-02 22:40:07 +1000487.Sh MODULI GENERATION
488.Nm
489may be used to generate groups for the Diffie-Hellman Group Exchange
490(DH-GEX) protocol.
491Generating these groups is a two-step process: first, candidate
492primes are generated using a fast, but memory intensive process.
493These candidate primes are then tested for suitability (a CPU-intensive
494process).
495.Pp
496Generation of primes is performed using the
497.Fl G
498option.
499The desired length of the primes may be specified by the
500.Fl b
501option.
502For example:
503.Pp
Damien Miller265d3092005-03-02 12:05:06 +1100504.Dl # ssh-keygen -G moduli-2048.candidates -b 2048
Darren Tucker019cefe2003-08-02 22:40:07 +1000505.Pp
506By default, the search for primes begins at a random point in the
507desired length range.
508This may be overridden using the
509.Fl S
510option, which specifies a different start point (in hex).
511.Pp
512Once a set of candidates have been generated, they must be tested for
513suitability.
514This may be performed using the
515.Fl T
516option.
517In this mode
518.Nm
519will read candidates from standard input (or a file specified using the
520.Fl f
521option).
522For example:
523.Pp
Damien Miller265d3092005-03-02 12:05:06 +1100524.Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
Darren Tucker019cefe2003-08-02 22:40:07 +1000525.Pp
526By default, each candidate will be subjected to 100 primality tests.
527This may be overridden using the
528.Fl a
529option.
530The DH generator value will be chosen automatically for the
531prime under consideration.
532If a specific generator is desired, it may be requested using the
533.Fl W
534option.
Damien Miller265d3092005-03-02 12:05:06 +1100535Valid generator values are 2, 3, and 5.
Darren Tucker019cefe2003-08-02 22:40:07 +1000536.Pp
537Screened DH groups may be installed in
538.Pa /etc/moduli .
539It is important that this file contains moduli of a range of bit lengths and
540that both ends of a connection share common moduli.
Damien Miller0a80ca12010-02-27 07:55:05 +1100541.Sh CERTIFICATES
542.Nm
543supports signing of keys to produce certificates that may be used for
544user or host authentication.
545Certificates consist of a public key, some identity information, zero or
Damien Miller1f181422010-04-18 08:08:03 +1000546more principal (user or host) names and a set of options that
Damien Miller0a80ca12010-02-27 07:55:05 +1100547are signed by a Certification Authority (CA) key.
548Clients or servers may then trust only the CA key and verify its signature
549on a certificate rather than trusting many user/host keys.
550Note that OpenSSH certificates are a different, and much simpler, format to
551the X.509 certificates used in
552.Xr ssl 8 .
553.Pp
554.Nm
555supports two types of certificates: user and host.
556User certificates authenticate users to servers, whereas host certificates
Damien Miller15f5b562010-03-03 10:25:21 +1100557authenticate server hosts to users.
558To generate a user certificate:
Damien Miller0a80ca12010-02-27 07:55:05 +1100559.Pp
560.Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub
561.Pp
562The resultant certificate will be placed in
Damien Miller1b61a282010-03-22 05:55:06 +1100563.Pa /path/to/user_key-cert.pub .
Damien Miller0a80ca12010-02-27 07:55:05 +1100564A host certificate requires the
565.Fl h
566option:
567.Pp
568.Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub
569.Pp
570The host certificate will be output to
Damien Miller1b61a282010-03-22 05:55:06 +1100571.Pa /path/to/host_key-cert.pub .
Damien Miller757f34e2010-08-05 13:05:31 +1000572.Pp
573It is possible to sign using a CA key stored in a PKCS#11 token by
574providing the token library using
575.Fl D
576and identifying the CA key by providing its public half as an argument
577to
578.Fl s :
579.Pp
580.Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub
581.Pp
582In all cases,
Damien Miller0a80ca12010-02-27 07:55:05 +1100583.Ar key_id
584is a "key identifier" that is logged by the server when the certificate
585is used for authentication.
586.Pp
587Certificates may be limited to be valid for a set of principal (user/host)
588names.
589By default, generated certificates are valid for all users or hosts.
590To generate a certificate for a specified set of principals:
591.Pp
592.Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
Damien Miller5a5d94b2010-03-22 05:57:49 +1100593.Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub"
Damien Miller0a80ca12010-02-27 07:55:05 +1100594.Pp
595Additional limitations on the validity and use of user certificates may
Damien Miller1f181422010-04-18 08:08:03 +1000596be specified through certificate options.
Damien Miller4e270b02010-04-16 15:56:21 +1000597A certificate option may disable features of the SSH session, may be
Damien Miller0a80ca12010-02-27 07:55:05 +1100598valid only when presented from particular source addresses or may
599force the use of a specific command.
Damien Miller4e270b02010-04-16 15:56:21 +1000600For a list of valid certificate options, see the documentation for the
Damien Miller0a80ca12010-02-27 07:55:05 +1100601.Fl O
602option above.
603.Pp
604Finally, certificates may be defined with a validity lifetime.
605The
606.Fl V
607option allows specification of certificate start and end times.
608A certificate that is presented at a time outside this range will not be
609considered valid.
610By default, certificates have a maximum validity interval.
611.Pp
612For certificates to be used for user or host authentication, the CA
613public key must be trusted by
614.Xr sshd 8
615or
616.Xr ssh 1 .
617Please refer to those manual pages for details.
Damien Miller32aa1441999-10-29 09:15:49 +1000618.Sh FILES
Damien Miller6186bbc2010-09-24 22:00:54 +1000619.Bl -tag -width Ds -compact
Damien Miller167ea5d2005-05-26 12:04:02 +1000620.It Pa ~/.ssh/identity
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000621Contains the protocol version 1 RSA authentication identity of the user.
Damien Miller450a7a12000-03-26 13:04:51 +1000622This file should not be readable by anyone but the user.
623It is possible to
Damien Miller32aa1441999-10-29 09:15:49 +1000624specify a passphrase when generating the key; that passphrase will be
Damien Miller6186bbc2010-09-24 22:00:54 +1000625used to encrypt the private part of this file using 3DES.
Damien Miller450a7a12000-03-26 13:04:51 +1000626This file is not automatically accessed by
Damien Miller32aa1441999-10-29 09:15:49 +1000627.Nm
628but it is offered as the default file for the private key.
Ben Lindstrombda98b02001-07-04 03:35:24 +0000629.Xr ssh 1
Damien Millere247cc42000-05-07 12:03:14 +1000630will read this file when a login attempt is made.
Damien Miller6186bbc2010-09-24 22:00:54 +1000631.Pp
Damien Miller167ea5d2005-05-26 12:04:02 +1000632.It Pa ~/.ssh/identity.pub
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000633Contains the protocol version 1 RSA public key for authentication.
Damien Miller450a7a12000-03-26 13:04:51 +1000634The contents of this file should be added to
Damien Miller167ea5d2005-05-26 12:04:02 +1000635.Pa ~/.ssh/authorized_keys
Damien Miller32aa1441999-10-29 09:15:49 +1000636on all machines
Ben Lindstrom594e2032001-09-12 18:35:30 +0000637where the user wishes to log in using RSA authentication.
Damien Miller450a7a12000-03-26 13:04:51 +1000638There is no need to keep the contents of this file secret.
Damien Miller6186bbc2010-09-24 22:00:54 +1000639.Pp
Damien Miller167ea5d2005-05-26 12:04:02 +1000640.It Pa ~/.ssh/id_dsa
Damien Miller6186bbc2010-09-24 22:00:54 +1000641.It Pa ~/.ssh/id_ecdsa
Damien Miller167ea5d2005-05-26 12:04:02 +1000642.It Pa ~/.ssh/id_rsa
Damien Miller6186bbc2010-09-24 22:00:54 +1000643Contains the protocol version 2 DSA, ECDSA or RSA authentication identity of the user.
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000644This file should not be readable by anyone but the user.
645It is possible to
646specify a passphrase when generating the key; that passphrase will be
Darren Tucker199ee6f2009-10-24 11:50:17 +1100647used to encrypt the private part of this file using 128-bit AES.
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000648This file is not automatically accessed by
649.Nm
650but it is offered as the default file for the private key.
Ben Lindstrombda98b02001-07-04 03:35:24 +0000651.Xr ssh 1
Ben Lindstrom18a82ac2001-04-11 15:59:35 +0000652will read this file when a login attempt is made.
Damien Miller6186bbc2010-09-24 22:00:54 +1000653.Pp
654.It Pa ~/.ssh/id_dsa.pub
655.It Pa ~/.ssh/id_ecdsa.pub
Damien Miller167ea5d2005-05-26 12:04:02 +1000656.It Pa ~/.ssh/id_rsa.pub
Damien Miller6186bbc2010-09-24 22:00:54 +1000657Contains the protocol version 2 DSA, ECDSA or RSA public key for authentication.
Damien Millere247cc42000-05-07 12:03:14 +1000658The contents of this file should be added to
Damien Miller167ea5d2005-05-26 12:04:02 +1000659.Pa ~/.ssh/authorized_keys
Damien Millere247cc42000-05-07 12:03:14 +1000660on all machines
Ben Lindstrom594e2032001-09-12 18:35:30 +0000661where the user wishes to log in using public key authentication.
Damien Millere247cc42000-05-07 12:03:14 +1000662There is no need to keep the contents of this file secret.
Damien Miller6186bbc2010-09-24 22:00:54 +1000663.Pp
Darren Tucker019cefe2003-08-02 22:40:07 +1000664.It Pa /etc/moduli
665Contains Diffie-Hellman groups used for DH-GEX.
666The file format is described in
667.Xr moduli 5 .
Damien Miller37023962000-07-11 17:31:38 +1000668.El
Damien Miller32aa1441999-10-29 09:15:49 +1000669.Sh SEE ALSO
670.Xr ssh 1 ,
671.Xr ssh-add 1 ,
Damien Miller2e8b1c81999-11-15 23:33:56 +1100672.Xr ssh-agent 1 ,
Darren Tucker019cefe2003-08-02 22:40:07 +1000673.Xr moduli 5 ,
Ben Lindstrom77788dc2001-02-10 23:10:33 +0000674.Xr sshd 8
Ben Lindstrom5a707822001-04-22 17:15:46 +0000675.Rs
Damien Millerc0367fb2007-01-05 16:25:46 +1100676.%R RFC 4716
677.%T "The Secure Shell (SSH) Public Key File Format"
678.%D 2006
Ben Lindstrom5a707822001-04-22 17:15:46 +0000679.Re
Damien Millerf1ce5052003-06-11 22:04:39 +1000680.Sh AUTHORS
681OpenSSH is a derivative of the original and free
682ssh 1.2.12 release by Tatu Ylonen.
683Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
684Theo de Raadt and Dug Song
685removed many bugs, re-added newer features and
686created OpenSSH.
687Markus Friedl contributed the support for SSH
688protocol versions 1.5 and 2.0.