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