1.\" $MirOS: src/usr.bin/ssh/ssh-keygen.1,v 1.13 2011/01/15 21:52:41 tg Exp $ 2.\" $OpenBSD: ssh-keygen.1,v 1.79 2008/07/24 23:55:30 sthen Exp $ 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 $Mdocdate: January 15 2011 $ 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 iI 64.Op Fl f Ar input_keyfile 65.Nm ssh-keygen 66.Fl eE 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 ~/.etc/ssh/identity , 138.Pa ~/.etc/ssh/id_dsa 139or 140.Pa ~/.etc/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 E 216This option will read a private or public OpenSSH RSAv2 key file and 217print the RSA public key in a PEM encoded format suitable for the 218.Xr openssl 1 219command to stdout. 220.It Fl F Ar hostname 221Search for the specified 222.Ar hostname 223in a 224.Pa known_hosts 225file, listing any occurrences found. 226This option is useful to find hashed host names or addresses and may also be 227used in conjunction with the 228.Fl H 229option to print found keys in a hashed format. 230.It Fl f Ar filename 231Specifies the filename of the key file. 232.It Fl G Ar output_file 233Generate candidate primes for DH-GEX. 234These primes must be screened for 235safety (using the 236.Fl T 237option) before use. 238.It Fl g 239Use generic DNS format when printing fingerprint resource records using the 240.Fl r 241command. 242.It Fl H 243Hash a 244.Pa known_hosts 245file. 246This replaces all hostnames and addresses with hashed representations 247within the specified file; the original content is moved to a file with 248a .old suffix. 249These hashes may be used normally by 250.Nm ssh 251and 252.Nm sshd , 253but they do not reveal identifying information should the file's contents 254be disclosed. 255This option will not modify existing hashed hostnames and is therefore safe 256to use on files that mix hashed and non-hashed names. 257.It Fl i 258This option will read an unencrypted private (or public) key file 259in SSH2-compatible format and print an OpenSSH compatible private 260(or public) key to stdout. 261.Nm 262also reads the 263RFC 4716 SSH Public Key File Format. 264This option allows importing keys from several commercial 265SSH implementations. 266.It Fl I 267This option will read a PEM encoded RSA public 268key or X.509 certificate file in the 269.Xr openssl 1 270tool format and print an OpenSSH compatible RSAv2 public key to stdout. 271.It Fl l 272Show fingerprint of specified public key file. 273Private RSA1 keys are also supported. 274For RSA and DSA keys 275.Nm 276tries to find the matching public key file and prints its fingerprint. 277If combined with 278.Fl v , 279an ASCII art representation of the key is supplied with the fingerprint. 280.It Fl M Ar memory 281Specify the amount of memory to use (in megabytes) when generating 282candidate moduli for DH-GEX. 283.It Fl N Ar new_passphrase 284Provides the new passphrase. 285.It Fl P Ar passphrase 286Provides the (old) passphrase. 287.It Fl p 288Requests changing the passphrase of a private key file instead of 289creating a new private key. 290The program will prompt for the file 291containing the private key, for the old passphrase, and twice for the 292new passphrase. 293.It Fl q 294Silence 295.Nm ssh-keygen . 296Used by 297.Pa /etc/rc 298when creating a new key. 299.It Fl R Ar hostname 300Removes all keys belonging to 301.Ar hostname 302from a 303.Pa known_hosts 304file. 305This option is useful to delete hashed hosts (see the 306.Fl H 307option above). 308.It Fl r Ar hostname 309Print the SSHFP fingerprint resource record named 310.Ar hostname 311for the specified public key file. 312.It Fl S Ar start 313Specify start point (in hex) when generating candidate moduli for DH-GEX. 314.It Fl T Ar output_file 315Test DH group exchange candidate primes (generated using the 316.Fl G 317option) for safety. 318.It Fl t Ar type 319Specifies the type of key to create. 320The possible values are 321.Dq rsa1 322for protocol version 1 and 323.Dq rsa 324or 325.Dq dsa 326for protocol version 2. 327.It Fl U Ar reader 328Upload an existing RSA private key into the smartcard in 329.Ar reader . 330.It Fl v 331Verbose mode. 332Causes 333.Nm 334to print debugging messages about its progress. 335This is helpful for debugging moduli generation. 336Multiple 337.Fl v 338options increase the verbosity. 339The maximum is 3. 340.It Fl W Ar generator 341Specify desired generator when testing candidate moduli for DH-GEX. 342.It Fl y 343This option will read a private 344OpenSSH format file and print an OpenSSH public key to stdout. 345.El 346.Sh MODULI GENERATION 347.Nm 348may be used to generate groups for the Diffie-Hellman Group Exchange 349(DH-GEX) protocol. 350Generating these groups is a two-step process: first, candidate 351primes are generated using a fast, but memory intensive process. 352These candidate primes are then tested for suitability (a CPU-intensive 353process). 354.Pp 355Generation of primes is performed using the 356.Fl G 357option. 358The desired length of the primes may be specified by the 359.Fl b 360option. 361For example: 362.Pp 363.Dl # ssh-keygen -G moduli-2048.candidates -b 2048 364.Pp 365By default, the search for primes begins at a random point in the 366desired length range. 367This may be overridden using the 368.Fl S 369option, which specifies a different start point (in hex). 370.Pp 371Once a set of candidates have been generated, they must be tested for 372suitability. 373This may be performed using the 374.Fl T 375option. 376In this mode 377.Nm 378will read candidates from standard input (or a file specified using the 379.Fl f 380option). 381For example: 382.Pp 383.Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates 384.Pp 385By default, each candidate will be subjected to 100 primality tests. 386This may be overridden using the 387.Fl a 388option. 389The DH generator value will be chosen automatically for the 390prime under consideration. 391If a specific generator is desired, it may be requested using the 392.Fl W 393option. 394Valid generator values are 2, 3, and 5. 395.Pp 396Screened DH groups may be installed in 397.Pa /etc/moduli . 398It is important that this file contains moduli of a range of bit lengths and 399that both ends of a connection share common moduli. 400.Sh FILES 401.Bl -tag -width Ds 402.It Pa ~/.etc/ssh/identity 403Contains the protocol version 1 RSA authentication identity of the user. 404This file should not be readable by anyone but the user. 405It is possible to 406specify a passphrase when generating the key; that passphrase will be 407used to encrypt the private part of this file using 3DES. 408This file is not automatically accessed by 409.Nm 410but it is offered as the default file for the private key. 411.Xr ssh 1 412will read this file when a login attempt is made. 413.It Pa ~/.etc/ssh/identity.pub 414Contains the protocol version 1 RSA public key for authentication. 415The contents of this file should be added to 416.Pa ~/.etc/ssh/authorised_keys 417.Po or Pa ~/.ssh/authorized_keys Pc 418on all machines 419where the user wishes to log in using RSA authentication. 420If the user is the superuser and his home directory the root or unset, 421.Pa /etc/ssh/root:authorised_keys 422is used instead. 423There is no need to keep the contents of this file secret. 424.It Pa ~/.etc/ssh/id_dsa 425Contains the protocol version 2 DSA authentication identity of the user. 426This file should not be readable by anyone but the user. 427It is possible to 428specify a passphrase when generating the key; that passphrase will be 429used to encrypt the private part of this file using 3DES. 430This file is not automatically accessed by 431.Nm 432but it is offered as the default file for the private key. 433.Xr ssh 1 434will read this file when a login attempt is made. 435.It Pa ~/.etc/ssh/id_dsa.pub 436Contains the protocol version 2 DSA public key for authentication. 437The contents of this file should be added to 438.Pa ~/.etc/ssh/authorised_keys 439.Po or Pa ~/.ssh/authorized_keys Pc 440on all machines 441where the user wishes to log in using public key authentication. 442If the user is the superuser and his home directory the root or unset, 443.Pa /etc/ssh/root:authorised_keys 444is used instead. 445There is no need to keep the contents of this file secret. 446.It Pa ~/.etc/ssh/id_rsa 447Contains the protocol version 2 RSA authentication identity of the user. 448This file should not be readable by anyone but the user. 449It is possible to 450specify a passphrase when generating the key; that passphrase will be 451used to encrypt the private part of this file using 3DES. 452This file is not automatically accessed by 453.Nm 454but it is offered as the default file for the private key. 455.Xr ssh 1 456will read this file when a login attempt is made. 457.It Pa ~/.etc/ssh/id_rsa.pub 458Contains the protocol version 2 RSA public key for authentication. 459The contents of this file should be added to 460.Pa ~/.etc/ssh/authorised_keys 461.Po or Pa ~/.ssh/authorized_keys Pc 462on all machines 463where the user wishes to log in using public key authentication. 464If the user is the superuser and his home directory the root or unset, 465.Pa /etc/ssh/root:authorised_keys 466is used instead. 467There is no need to keep the contents of this file secret. 468.It Pa /etc/moduli 469Contains Diffie-Hellman groups used for DH-GEX. 470The file format is described in 471.Xr moduli 5 . 472.El 473.Sh SEE ALSO 474.Xr ssh 1 , 475.Xr ssh-add 1 , 476.Xr ssh-agent 1 , 477.Xr moduli 5 , 478.Xr sshd 8 479.Rs 480.%R RFC 4716 481.%T "The Secure Shell (SSH) Public Key File Format" 482.%D 2006 483.Re 484.Sh AUTHORS 485OpenSSH is a derivative of the original and free 486ssh 1.2.12 release by Tatu Ylonen. 487Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 488Theo de Raadt and Dug Song 489removed many bugs, re-added newer features and 490created OpenSSH. 491Markus Friedl contributed the support for SSH 492protocol versions 1.5 and 2.0. 493