ssh-keygen.0 revision 180744
124139SjoergSSH-KEYGEN(1) OpenBSD Reference Manual SSH-KEYGEN(1) 289750Sdwmalone 389750SdwmaloneNAME 424139Sjoerg ssh-keygen - authentication key generation, management and conversion 524139Sjoerg 689750SdwmaloneSYNOPSIS 724139Sjoerg ssh-keygen [-q] [-b bits] -t type [-N new_passphrase] [-C comment] 824139Sjoerg [-f output_keyfile] 924139Sjoerg ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile] 1024139Sjoerg ssh-keygen -i [-f input_keyfile] 1124139Sjoerg ssh-keygen -e [-f input_keyfile] 1224139Sjoerg ssh-keygen -y [-f input_keyfile] 1324139Sjoerg ssh-keygen -c [-P passphrase] [-C comment] [-f keyfile] 1424139Sjoerg ssh-keygen -l [-f input_keyfile] 1524139Sjoerg ssh-keygen -B [-f input_keyfile] 1624139Sjoerg ssh-keygen -D reader 1724139Sjoerg ssh-keygen -F hostname [-f known_hosts_file] 1889750Sdwmalone ssh-keygen -H [-f known_hosts_file] 1989750Sdwmalone ssh-keygen -R hostname [-f known_hosts_file] 2089750Sdwmalone ssh-keygen -U reader [-f input_keyfile] 2189750Sdwmalone ssh-keygen -r hostname [-f input_keyfile] [-g] 2289750Sdwmalone ssh-keygen -G output_file [-v] [-b bits] [-M memory] [-S start_point] 2389750Sdwmalone ssh-keygen -T output_file -f input_file [-v] [-a num_trials] [-W 2424139Sjoerg generator] 2524139Sjoerg 2689750SdwmaloneDESCRIPTION 2789750Sdwmalone ssh-keygen generates, manages and converts authentication keys for 2889750Sdwmalone ssh(1). ssh-keygen can create RSA keys for use by SSH protocol version 1 2989750Sdwmalone and RSA or DSA keys for use by SSH protocol version 2. The type of key 3024139Sjoerg to be generated is specified with the -t option. If invoked without any 3124139Sjoerg arguments, ssh-keygen will generate an RSA key for use in SSH protocol 2 3224139Sjoerg connections. 3389750Sdwmalone 3489750Sdwmalone ssh-keygen is also used to generate groups for use in Diffie-Hellman 3589750Sdwmalone group exchange (DH-GEX). See the MODULI GENERATION section for details. 3689750Sdwmalone 3789750Sdwmalone Normally each user wishing to use SSH with RSA or DSA authentication runs 3889750Sdwmalone this once to create the authentication key in ~/.ssh/identity, 3989750Sdwmalone ~/.ssh/id_dsa or ~/.ssh/id_rsa. Additionally, the system administrator 4024139Sjoerg may use this to generate host keys, as seen in /etc/rc. 4189750Sdwmalone 4289750Sdwmalone Normally this program generates the key and asks for a file in which to 4389750Sdwmalone store the private key. The public key is stored in a file with the same 4489750Sdwmalone name but ``.pub'' appended. The program also asks for a passphrase. The 4589750Sdwmalone passphrase may be empty to indicate no passphrase (host keys must have an 4689750Sdwmalone empty passphrase), or it may be a string of arbitrary length. A 4789750Sdwmalone passphrase is similar to a password, except it can be a phrase with a se- 4889750Sdwmalone ries of words, punctuation, numbers, whitespace, or any string of charac- 4924139Sjoerg ters you want. Good passphrases are 10-30 characters long, are not sim- 5089750Sdwmalone ple sentences or otherwise easily guessable (English prose has only 1-2 5124139Sjoerg bits of entropy per character, and provides very bad passphrases), and 5289750Sdwmalone contain a mix of upper and lowercase letters, numbers, and non-alphanu- 5389750Sdwmalone meric characters. The passphrase can be changed later by using the -p 5489750Sdwmalone option. 5589750Sdwmalone 5689750Sdwmalone There is no way to recover a lost passphrase. If the passphrase is lost 5724139Sjoerg or forgotten, a new key must be generated and copied to the corresponding 5824139Sjoerg public key to other machines. 5924139Sjoerg 6089750Sdwmalone For RSA1 keys, there is also a comment field in the key file that is only 6189750Sdwmalone for convenience to the user to help identify the key. The comment can 6289750Sdwmalone tell what the key is for, or whatever is useful. The comment is initial- 6389750Sdwmalone ized to ``user@host'' when the key is created, but can be changed using 6424139Sjoerg the -c option. 6524139Sjoerg 6624139Sjoerg After a key is generated, instructions below detail where the keys should 6724139Sjoerg be placed to be activated. 6889750Sdwmalone 6924139Sjoerg The options are as follows: 7024139Sjoerg 7124139Sjoerg -a trials 7224139Sjoerg Specifies the number of primality tests to perform when screening 7324139Sjoerg DH-GEX candidates using the -T command. 7424139Sjoerg 7524139Sjoerg -B Show the bubblebabble digest of specified private or public key 7624139Sjoerg file. 7724139Sjoerg 7824139Sjoerg -b bits 7924139Sjoerg Specifies the number of bits in the key to create. For RSA keys, 8024139Sjoerg the minimum size is 768 bits and the default is 2048 bits. Gen- 8124139Sjoerg erally, 2048 bits is considered sufficient. DSA keys must be ex- 8224139Sjoerg actly 1024 bits as specified by FIPS 186-2. 8324139Sjoerg 8424139Sjoerg -C comment 8524139Sjoerg Provides a new comment. 8624139Sjoerg 8724139Sjoerg -c Requests changing the comment in the private and public key 8824139Sjoerg files. This operation is only supported for RSA1 keys. The pro- 8924139Sjoerg gram will prompt for the file containing the private keys, for 9024139Sjoerg the passphrase if the key has one, and for the new comment. 9189750Sdwmalone 9224139Sjoerg -D reader 9324139Sjoerg Download the RSA public key stored in the smartcard in reader. 9424139Sjoerg 9524139Sjoerg -e This option will read a private or public OpenSSH key file and 9624139Sjoerg print the key in RFC 4716 SSH Public Key File Format to stdout. 9724139Sjoerg This option allows exporting keys for use by several commercial 9824139Sjoerg SSH implementations. 9924139Sjoerg 10024139Sjoerg -F hostname 10124139Sjoerg Search for the specified hostname in a known_hosts file, listing 10224139Sjoerg any occurrences found. This option is useful to find hashed host 10324139Sjoerg names or addresses and may also be used in conjunction with the 10424139Sjoerg -H option to print found keys in a hashed format. 10524139Sjoerg 10624139Sjoerg -f filename 10724139Sjoerg Specifies the filename of the key file. 10824139Sjoerg 10924139Sjoerg -G output_file 11024139Sjoerg Generate candidate primes for DH-GEX. These primes must be 11124139Sjoerg screened for safety (using the -T option) before use. 11224139Sjoerg 11324139Sjoerg -g Use generic DNS format when printing fingerprint resource records 11424139Sjoerg using the -r command. 11524139Sjoerg 11624139Sjoerg -H Hash a known_hosts file. This replaces all hostnames and ad- 11724139Sjoerg dresses with hashed representations within the specified file; 11824139Sjoerg the original content is moved to a file with a .old suffix. 11924139Sjoerg These hashes may be used normally by ssh and sshd, but they do 12024139Sjoerg not reveal identifying information should the file's contents be 12124139Sjoerg disclosed. This option will not modify existing hashed hostnames 12224139Sjoerg and is therefore safe to use on files that mix hashed and non- 12324139Sjoerg hashed names. 12424139Sjoerg 12524139Sjoerg -i This option will read an unencrypted private (or public) key file 12624139Sjoerg in SSH2-compatible format and print an OpenSSH compatible private 12724139Sjoerg (or public) key to stdout. ssh-keygen also reads the RFC 4716 12824139Sjoerg SSH Public Key File Format. This option allows importing keys 12924139Sjoerg from several commercial SSH implementations. 13024139Sjoerg 13124139Sjoerg -l Show fingerprint of specified public key file. Private RSA1 keys 13224139Sjoerg are also supported. For RSA and DSA keys ssh-keygen tries to 13324139Sjoerg find the matching public key file and prints its fingerprint. 13424139Sjoerg 13524139Sjoerg -M memory 13624139Sjoerg Specify the amount of memory to use (in megabytes) when generat- 13724139Sjoerg ing candidate moduli for DH-GEX. 13824139Sjoerg 13924139Sjoerg -N new_passphrase 14024139Sjoerg Provides the new passphrase. 14124139Sjoerg 14224139Sjoerg -P passphrase 14389750Sdwmalone Provides the (old) passphrase. 14489750Sdwmalone 14589750Sdwmalone -p Requests changing the passphrase of a private key file instead of 14689750Sdwmalone creating a new private key. The program will prompt for the file 14789750Sdwmalone containing the private key, for the old passphrase, and twice for 14889750Sdwmalone the new passphrase. 14989750Sdwmalone 15089750Sdwmalone -q Silence ssh-keygen. Used by /etc/rc when creating a new key. 15189750Sdwmalone 15224139Sjoerg -R hostname 15324139Sjoerg Removes all keys belonging to hostname from a known_hosts file. 15424139Sjoerg This option is useful to delete hashed hosts (see the -H option 15524139Sjoerg above). 15624139Sjoerg 15724139Sjoerg -r hostname 15824139Sjoerg Print the SSHFP fingerprint resource record named hostname for 15924139Sjoerg the specified public key file. 16024139Sjoerg 16124139Sjoerg -S start 16224139Sjoerg Specify start point (in hex) when generating candidate moduli for 16324139Sjoerg DH-GEX. 16424139Sjoerg 16524139Sjoerg -T output_file 16624139Sjoerg Test DH group exchange candidate primes (generated using the -G 16724139Sjoerg option) for safety. 16824139Sjoerg 16924139Sjoerg -t type 17024139Sjoerg Specifies the type of key to create. The possible values are 17124139Sjoerg ``rsa1'' for protocol version 1 and ``rsa'' or ``dsa'' for proto- 17224139Sjoerg col version 2. 17324139Sjoerg 17424139Sjoerg -U reader 17524139Sjoerg Upload an existing RSA private key into the smartcard in reader. 17624139Sjoerg 17724139Sjoerg -v Verbose mode. Causes ssh-keygen to print debugging messages 17824139Sjoerg about its progress. This is helpful for debugging moduli genera- 17924139Sjoerg tion. Multiple -v options increase the verbosity. The maximum 18024139Sjoerg is 3. 18124139Sjoerg 18224139Sjoerg -W generator 18324139Sjoerg Specify desired generator when testing candidate moduli for DH- 18424139Sjoerg GEX. 18524139Sjoerg 18624139Sjoerg -y This option will read a private OpenSSH format file and print an 18724139Sjoerg OpenSSH public key to stdout. 18824139Sjoerg 18924139SjoergMODULI GENERATION 19024139Sjoerg ssh-keygen may be used to generate groups for the Diffie-Hellman Group 19124139Sjoerg Exchange (DH-GEX) protocol. Generating these groups is a two-step pro- 19224139Sjoerg cess: first, candidate primes are generated using a fast, but memory in- 19324139Sjoerg tensive process. These candidate primes are then tested for suitability 19424139Sjoerg (a CPU-intensive process). 19524139Sjoerg 19624139Sjoerg Generation of primes is performed using the -G option. The desired 19724139Sjoerg length of the primes may be specified by the -b option. For example: 19824139Sjoerg 19924139Sjoerg # ssh-keygen -G moduli-2048.candidates -b 2048 20024139Sjoerg 20124139Sjoerg By default, the search for primes begins at a random point in the desired 20224139Sjoerg length range. This may be overridden using the -S option, which speci- 20324139Sjoerg fies a different start point (in hex). 20424139Sjoerg 20524139Sjoerg Once a set of candidates have been generated, they must be tested for 20624139Sjoerg suitability. This may be performed using the -T option. In this mode 20724139Sjoerg ssh-keygen will read candidates from standard input (or a file specified 20824139Sjoerg using the -f option). For example: 20989750Sdwmalone 21089750Sdwmalone # ssh-keygen -T moduli-2048 -f moduli-2048.candidates 21189750Sdwmalone 21224139Sjoerg By default, each candidate will be subjected to 100 primality tests. 21324139Sjoerg This may be overridden using the -a option. The DH generator value will 21489750Sdwmalone be chosen automatically for the prime under consideration. If a specific 21589750Sdwmalone generator is desired, it may be requested using the -W option. Valid 21689750Sdwmalone generator values are 2, 3, and 5. 21789750Sdwmalone 21889750Sdwmalone Screened DH groups may be installed in /etc/moduli. It is important that 21924139Sjoerg this file contains moduli of a range of bit lengths and that both ends of 22089750Sdwmalone a connection share common moduli. 22189750Sdwmalone 22289750SdwmaloneFILES 22389750Sdwmalone ~/.ssh/identity 22489750Sdwmalone Contains the protocol version 1 RSA authentication identity of 22589750Sdwmalone the user. This file should not be readable by anyone but the us- 22689750Sdwmalone er. It is possible to specify a passphrase when generating the 22724139Sjoerg key; that passphrase will be used to encrypt the private part of 22824139Sjoerg this file using 3DES. This file is not automatically accessed by 22989750Sdwmalone ssh-keygen but it is offered as the default file for the private 23024139Sjoerg key. ssh(1) will read this file when a login attempt is made. 23189750Sdwmalone 23289750Sdwmalone ~/.ssh/identity.pub 23389750Sdwmalone Contains the protocol version 1 RSA public key for authentica- 23424139Sjoerg tion. The contents of this file should be added to 23524139Sjoerg ~/.ssh/authorized_keys on all machines where the user wishes to 23624139Sjoerg log in using RSA authentication. There is no need to keep the 23724139Sjoerg contents of this file secret. 23889750Sdwmalone 23924139Sjoerg ~/.ssh/id_dsa 24024139Sjoerg Contains the protocol version 2 DSA authentication identity of 24124139Sjoerg the user. This file should not be readable by anyone but the us- 24224139Sjoerg er. It is possible to specify a passphrase when generating the 24324139Sjoerg key; that passphrase will be used to encrypt the private part of 24424139Sjoerg this file using 3DES. This file is not automatically accessed by 24524139Sjoerg ssh-keygen but it is offered as the default file for the private 24624139Sjoerg key. ssh(1) will read this file when a login attempt is made. 24789750Sdwmalone 24824139Sjoerg ~/.ssh/id_dsa.pub 24924139Sjoerg Contains the protocol version 2 DSA public key for authentica- 25024139Sjoerg tion. The contents of this file should be added to 25124139Sjoerg ~/.ssh/authorized_keys on all machines where the user wishes to 25224139Sjoerg log in using public key authentication. There is no need to keep 25324139Sjoerg the contents of this file secret. 25424139Sjoerg 25524139Sjoerg ~/.ssh/id_rsa 25624139Sjoerg Contains the protocol version 2 RSA authentication identity of 25724139Sjoerg the user. This file should not be readable by anyone but the us- 25824139Sjoerg er. It is possible to specify a passphrase when generating the 25924139Sjoerg key; that passphrase will be used to encrypt the private part of 26024139Sjoerg this file using 3DES. This file is not automatically accessed by 26124139Sjoerg ssh-keygen but it is offered as the default file for the private 26224139Sjoerg key. ssh(1) will read this file when a login attempt is made. 26324139Sjoerg 26424139Sjoerg ~/.ssh/id_rsa.pub 265 Contains the protocol version 2 RSA public key for authentica- 266 tion. The contents of this file should be added to 267 ~/.ssh/authorized_keys on all machines where the user wishes to 268 log in using public key authentication. There is no need to keep 269 the contents of this file secret. 270 271 /etc/moduli 272 Contains Diffie-Hellman groups used for DH-GEX. The file format 273 is described in moduli(5). 274 275SEE ALSO 276 ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8) 277 278 The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006. 279 280AUTHORS 281 OpenSSH is a derivative of the original and free ssh 1.2.12 release by 282 Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo 283 de Raadt and Dug Song removed many bugs, re-added newer features and 284 created OpenSSH. Markus Friedl contributed the support for SSH protocol 285 versions 1.5 and 2.0. 286 287OpenBSD 4.2 June 5, 2007 5 288