1.\" $OpenBSD: ssh-keygen.1,v 1.63 2004/08/13 00:01:43 jmc 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 format when printing fingerprint resource records using the 196.Fl r 197command. 198.It Fl f Ar filename 199Specifies the filename of the key file. 200.It Fl i 201This option will read an unencrypted private (or public) key file 202in SSH2-compatible format and print an OpenSSH compatible private 203(or public) key to stdout. 204.Nm 205also reads the 206.Sq SECSH Public Key File Format . 207This option allows importing keys from several commercial 208SSH implementations. 209.It Fl l 210Show fingerprint of specified public key file. 211Private RSA1 keys are also supported. 212For RSA and DSA keys 213.Nm 214tries to find the matching public key file and prints its fingerprint. 215.It Fl p 216Requests changing the passphrase of a private key file instead of 217creating a new private key. 218The program will prompt for the file 219containing the private key, for the old passphrase, and twice for the 220new passphrase. 221.It Fl q 222Silence 223.Nm ssh-keygen . 224Used by 225.Pa /etc/rc 226when creating a new key. 227.It Fl y 228This option will read a private 229OpenSSH format file and print an OpenSSH public key to stdout. 230.It Fl t Ar type 231Specifies the type of the key to create. 232The possible values are 233.Dq rsa1 234for protocol version 1 and 235.Dq rsa 236or 237.Dq dsa 238for protocol version 2. 239.It Fl B 240Show the bubblebabble digest of specified private or public key file. 241.It Fl C Ar comment 242Provides the new comment. 243.It Fl D Ar reader 244Download the RSA public key stored in the smartcard in 245.Ar reader . 246.It Fl G Ar output_file 247Generate candidate primes for DH-GEX. 248These primes must be screened for 249safety (using the 250.Fl T 251option) before use. 252.It Fl M Ar memory 253Specify the amount of memory to use (in megabytes) when generating 254candidate moduli for DH-GEX. 255.It Fl N Ar new_passphrase 256Provides the new passphrase. 257.It Fl P Ar passphrase 258Provides the (old) passphrase. 259.It Fl S Ar start 260Specify start point (in hex) when generating candidate moduli for DH-GEX. 261.It Fl T Ar output_file 262Test DH group exchange candidate primes (generated using the 263.Fl G 264option) for safety. 265.It Fl W Ar generator 266Specify desired generator when testing candidate moduli for DH-GEX. 267.It Fl U Ar reader 268Upload an existing RSA private key into the smartcard in 269.Ar reader . 270.It Fl v 271Verbose mode. 272Causes 273.Nm 274to print debugging messages about its progress. 275This is helpful for debugging moduli generation. 276Multiple 277.Fl v 278options increase the verbosity. 279The maximum is 3. 280.It Fl r Ar hostname 281Print the SSHFP fingerprint resource record named 282.Ar hostname 283for the specified public key file. 284.El 285.Sh MODULI GENERATION 286.Nm 287may be used to generate groups for the Diffie-Hellman Group Exchange 288(DH-GEX) protocol. 289Generating these groups is a two-step process: first, candidate 290primes are generated using a fast, but memory intensive process. 291These candidate primes are then tested for suitability (a CPU-intensive 292process). 293.Pp 294Generation of primes is performed using the 295.Fl G 296option. 297The desired length of the primes may be specified by the 298.Fl b 299option. 300For example: 301.Pp 302.Dl ssh-keygen -G moduli-2048.candidates -b 2048 303.Pp 304By default, the search for primes begins at a random point in the 305desired length range. 306This may be overridden using the 307.Fl S 308option, which specifies a different start point (in hex). 309.Pp 310Once a set of candidates have been generated, they must be tested for 311suitability. 312This may be performed using the 313.Fl T 314option. 315In this mode 316.Nm 317will read candidates from standard input (or a file specified using the 318.Fl f 319option). 320For example: 321.Pp 322.Dl ssh-keygen -T moduli-2048 -f moduli-2048.candidates 323.Pp 324By default, each candidate will be subjected to 100 primality tests. 325This may be overridden using the 326.Fl a 327option. 328The DH generator value will be chosen automatically for the 329prime under consideration. 330If a specific generator is desired, it may be requested using the 331.Fl W 332option. 333Valid generator values are 2, 3 and 5. 334.Pp 335Screened DH groups may be installed in 336.Pa /etc/moduli . 337It is important that this file contains moduli of a range of bit lengths and 338that both ends of a connection share common moduli. 339.Sh FILES 340.Bl -tag -width Ds 341.It Pa $HOME/.ssh/identity 342Contains the protocol version 1 RSA authentication identity of the user. 343This file should not be readable by anyone but the user. 344It is possible to 345specify a passphrase when generating the key; that passphrase will be 346used to encrypt the private part of this file using 3DES. 347This file is not automatically accessed by 348.Nm 349but it is offered as the default file for the private key. 350.Xr ssh 1 351will read this file when a login attempt is made. 352.It Pa $HOME/.ssh/identity.pub 353Contains the protocol version 1 RSA public key for authentication. 354The contents of this file should be added to 355.Pa $HOME/.ssh/authorized_keys 356on all machines 357where the user wishes to log in using RSA authentication. 358There is no need to keep the contents of this file secret. 359.It Pa $HOME/.ssh/id_dsa 360Contains the protocol version 2 DSA authentication identity of the user. 361This file should not be readable by anyone but the user. 362It is possible to 363specify a passphrase when generating the key; that passphrase will be 364used to encrypt the private part of this file using 3DES. 365This file is not automatically accessed by 366.Nm 367but it is offered as the default file for the private key. 368.Xr ssh 1 369will read this file when a login attempt is made. 370.It Pa $HOME/.ssh/id_dsa.pub 371Contains the protocol version 2 DSA public key for authentication. 372The contents of this file should be added to 373.Pa $HOME/.ssh/authorized_keys 374on all machines 375where the user wishes to log in using public key authentication. 376There is no need to keep the contents of this file secret. 377.It Pa $HOME/.ssh/id_rsa 378Contains the protocol version 2 RSA authentication identity of the user. 379This file should not be readable by anyone but the user. 380It is possible to 381specify a passphrase when generating the key; that passphrase will be 382used to encrypt the private part of this file using 3DES. 383This file is not automatically accessed by 384.Nm 385but it is offered as the default file for the private key. 386.Xr ssh 1 387will read this file when a login attempt is made. 388.It Pa $HOME/.ssh/id_rsa.pub 389Contains the protocol version 2 RSA public key for authentication. 390The contents of this file should be added to 391.Pa $HOME/.ssh/authorized_keys 392on all machines 393where the user wishes to log in using public key authentication. 394There is no need to keep the contents of this file secret. 395.It Pa /etc/moduli 396Contains Diffie-Hellman groups used for DH-GEX. 397The file format is described in 398.Xr moduli 5 . 399.El 400.Sh SEE ALSO 401.Xr ssh 1 , 402.Xr ssh-add 1 , 403.Xr ssh-agent 1 , 404.Xr moduli 5 , 405.Xr sshd 8 406.Rs 407.%A J. Galbraith 408.%A R. Thayer 409.%T "SECSH Public Key File Format" 410.%N draft-ietf-secsh-publickeyfile-01.txt 411.%D March 2001 412.%O work in progress material 413.Re 414.Sh AUTHORS 415OpenSSH is a derivative of the original and free 416ssh 1.2.12 release by Tatu Ylonen. 417Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 418Theo de Raadt and Dug Song 419removed many bugs, re-added newer features and 420created OpenSSH. 421Markus Friedl contributed the support for SSH 422protocol versions 1.5 and 2.0. 423