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