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