1.\" $OpenBSD: ssh-keygen.1,v 1.61 2003/12/22 09:16:58 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 v 93.Op Fl b Ar bits 94.Op Fl M Ar memory 95.Op Fl S Ar start_point 96.Nm ssh-keygen 97.Fl T Ar output_file 98.Fl f Ar input_file 99.Op Fl v 100.Op Fl a Ar num_trials 101.Op Fl W Ar generator 102.Sh DESCRIPTION 103.Nm 104generates, manages and converts authentication keys for 105.Xr ssh 1 . 106.Nm 107can create RSA keys for use by SSH protocol version 1 and RSA or DSA 108keys for use by SSH protocol version 2. 109The type of key to be generated is specified with the 110.Fl t 111option. 112.Pp 113.Nm 114is also used to generate groups for use in Diffie-Hellman group 115exchange (DH-GEX). 116See the 117.Sx MODULI GENERATION 118section for details. 119.Pp 120Normally each user wishing to use SSH 121with RSA or DSA authentication runs this once to create the authentication 122key in 123.Pa $HOME/.ssh/identity , 124.Pa $HOME/.ssh/id_dsa 125or 126.Pa $HOME/.ssh/id_rsa . 127Additionally, the system administrator may use this to generate host keys, 128as seen in 129.Pa /etc/rc . 130.Pp 131Normally this program generates the key and asks for a file in which 132to store the private key. 133The public key is stored in a file with the same name but 134.Dq .pub 135appended. 136The program also asks for a passphrase. 137The passphrase may be empty to indicate no passphrase 138(host keys must have an empty passphrase), or it may be a string of 139arbitrary length. 140A passphrase is similar to a password, except it can be a phrase with a 141series of words, punctuation, numbers, whitespace, or any string of 142characters you want. 143Good passphrases are 10-30 characters long, are 144not simple sentences or otherwise easily guessable (English 145prose has only 1-2 bits of entropy per character, and provides very bad 146passphrases), and contain a mix of upper and lowercase letters, 147numbers, and non-alphanumeric characters. 148The passphrase can be changed later by using the 149.Fl p 150option. 151.Pp 152There is no way to recover a lost passphrase. 153If the passphrase is 154lost or forgotten, a new key must be generated and copied to the 155corresponding public key to other machines. 156.Pp 157For RSA1 keys, 158there is also a comment field in the key file that is only for 159convenience to the user to help identify the key. 160The comment can tell what the key is for, or whatever is useful. 161The comment is initialized to 162.Dq user@host 163when the key is created, but can be changed using the 164.Fl c 165option. 166.Pp 167After a key is generated, instructions below detail where the keys 168should be placed to be activated. 169.Pp 170The options are as follows: 171.Bl -tag -width Ds 172.It Fl a Ar trials 173Specifies the number of primality tests to perform when screening DH-GEX 174candidates using the 175.Fl T 176command. 177.It Fl b Ar bits 178Specifies the number of bits in the key to create. 179Minimum is 512 bits. 180Generally, 1024 bits is considered sufficient. 181The default is 1024 bits. 182.It Fl c 183Requests changing the comment in the private and public key files. 184This operation is only supported for RSA1 keys. 185The program will prompt for the file containing the private keys, for 186the passphrase if the key has one, and for the new comment. 187.It Fl e 188This option will read a private or public OpenSSH key file and 189print the key in a 190.Sq SECSH Public Key File Format 191to stdout. 192This option allows exporting keys for use by several commercial 193SSH implementations. 194.It Fl g 195Use generic DNS resource record format. 196.It Fl f Ar filename 197Specifies the filename of the key file. 198.It Fl i 199This option will read an unencrypted private (or public) key file 200in SSH2-compatible format and print an OpenSSH compatible private 201(or public) key to stdout. 202.Nm 203also reads the 204.Sq SECSH Public Key File Format . 205This option allows importing keys from several commercial 206SSH implementations. 207.It Fl l 208Show fingerprint of specified public key file. 209Private RSA1 keys are also supported. 210For RSA and DSA keys 211.Nm 212tries to find the matching public key file and prints its fingerprint. 213.It Fl p 214Requests changing the passphrase of a private key file instead of 215creating a new private key. 216The program will prompt for the file 217containing the private key, for the old passphrase, and twice for the 218new passphrase. 219.It Fl q 220Silence 221.Nm ssh-keygen . 222Used by 223.Pa /etc/rc 224when creating a new key. 225.It Fl y 226This option will read a private 227OpenSSH format file and print an OpenSSH public key to stdout. 228.It Fl t Ar type 229Specifies the type of the key to create. 230The possible values are 231.Dq rsa1 232for protocol version 1 and 233.Dq rsa 234or 235.Dq dsa 236for protocol version 2. 237.It Fl B 238Show the bubblebabble digest of specified private or public key file. 239.It Fl C Ar comment 240Provides the new comment. 241.It Fl D Ar reader 242Download the RSA public key stored in the smartcard in 243.Ar reader . 244.It Fl G Ar output_file 245Generate candidate primes for DH-GEX. 246These primes must be screened for 247safety (using the 248.Fl T 249option) before use. 250.It Fl M Ar memory 251Specify the amount of memory to use (in megabytes) when generating 252candidate moduli for DH-GEX. 253.It Fl N Ar new_passphrase 254Provides the new passphrase. 255.It Fl P Ar passphrase 256Provides the (old) passphrase. 257.It Fl S Ar start 258Specify start point (in hex) when generating candidate moduli for DH-GEX. 259.It Fl T Ar output_file 260Test DH group exchange candidate primes (generated using the 261.Fl G 262option) for safety. 263.It Fl W Ar generator 264Specify desired generator when testing candidate moduli for DH-GEX. 265.It Fl U Ar reader 266Upload an existing RSA private key into the smartcard in 267.Ar reader . 268.It Fl v 269Verbose mode. 270Causes 271.Nm 272to print debugging messages about its progress. 273This is helpful for debugging moduli generation. 274Multiple 275.Fl v 276options increase the verbosity. 277The maximum is 3. 278.It Fl r Ar hostname 279Print DNS resource record with the specified 280.Ar hostname . 281.El 282.Sh MODULI GENERATION 283.Nm 284may be used to generate groups for the Diffie-Hellman Group Exchange 285(DH-GEX) protocol. 286Generating these groups is a two-step process: first, candidate 287primes are generated using a fast, but memory intensive process. 288These candidate primes are then tested for suitability (a CPU-intensive 289process). 290.Pp 291Generation of primes is performed using the 292.Fl G 293option. 294The desired length of the primes may be specified by the 295.Fl b 296option. 297For example: 298.Pp 299.Dl ssh-keygen -G moduli-2048.candidates -b 2048 300.Pp 301By default, the search for primes begins at a random point in the 302desired length range. 303This may be overridden using the 304.Fl S 305option, which specifies a different start point (in hex). 306.Pp 307Once a set of candidates have been generated, they must be tested for 308suitability. 309This may be performed using the 310.Fl T 311option. 312In this mode 313.Nm 314will read candidates from standard input (or a file specified using the 315.Fl f 316option). 317For example: 318.Pp 319.Dl ssh-keygen -T moduli-2048 -f moduli-2048.candidates 320.Pp 321By default, each candidate will be subjected to 100 primality tests. 322This may be overridden using the 323.Fl a 324option. 325The DH generator value will be chosen automatically for the 326prime under consideration. 327If a specific generator is desired, it may be requested using the 328.Fl W 329option. 330Valid generator values are 2, 3 and 5. 331.Pp 332Screened DH groups may be installed in 333.Pa /etc/moduli . 334It is important that this file contains moduli of a range of bit lengths and 335that both ends of a connection share common moduli. 336.Sh FILES 337.Bl -tag -width Ds 338.It Pa $HOME/.ssh/identity 339Contains the protocol version 1 RSA authentication identity of the user. 340This file should not be readable by anyone but the user. 341It is possible to 342specify a passphrase when generating the key; that passphrase will be 343used to encrypt the private part of this file using 3DES. 344This file is not automatically accessed by 345.Nm 346but it is offered as the default file for the private key. 347.Xr ssh 1 348will read this file when a login attempt is made. 349.It Pa $HOME/.ssh/identity.pub 350Contains the protocol version 1 RSA public key for authentication. 351The contents of this file should be added to 352.Pa $HOME/.ssh/authorized_keys 353on all machines 354where the user wishes to log in using RSA authentication. 355There is no need to keep the contents of this file secret. 356.It Pa $HOME/.ssh/id_dsa 357Contains the protocol version 2 DSA authentication identity of the user. 358This file should not be readable by anyone but the user. 359It is possible to 360specify a passphrase when generating the key; that passphrase will be 361used to encrypt the private part of this file using 3DES. 362This file is not automatically accessed by 363.Nm 364but it is offered as the default file for the private key. 365.Xr ssh 1 366will read this file when a login attempt is made. 367.It Pa $HOME/.ssh/id_dsa.pub 368Contains the protocol version 2 DSA public key for authentication. 369The contents of this file should be added to 370.Pa $HOME/.ssh/authorized_keys 371on all machines 372where the user wishes to log in using public key authentication. 373There is no need to keep the contents of this file secret. 374.It Pa $HOME/.ssh/id_rsa 375Contains the protocol version 2 RSA authentication identity of the user. 376This file should not be readable by anyone but the user. 377It is possible to 378specify a passphrase when generating the key; that passphrase will be 379used to encrypt the private part of this file using 3DES. 380This file is not automatically accessed by 381.Nm 382but it is offered as the default file for the private key. 383.Xr ssh 1 384will read this file when a login attempt is made. 385.It Pa $HOME/.ssh/id_rsa.pub 386Contains the protocol version 2 RSA public key for authentication. 387The contents of this file should be added to 388.Pa $HOME/.ssh/authorized_keys 389on all machines 390where the user wishes to log in using public key authentication. 391There is no need to keep the contents of this file secret. 392.It Pa /etc/moduli 393Contains Diffie-Hellman groups used for DH-GEX. 394The file format is described in 395.Xr moduli 5 . 396.El 397.Sh SEE ALSO 398.Xr ssh 1 , 399.Xr ssh-add 1 , 400.Xr ssh-agent 1 , 401.Xr moduli 5 , 402.Xr sshd 8 403.Rs 404.%A J. Galbraith 405.%A R. Thayer 406.%T "SECSH Public Key File Format" 407.%N draft-ietf-secsh-publickeyfile-01.txt 408.%D March 2001 409.%O work in progress material 410.Re 411.Sh AUTHORS 412OpenSSH is a derivative of the original and free 413ssh 1.2.12 release by Tatu Ylonen. 414Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 415Theo de Raadt and Dug Song 416removed many bugs, re-added newer features and 417created OpenSSH. 418Markus Friedl contributed the support for SSH 419protocol versions 1.5 and 2.0. 420