1.\" $OpenBSD: ssh-keygen.1,v 1.78 2008/06/12 19:10:09 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 June 12 2008 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 209RFC 4716 SSH 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 256RFC 4716 SSH 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. 265If combined with 266.Fl v , 267an ASCII art representation of the key is supplied with the fingerprint. 268.It Fl M Ar memory 269Specify the amount of memory to use (in megabytes) when generating 270candidate moduli for DH-GEX. 271.It Fl N Ar new_passphrase 272Provides the new passphrase. 273.It Fl P Ar passphrase 274Provides the (old) passphrase. 275.It Fl p 276Requests changing the passphrase of a private key file instead of 277creating a new private key. 278The program will prompt for the file 279containing the private key, for the old passphrase, and twice for the 280new passphrase. 281.It Fl q 282Silence 283.Nm ssh-keygen . 284Used by 285.Pa /etc/rc 286when creating a new key. 287.It Fl R Ar hostname 288Removes all keys belonging to 289.Ar hostname 290from a 291.Pa known_hosts 292file. 293This option is useful to delete hashed hosts (see the 294.Fl H 295option above). 296.It Fl r Ar hostname 297Print the SSHFP fingerprint resource record named 298.Ar hostname 299for the specified public key file. 300.It Fl S Ar start 301Specify start point (in hex) when generating candidate moduli for DH-GEX. 302.It Fl T Ar output_file 303Test DH group exchange candidate primes (generated using the 304.Fl G 305option) for safety. 306.It Fl t Ar type 307Specifies the type of key to create. 308The possible values are 309.Dq rsa1 310for protocol version 1 and 311.Dq rsa 312or 313.Dq dsa 314for protocol version 2. 315.It Fl U Ar reader 316Upload an existing RSA private key into the smartcard in 317.Ar reader . 318.It Fl v 319Verbose mode. 320Causes 321.Nm 322to print debugging messages about its progress. 323This is helpful for debugging moduli generation. 324Multiple 325.Fl v 326options increase the verbosity. 327The maximum is 3. 328.It Fl W Ar generator 329Specify desired generator when testing candidate moduli for DH-GEX. 330.It Fl y 331This option will read a private 332OpenSSH format file and print an OpenSSH public key to stdout. 333.El 334.Sh MODULI GENERATION 335.Nm 336may be used to generate groups for the Diffie-Hellman Group Exchange 337(DH-GEX) protocol. 338Generating these groups is a two-step process: first, candidate 339primes are generated using a fast, but memory intensive process. 340These candidate primes are then tested for suitability (a CPU-intensive 341process). 342.Pp 343Generation of primes is performed using the 344.Fl G 345option. 346The desired length of the primes may be specified by the 347.Fl b 348option. 349For example: 350.Pp 351.Dl # ssh-keygen -G moduli-2048.candidates -b 2048 352.Pp 353By default, the search for primes begins at a random point in the 354desired length range. 355This may be overridden using the 356.Fl S 357option, which specifies a different start point (in hex). 358.Pp 359Once a set of candidates have been generated, they must be tested for 360suitability. 361This may be performed using the 362.Fl T 363option. 364In this mode 365.Nm 366will read candidates from standard input (or a file specified using the 367.Fl f 368option). 369For example: 370.Pp 371.Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates 372.Pp 373By default, each candidate will be subjected to 100 primality tests. 374This may be overridden using the 375.Fl a 376option. 377The DH generator value will be chosen automatically for the 378prime under consideration. 379If a specific generator is desired, it may be requested using the 380.Fl W 381option. 382Valid generator values are 2, 3, and 5. 383.Pp 384Screened DH groups may be installed in 385.Pa /etc/moduli . 386It is important that this file contains moduli of a range of bit lengths and 387that both ends of a connection share common moduli. 388.Sh FILES 389.Bl -tag -width Ds 390.It Pa ~/.ssh/identity 391Contains the protocol version 1 RSA authentication identity of the user. 392This file should not be readable by anyone but the user. 393It is possible to 394specify a passphrase when generating the key; that passphrase will be 395used to encrypt the private part of this file using 3DES. 396This file is not automatically accessed by 397.Nm 398but it is offered as the default file for the private key. 399.Xr ssh 1 400will read this file when a login attempt is made. 401.It Pa ~/.ssh/identity.pub 402Contains the protocol version 1 RSA public key for authentication. 403The contents of this file should be added to 404.Pa ~/.ssh/authorized_keys 405on all machines 406where the user wishes to log in using RSA authentication. 407There is no need to keep the contents of this file secret. 408.It Pa ~/.ssh/id_dsa 409Contains the protocol version 2 DSA authentication identity of the user. 410This file should not be readable by anyone but the user. 411It is possible to 412specify a passphrase when generating the key; that passphrase will be 413used to encrypt the private part of this file using 3DES. 414This file is not automatically accessed by 415.Nm 416but it is offered as the default file for the private key. 417.Xr ssh 1 418will read this file when a login attempt is made. 419.It Pa ~/.ssh/id_dsa.pub 420Contains the protocol version 2 DSA public key for authentication. 421The contents of this file should be added to 422.Pa ~/.ssh/authorized_keys 423on all machines 424where the user wishes to log in using public key authentication. 425There is no need to keep the contents of this file secret. 426.It Pa ~/.ssh/id_rsa 427Contains the protocol version 2 RSA authentication identity of the user. 428This file should not be readable by anyone but the user. 429It is possible to 430specify a passphrase when generating the key; that passphrase will be 431used to encrypt the private part of this file using 3DES. 432This file is not automatically accessed by 433.Nm 434but it is offered as the default file for the private key. 435.Xr ssh 1 436will read this file when a login attempt is made. 437.It Pa ~/.ssh/id_rsa.pub 438Contains the protocol version 2 RSA public key for authentication. 439The contents of this file should be added to 440.Pa ~/.ssh/authorized_keys 441on all machines 442where the user wishes to log in using public key authentication. 443There is no need to keep the contents of this file secret. 444.It Pa /etc/moduli 445Contains Diffie-Hellman groups used for DH-GEX. 446The file format is described in 447.Xr moduli 5 . 448.El 449.Sh SEE ALSO 450.Xr ssh 1 , 451.Xr ssh-add 1 , 452.Xr ssh-agent 1 , 453.Xr moduli 5 , 454.Xr sshd 8 455.Rs 456.%R RFC 4716 457.%T "The Secure Shell (SSH) Public Key File Format" 458.%D 2006 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