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