1.\" $OpenBSD: ssh-keygen.1,v 1.60 2003/07/28 09:49:56 djm Exp $ 2.\" 3.\" -*- nroff -*- 4.\" 5.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 6.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 7.\" All rights reserved 8.\" 9.\" As far as I am concerned, the code I have written for this software 10.\" can be used freely for any purpose. Any derived versions of this 11.\" software must be clearly marked as such, and if the derived work is 12.\" incompatible with the protocol description in the RFC file, it must be 13.\" called by a name other than "ssh" or "Secure Shell". 14.\" 15.\" 16.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. 17.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. 18.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. 19.\" 20.\" Redistribution and use in source and binary forms, with or without 21.\" modification, are permitted provided that the following conditions 22.\" are met: 23.\" 1. Redistributions of source code must retain the above copyright 24.\" notice, this list of conditions and the following disclaimer. 25.\" 2. Redistributions in binary form must reproduce the above copyright 26.\" notice, this list of conditions and the following disclaimer in the 27.\" documentation and/or other materials provided with the distribution. 28.\" 29.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 30.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 31.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 32.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 33.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 34.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 35.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 36.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 37.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 38.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 39.\" 40.Dd September 25, 1999 41.Dt SSH-KEYGEN 1 42.Os 43.Sh NAME 44.Nm ssh-keygen 45.Nd authentication key generation, management and conversion 46.Sh SYNOPSIS 47.Nm ssh-keygen 48.Bk -words 49.Op Fl q 50.Op Fl b Ar bits 51.Fl t Ar type 52.Op Fl N Ar new_passphrase 53.Op Fl C Ar comment 54.Op Fl f Ar output_keyfile 55.Ek 56.Nm ssh-keygen 57.Fl p 58.Op Fl P Ar old_passphrase 59.Op Fl N Ar new_passphrase 60.Op Fl f Ar keyfile 61.Nm ssh-keygen 62.Fl i 63.Op Fl f Ar input_keyfile 64.Nm ssh-keygen 65.Fl e 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 reader 83.Nm ssh-keygen 84.Fl U Ar reader 85.Op Fl f Ar input_keyfile 86.Nm ssh-keygen 87.Fl r Ar hostname 88.Op Fl f Ar input_keyfile 89.Op Fl g 90.Nm ssh-keygen 91.Fl G Ar output_file 92.Op Fl b Ar bits 93.Op Fl M Ar memory 94.Op Fl S Ar start_point 95.Nm ssh-keygen 96.Fl T Ar output_file 97.Fl f Ar input_file 98.Op Fl a Ar num_trials 99.Op Fl W Ar generator 100.Sh DESCRIPTION 101.Nm 102generates, manages and converts authentication keys for 103.Xr ssh 1 . 104.Nm 105can create RSA keys for use by SSH protocol version 1 and RSA or DSA 106keys for use by SSH protocol version 2. 107The type of key to be generated is specified with the 108.Fl t 109option. 110.Pp 111.Nm 112is also used to generate groups for use in Diffie-Hellman group 113exchange (DH-GEX). 114See the 115.Sx MODULI GENERATION 116section for details. 117.Pp 118Normally each user wishing to use SSH 119with RSA or DSA authentication runs this once to create the authentication 120key in 121.Pa $HOME/.ssh/identity , 122.Pa $HOME/.ssh/id_dsa 123or 124.Pa $HOME/.ssh/id_rsa . 125Additionally, the system administrator may use this to generate host keys, 126as seen in 127.Pa /etc/rc . 128.Pp 129Normally this program generates the key and asks for a file in which 130to store the private key. 131The public key is stored in a file with the same name but 132.Dq .pub 133appended. 134The program also asks for a passphrase. 135The passphrase may be empty to indicate no passphrase 136(host keys must have an empty passphrase), or it may be a string of 137arbitrary length. 138A passphrase is similar to a password, except it can be a phrase with a 139series of words, punctuation, numbers, whitespace, or any string of 140characters you want. 141Good passphrases are 10-30 characters long, are 142not simple sentences or otherwise easily guessable (English 143prose has only 1-2 bits of entropy per character, and provides very bad 144passphrases), and contain a mix of upper and lowercase letters, 145numbers, and non-alphanumeric characters. 146The passphrase can be changed later by using the 147.Fl p 148option. 149.Pp 150There is no way to recover a lost passphrase. 151If the passphrase is 152lost or forgotten, a new key must be generated and copied to the 153corresponding public key to other machines. 154.Pp 155For RSA1 keys, 156there is also a comment field in the key file that is only for 157convenience to the user to help identify the key. 158The comment can tell what the key is for, or whatever is useful. 159The comment is initialized to 160.Dq user@host 161when the key is created, but can be changed using the 162.Fl c 163option. 164.Pp 165After a key is generated, instructions below detail where the keys 166should be placed to be activated. 167.Pp 168The options are as follows: 169.Bl -tag -width Ds 170.It Fl a Ar trials 171Specifies the number of primality tests to perform when screening DH-GEX 172candidates using the 173.Fl T 174command. 175.It Fl b Ar bits 176Specifies the number of bits in the key to create. 177Minimum is 512 bits. 178Generally, 1024 bits is considered sufficient. 179The default is 1024 bits. 180.It Fl c 181Requests changing the comment in the private and public key files. 182This operation is only supported for RSA1 keys. 183The program will prompt for the file containing the private keys, for 184the passphrase if the key has one, and for the new comment. 185.It Fl e 186This option will read a private or public OpenSSH key file and 187print the key in a 188.Sq SECSH Public Key File Format 189to stdout. 190This option allows exporting keys for use by several commercial 191SSH implementations. 192.It Fl g 193Use generic DNS resource record format. 194.It Fl f Ar filename 195Specifies the filename of the key file. 196.It Fl i 197This option will read an unencrypted private (or public) key file 198in SSH2-compatible format and print an OpenSSH compatible private 199(or public) key to stdout. 200.Nm 201also reads the 202.Sq SECSH Public Key File Format . 203This option allows importing keys from several commercial 204SSH implementations. 205.It Fl l 206Show fingerprint of specified public key file. 207Private RSA1 keys are also supported. 208For RSA and DSA keys 209.Nm 210tries to find the matching public key file and prints its fingerprint. 211.It Fl p 212Requests changing the passphrase of a private key file instead of 213creating a new private key. 214The program will prompt for the file 215containing the private key, for the old passphrase, and twice for the 216new passphrase. 217.It Fl q 218Silence 219.Nm ssh-keygen . 220Used by 221.Pa /etc/rc 222when creating a new key. 223.It Fl y 224This option will read a private 225OpenSSH format file and print an OpenSSH public key to stdout. 226.It Fl t Ar type 227Specifies the type of the key to create. 228The possible values are 229.Dq rsa1 230for protocol version 1 and 231.Dq rsa 232or 233.Dq dsa 234for protocol version 2. 235.It Fl B 236Show the bubblebabble digest of specified private or public key file. 237.It Fl C Ar comment 238Provides the new comment. 239.It Fl D Ar reader 240Download the RSA public key stored in the smartcard in 241.Ar reader . 242.It Fl G Ar output_file 243Generate candidate primes for DH-GEX. 244These primes must be screened for 245safety (using the 246.Fl T 247option) before use. 248.It Fl M Ar memory 249Specify the amount of memory to use (in megabytes) when generating 250candidate moduli for DH-GEX. 251.It Fl N Ar new_passphrase 252Provides the new passphrase. 253.It Fl P Ar passphrase 254Provides the (old) passphrase. 255.It Fl S Ar start 256Specify start point (in hex) when generating candidate moduli for DH-GEX. 257.It Fl T Ar output_file 258Test DH group exchange candidate primes (generated using the 259.Fl G 260option) for safety. 261.It Fl W Ar generator 262Specify desired generator when testing candidate moduli for DH-GEX. 263.It Fl U Ar reader 264Upload an existing RSA private key into the smartcard in 265.Ar reader . 266.It Fl r Ar hostname 267Print DNS resource record with the specified 268.Ar hostname . 269.El 270.Sh MODULI GENERATION 271.Nm 272may be used to generate groups for the Diffie-Hellman Group Exchange 273(DH-GEX) protocol. 274Generating these groups is a two-step process: first, candidate 275primes are generated using a fast, but memory intensive process. 276These candidate primes are then tested for suitability (a CPU-intensive 277process). 278.Pp 279Generation of primes is performed using the 280.Fl G 281option. 282The desired length of the primes may be specified by the 283.Fl b 284option. 285For example: 286.Pp 287.Dl ssh-keygen -G moduli-2048.candidates -b 2048 288.Pp 289By default, the search for primes begins at a random point in the 290desired length range. 291This may be overridden using the 292.Fl S 293option, which specifies a different start point (in hex). 294.Pp 295Once a set of candidates have been generated, they must be tested for 296suitability. 297This may be performed using the 298.Fl T 299option. 300In this mode 301.Nm 302will read candidates from standard input (or a file specified using the 303.Fl f 304option). 305For example: 306.Pp 307.Dl ssh-keygen -T moduli-2048 -f moduli-2048.candidates 308.Pp 309By default, each candidate will be subjected to 100 primality tests. 310This may be overridden using the 311.Fl a 312option. 313The DH generator value will be chosen automatically for the 314prime under consideration. 315If a specific generator is desired, it may be requested using the 316.Fl W 317option. 318Valid generator values are 2, 3 and 5. 319.Pp 320Screened DH groups may be installed in 321.Pa /etc/moduli . 322It is important that this file contains moduli of a range of bit lengths and 323that both ends of a connection share common moduli. 324.Sh FILES 325.Bl -tag -width Ds 326.It Pa $HOME/.ssh/identity 327Contains the protocol version 1 RSA authentication identity of the user. 328This file should not be readable by anyone but the user. 329It is possible to 330specify a passphrase when generating the key; that passphrase will be 331used to encrypt the private part of this file using 3DES. 332This file is not automatically accessed by 333.Nm 334but it is offered as the default file for the private key. 335.Xr ssh 1 336will read this file when a login attempt is made. 337.It Pa $HOME/.ssh/identity.pub 338Contains the protocol version 1 RSA public key for authentication. 339The contents of this file should be added to 340.Pa $HOME/.ssh/authorized_keys 341on all machines 342where the user wishes to log in using RSA authentication. 343There is no need to keep the contents of this file secret. 344.It Pa $HOME/.ssh/id_dsa 345Contains the protocol version 2 DSA authentication identity of the user. 346This file should not be readable by anyone but the user. 347It is possible to 348specify a passphrase when generating the key; that passphrase will be 349used to encrypt the private part of this file using 3DES. 350This file is not automatically accessed by 351.Nm 352but it is offered as the default file for the private key. 353.Xr ssh 1 354will read this file when a login attempt is made. 355.It Pa $HOME/.ssh/id_dsa.pub 356Contains the protocol version 2 DSA public key for authentication. 357The contents of this file should be added to 358.Pa $HOME/.ssh/authorized_keys 359on all machines 360where the user wishes to log in using public key authentication. 361There is no need to keep the contents of this file secret. 362.It Pa $HOME/.ssh/id_rsa 363Contains the protocol version 2 RSA authentication identity of the user. 364This file should not be readable by anyone but the user. 365It is possible to 366specify a passphrase when generating the key; that passphrase will be 367used to encrypt the private part of this file using 3DES. 368This file is not automatically accessed by 369.Nm 370but it is offered as the default file for the private key. 371.Xr ssh 1 372will read this file when a login attempt is made. 373.It Pa $HOME/.ssh/id_rsa.pub 374Contains the protocol version 2 RSA public key for authentication. 375The contents of this file should be added to 376.Pa $HOME/.ssh/authorized_keys 377on all machines 378where the user wishes to log in using public key authentication. 379There is no need to keep the contents of this file secret. 380.It Pa /etc/moduli 381Contains Diffie-Hellman groups used for DH-GEX. 382The file format is described in 383.Xr moduli 5 . 384.El 385.Sh SEE ALSO 386.Xr ssh 1 , 387.Xr ssh-add 1 , 388.Xr ssh-agent 1 , 389.Xr moduli 5 , 390.Xr sshd 8 391.Rs 392.%A J. Galbraith 393.%A R. Thayer 394.%T "SECSH Public Key File Format" 395.%N draft-ietf-secsh-publickeyfile-01.txt 396.%D March 2001 397.%O work in progress material 398.Re 399.Sh AUTHORS 400OpenSSH is a derivative of the original and free 401ssh 1.2.12 release by Tatu Ylonen. 402Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 403Theo de Raadt and Dug Song 404removed many bugs, re-added newer features and 405created OpenSSH. 406Markus Friedl contributed the support for SSH 407protocol versions 1.5 and 2.0. 408