ssh-keygen.0 revision 180740
12089SsosSSH-KEYGEN(1) OpenBSD Reference Manual SSH-KEYGEN(1) 216565Ssos 32089SsosNAME 42089Ssos ssh-keygen - authentication key generation, management and conversion 52089Ssos 62089SsosSYNOPSIS 72089Ssos ssh-keygen [-q] [-b bits] -t type [-N new_passphrase] [-C comment] 82089Ssos [-f output_keyfile] 95994Ssos ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile] 105994Ssos ssh-keygen -i [-f input_keyfile] 112089Ssos ssh-keygen -e [-f input_keyfile] 122089Ssos ssh-keygen -y [-f input_keyfile] 132089Ssos ssh-keygen -c [-P passphrase] [-C comment] [-f keyfile] 142089Ssos ssh-keygen -l [-f input_keyfile] 152089Ssos ssh-keygen -B [-f input_keyfile] 162089Ssos ssh-keygen -D reader 172089Ssos ssh-keygen -F hostname [-f known_hosts_file] 182089Ssos ssh-keygen -H [-f known_hosts_file] 192089Ssos ssh-keygen -R hostname [-f known_hosts_file] 202089Ssos ssh-keygen -U reader [-f input_keyfile] 212089Ssos ssh-keygen -r hostname [-f input_keyfile] [-g] 222089Ssos ssh-keygen -G output_file [-v] [-b bits] [-M memory] [-S start_point] 232089Ssos ssh-keygen -T output_file -f input_file [-v] [-a num_trials] [-W 242089Ssos generator] 252089Ssos 262089SsosDESCRIPTION 272089Ssos ssh-keygen generates, manages and converts authentication keys for 282089Ssos ssh(1). ssh-keygen can create RSA keys for use by SSH protocol version 1 2930764Scharnier and RSA or DSA keys for use by SSH protocol version 2. The type of key 3030764Scharnier to be generated is specified with the -t option. If invoked without any 3139592Syokota arguments, ssh-keygen will generate an RSA key for use in SSH protocol 2 3230764Scharnier connections. 3330764Scharnier 342089Ssos ssh-keygen is also used to generate groups for use in Diffie-Hellman 3530764Scharnier group exchange (DH-GEX). See the MODULI GENERATION section for details. 362089Ssos 3723457Sbrian Normally each user wishing to use SSH with RSA or DSA authentication runs 3830764Scharnier this once to create the authentication key in ~/.ssh/identity, 3923702Speter ~/.ssh/id_dsa or ~/.ssh/id_rsa. Additionally, the system administrator 402089Ssos may use this to generate host keys, as seen in /etc/rc. 412089Ssos 422089Ssos Normally this program generates the key and asks for a file in which to 4323457Sbrian store the private key. The public key is stored in a file with the same 442089Ssos name but ``.pub'' appended. The program also asks for a passphrase. The 452089Ssos passphrase may be empty to indicate no passphrase (host keys must have an 462089Ssos empty passphrase), or it may be a string of arbitrary length. A 472089Ssos passphrase is similar to a password, except it can be a phrase with a se- 482089Ssos ries of words, punctuation, numbers, whitespace, or any string of charac- 492089Ssos ters you want. Good passphrases are 10-30 characters long, are not sim- 506628Ssos ple sentences or otherwise easily guessable (English prose has only 1-2 512089Ssos bits of entropy per character, and provides very bad passphrases), and 526047Ssos contain a mix of upper and lowercase letters, numbers, and non-alphanu- 532089Ssos meric characters. The passphrase can be changed later by using the -p 542089Ssos option. 552089Ssos 562089Ssos There is no way to recover a lost passphrase. If the passphrase is lost 5730764Scharnier or forgotten, a new key must be generated and copied to the corresponding 586628Ssos public key to other machines. 596628Ssos 6030764Scharnier For RSA1 keys, there is also a comment field in the key file that is only 6130764Scharnier for convenience to the user to help identify the key. The comment can 6239361Sabial tell what the key is for, or whatever is useful. The comment is initial- 6339361Sabial ized to ``user@host'' when the key is created, but can be changed using 6430764Scharnier the -c option. 656628Ssos 666628Ssos After a key is generated, instructions below detail where the keys should 672089Ssos be placed to be activated. 682089Ssos 692089Ssos The options are as follows: 702089Ssos 712089Ssos -a trials 7230764Scharnier Specifies the number of primality tests to perform when screening 732089Ssos DH-GEX candidates using the -T command. 742089Ssos 752089Ssos -B Show the bubblebabble digest of specified private or public key 762089Ssos file. 772089Ssos 782089Ssos -b bits 796628Ssos Specifies the number of bits in the key to create. For RSA keys, 806628Ssos the minimum size is 768 bits and the default is 2048 bits. Gen- 816628Ssos erally, 2048 bits is considered sufficient. DSA keys must be ex- 822089Ssos actly 1024 bits as specified by FIPS 186-2. 832089Ssos 842089Ssos -C comment 852089Ssos Provides a new comment. 862089Ssos 872089Ssos -c Requests changing the comment in the private and public key 882089Ssos files. This operation is only supported for RSA1 keys. The pro- 892089Ssos gram will prompt for the file containing the private keys, for 902089Ssos the passphrase if the key has one, and for the new comment. 912089Ssos 922089Ssos -D reader 932089Ssos Download the RSA public key stored in the smartcard in reader. 942089Ssos 952089Ssos -e This option will read a private or public OpenSSH key file and 962089Ssos print the key in RFC 4716 SSH Public Key File Format to stdout. 972089Ssos This option allows exporting keys for use by several commercial 982089Ssos SSH implementations. 992089Ssos 1002089Ssos -F hostname 1012089Ssos Search for the specified hostname in a known_hosts file, listing 1022089Ssos any occurrences found. This option is useful to find hashed host 1032089Ssos names or addresses and may also be used in conjunction with the 10423457Sbrian -H option to print found keys in a hashed format. 1052089Ssos 1062089Ssos -f filename 1072089Ssos Specifies the filename of the key file. 1082089Ssos 1092089Ssos -G output_file 1102089Ssos Generate candidate primes for DH-GEX. These primes must be 1112089Ssos screened for safety (using the -T option) before use. 1122089Ssos 11323457Sbrian -g Use generic DNS format when printing fingerprint resource records 11423457Sbrian using the -r command. 1152089Ssos 1162089Ssos -H Hash a known_hosts file. This replaces all hostnames and ad- 1172089Ssos dresses with hashed representations within the specified file; 11830764Scharnier the original content is moved to a file with a .old suffix. 1192089Ssos These hashes may be used normally by ssh and sshd, but they do 1202089Ssos not reveal identifying information should the file's contents be 1212089Ssos disclosed. This option will not modify existing hashed hostnames 12223457Sbrian and is therefore safe to use on files that mix hashed and non- 1232089Ssos hashed names. 1242089Ssos 12530764Scharnier -i This option will read an unencrypted private (or public) key file 12623457Sbrian in SSH2-compatible format and print an OpenSSH compatible private 1272089Ssos (or public) key to stdout. ssh-keygen also reads the RFC 4716 1282089Ssos SSH Public Key File Format. This option allows importing keys 1292089Ssos from several commercial SSH implementations. 1302089Ssos 13130764Scharnier -l Show fingerprint of specified public key file. Private RSA1 keys 13223457Sbrian are also supported. For RSA and DSA keys ssh-keygen tries to 1332089Ssos find the matching public key file and prints its fingerprint. 1342089Ssos 1352089Ssos -M memory 1362089Ssos Specify the amount of memory to use (in megabytes) when generat- 1372089Ssos ing candidate moduli for DH-GEX. 1386628Ssos 1392089Ssos -N new_passphrase 1402089Ssos Provides the new passphrase. 1412089Ssos 1422089Ssos -P passphrase 1432089Ssos Provides the (old) passphrase. 14430764Scharnier 1452089Ssos -p Requests changing the passphrase of a private key file instead of 1462089Ssos creating a new private key. The program will prompt for the file 1472089Ssos containing the private key, for the old passphrase, and twice for 1482089Ssos the new passphrase. 1492089Ssos 1502089Ssos -q Silence ssh-keygen. Used by /etc/rc when creating a new key. 1512089Ssos 1522089Ssos -R hostname 1532089Ssos Removes all keys belonging to hostname from a known_hosts file. 15430764Scharnier This option is useful to delete hashed hosts (see the -H option 1552089Ssos above). 1562089Ssos 1572089Ssos -r hostname 1582089Ssos Print the SSHFP fingerprint resource record named hostname for 1592089Ssos the specified public key file. 1602089Ssos 1618857Srgrimes -S start 1622089Ssos Specify start point (in hex) when generating candidate moduli for 1632089Ssos DH-GEX. 1642089Ssos 1652089Ssos -T output_file 1662089Ssos Test DH group exchange candidate primes (generated using the -G 1672089Ssos option) for safety. 1682089Ssos 1698857Srgrimes -t type 1702089Ssos Specifies the type of key to create. The possible values are 1712089Ssos ``rsa1'' for protocol version 1 and ``rsa'' or ``dsa'' for proto- 17223457Sbrian col version 2. 17337636Sbde 17437636Sbde -U reader 1752089Ssos Upload an existing RSA private key into the smartcard in reader. 1762089Ssos 1772089Ssos -v Verbose mode. Causes ssh-keygen to print debugging messages 1782089Ssos about its progress. This is helpful for debugging moduli genera- 1792089Ssos tion. Multiple -v options increase the verbosity. The maximum 1802089Ssos is 3. 18123457Sbrian 18223457Sbrian -W generator 1832089Ssos Specify desired generator when testing candidate moduli for DH- 1842089Ssos GEX. 1852089Ssos 18630764Scharnier -y This option will read a private OpenSSH format file and print an 1872089Ssos OpenSSH public key to stdout. 1882089Ssos 1892089SsosMODULI GENERATION 1902089Ssos ssh-keygen may be used to generate groups for the Diffie-Hellman Group 1912089Ssos Exchange (DH-GEX) protocol. Generating these groups is a two-step pro- 1922089Ssos cess: first, candidate primes are generated using a fast, but memory in- 1932089Ssos tensive process. These candidate primes are then tested for suitability 1942089Ssos (a CPU-intensive process). 1952089Ssos 1962089Ssos Generation of primes is performed using the -G option. The desired 1972089Ssos length of the primes may be specified by the -b option. For example: 1982089Ssos 1992089Ssos # ssh-keygen -G moduli-2048.candidates -b 2048 2002089Ssos 2012089Ssos By default, the search for primes begins at a random point in the desired 20230764Scharnier length range. This may be overridden using the -S option, which speci- 20323457Sbrian fies a different start point (in hex). 2042089Ssos 2052089Ssos Once a set of candidates have been generated, they must be tested for 2062089Ssos suitability. This may be performed using the -T option. In this mode 2072089Ssos ssh-keygen will read candidates from standard input (or a file specified 2082089Ssos using the -f option). For example: 2092089Ssos 21030764Scharnier # ssh-keygen -T moduli-2048 -f moduli-2048.candidates 21123457Sbrian 2122089Ssos By default, each candidate will be subjected to 100 primality tests. 2132089Ssos This may be overridden using the -a option. The DH generator value will 2142089Ssos be chosen automatically for the prime under consideration. If a specific 2152089Ssos generator is desired, it may be requested using the -W option. Valid 2162089Ssos generator values are 2, 3, and 5. 21730764Scharnier 21823457Sbrian Screened DH groups may be installed in /etc/moduli. It is important that 2192089Ssos this file contains moduli of a range of bit lengths and that both ends of 2202089Ssos a connection share common moduli. 2212089Ssos 2222089SsosFILES 2232089Ssos ~/.ssh/identity 2242089Ssos Contains the protocol version 1 RSA authentication identity of 2252089Ssos the user. This file should not be readable by anyone but the us- 2262089Ssos er. It is possible to specify a passphrase when generating the 2272089Ssos key; that passphrase will be used to encrypt the private part of 2282089Ssos this file using 3DES. This file is not automatically accessed by 2292089Ssos ssh-keygen but it is offered as the default file for the private 2302089Ssos key. ssh(1) will read this file when a login attempt is made. 2312089Ssos 23230764Scharnier ~/.ssh/identity.pub 2332089Ssos Contains the protocol version 1 RSA public key for authentica- 2342089Ssos tion. The contents of this file should be added to 2352089Ssos ~/.ssh/authorized_keys on all machines where the user wishes to 2362089Ssos log in using RSA authentication. There is no need to keep the 23730764Scharnier contents of this file secret. 2382089Ssos 2392089Ssos ~/.ssh/id_dsa 2402089Ssos Contains the protocol version 2 DSA authentication identity of 2415536Ssos the user. This file should not be readable by anyone but the us- 2422089Ssos er. It is possible to specify a passphrase when generating the 2435536Ssos key; that passphrase will be used to encrypt the private part of 2442089Ssos this file using 3DES. This file is not automatically accessed by 2456230Ssos ssh-keygen but it is offered as the default file for the private 2466230Ssos key. ssh(1) will read this file when a login attempt is made. 2476230Ssos 2485536Ssos ~/.ssh/id_dsa.pub 2496230Ssos Contains the protocol version 2 DSA public key for authentica- 2506230Ssos tion. The contents of this file should be added to 2515536Ssos ~/.ssh/authorized_keys on all machines where the user wishes to 25230764Scharnier log in using public key authentication. There is no need to keep 2532089Ssos the contents of this file secret. 2542089Ssos 2555536Ssos ~/.ssh/id_rsa 2562089Ssos Contains the protocol version 2 RSA authentication identity of 2572089Ssos the user. This file should not be readable by anyone but the us- 25823457Sbrian er. It is possible to specify a passphrase when generating the 2592089Ssos key; that passphrase will be used to encrypt the private part of 2602089Ssos this file using 3DES. This file is not automatically accessed by 26139592Syokota ssh-keygen but it is offered as the default file for the private 26239592Syokota key. ssh(1) will read this file when a login attempt is made. 26339592Syokota 26439592Syokota ~/.ssh/id_rsa.pub 26539592Syokota Contains the protocol version 2 RSA public key for authentica- 26639592Syokota tion. The contents of this file should be added to 26739592Syokota ~/.ssh/authorized_keys on all machines where the user wishes to 26839592Syokota log in using public key authentication. There is no need to keep 26939592Syokota the contents of this file secret. 27039592Syokota 27139592Syokota /etc/moduli 27239592Syokota Contains Diffie-Hellman groups used for DH-GEX. The file format 27339592Syokota is described in moduli(5). 27439592Syokota 27539592SyokotaSEE ALSO 27639592Syokota ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8) 27739592Syokota 27839592Syokota The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006. 27939592Syokota 28039592SyokotaAUTHORS 28139592Syokota OpenSSH is a derivative of the original and free ssh 1.2.12 release by 28239592Syokota Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo 28339592Syokota de Raadt and Dug Song removed many bugs, re-added newer features and 28439592Syokota created OpenSSH. Markus Friedl contributed the support for SSH protocol 28539592Syokota versions 1.5 and 2.0. 28639592Syokota 28739592SyokotaOpenBSD 4.1 September 25, 1999 5 28839592Syokota