ssh-keygen.0 revision 218767
123353SdfrSSH-KEYGEN(1) OpenBSD Reference Manual SSH-KEYGEN(1) 223353Sdfr 323353SdfrNAME 423353Sdfr ssh-keygen - authentication key generation, management and conversion 523353Sdfr 623353SdfrSYNOPSIS 723353Sdfr ssh-keygen [-q] [-b bits] -t type [-N new_passphrase] [-C comment] 823353Sdfr [-f output_keyfile] 923353Sdfr ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile] 1023353Sdfr ssh-keygen -i [-m key_format] [-f input_keyfile] 1123353Sdfr ssh-keygen -e [-m key_format] [-f input_keyfile] 1223353Sdfr ssh-keygen -y [-f input_keyfile] 1323353Sdfr ssh-keygen -c [-P passphrase] [-C comment] [-f keyfile] 1423353Sdfr ssh-keygen -l [-f input_keyfile] 1523353Sdfr ssh-keygen -B [-f input_keyfile] 1623353Sdfr ssh-keygen -D pkcs11 1723353Sdfr ssh-keygen -F hostname [-f known_hosts_file] [-l] 1823353Sdfr ssh-keygen -H [-f known_hosts_file] 1923353Sdfr ssh-keygen -R hostname [-f known_hosts_file] 2023353Sdfr ssh-keygen -r hostname [-f input_keyfile] [-g] 2123353Sdfr ssh-keygen -G output_file [-v] [-b bits] [-M memory] [-S start_point] 2223353Sdfr ssh-keygen -T output_file -f input_file [-v] [-a num_trials] 2323353Sdfr [-W generator] 2423353Sdfr ssh-keygen -s ca_key -I certificate_identity [-h] [-n principals] 2523353Sdfr [-O option] [-V validity_interval] [-z serial_number] file ... 2623353Sdfr ssh-keygen -L [-f input_keyfile] 2723353Sdfr 2823353SdfrDESCRIPTION 2950476Speter ssh-keygen generates, manages and converts authentication keys for 3023353Sdfr ssh(1). ssh-keygen can create RSA keys for use by SSH protocol version 1 3123353Sdfr and DSA, ECDSA or RSA keys for use by SSH protocol version 2. The type 32206622Suqs of key to be generated is specified with the -t option. If invoked 3323353Sdfr without any arguments, ssh-keygen will generate an RSA key for use in SSH 3423353Sdfr protocol 2 connections. 3523353Sdfr 3623353Sdfr ssh-keygen is also used to generate groups for use in Diffie-Hellman 3723353Sdfr group exchange (DH-GEX). See the MODULI GENERATION section for details. 3884306Sru 3984306Sru Normally each user wishing to use SSH with public key authentication runs 4023353Sdfr this once to create the authentication key in ~/.ssh/identity, 4188509Sdavidc ~/.ssh/id_ecdsa, ~/.ssh/id_dsa or ~/.ssh/id_rsa. Additionally, the 4223353Sdfr system administrator may use this to generate host keys, as seen in 4323353Sdfr /etc/rc. 4423353Sdfr 45115440Shmp Normally this program generates the key and asks for a file in which to 46140932Sru store the private key. The public key is stored in a file with the same 47115440Shmp name but ``.pub'' appended. The program also asks for a passphrase. The 48140932Sru passphrase may be empty to indicate no passphrase (host keys must have an 4923353Sdfr empty passphrase), or it may be a string of arbitrary length. A 5023353Sdfr passphrase is similar to a password, except it can be a phrase with a 51121384Shmp series of words, punctuation, numbers, whitespace, or any string of 52121384Shmp characters you want. Good passphrases are 10-30 characters long, are not 5323353Sdfr simple sentences or otherwise easily guessable (English prose has only 1- 54121384Shmp 2 bits of entropy per character, and provides very bad passphrases), and 55121384Shmp contain a mix of upper and lowercase letters, numbers, and non- 5623353Sdfr alphanumeric characters. The passphrase can be changed later by using 5723353Sdfr the -p option. 5823353Sdfr 5923353Sdfr There is no way to recover a lost passphrase. If the passphrase is lost 6023353Sdfr or forgotten, a new key must be generated and copied to the corresponding 6123353Sdfr public key to other machines. 62108257Sru 6323353Sdfr For RSA1 keys, there is also a comment field in the key file that is only 6423353Sdfr for convenience to the user to help identify the key. The comment can 6523353Sdfr tell what the key is for, or whatever is useful. The comment is 6623353Sdfr initialized to ``user@host'' when the key is created, but can be changed 6723353Sdfr using the -c option. 6823353Sdfr 6923353Sdfr After a key is generated, instructions below detail where the keys should 70147647Shmp be placed to be activated. 7134504Scharnier 72 The options are as follows: 73 74 -a trials 75 Specifies the number of primality tests to perform when screening 76 DH-GEX candidates using the -T command. 77 78 -B Show the bubblebabble digest of specified private or public key 79 file. 80 81 -b bits 82 Specifies the number of bits in the key to create. For RSA keys, 83 the minimum size is 768 bits and the default is 2048 bits. 84 Generally, 2048 bits is considered sufficient. DSA keys must be 85 exactly 1024 bits as specified by FIPS 186-2. 86 87 -C comment 88 Provides a new comment. 89 90 -c Requests changing the comment in the private and public key 91 files. This operation is only supported for RSA1 keys. The 92 program will prompt for the file containing the private keys, for 93 the passphrase if the key has one, and for the new comment. 94 95 -D pkcs11 96 Download the RSA public keys provided by the PKCS#11 shared 97 library pkcs11. When used in combination with -s, this option 98 indicates that a CA key resides in a PKCS#11 token (see the 99 CERTIFICATES section for details). 100 101 -e This option will read a private or public OpenSSH key file and 102 print to stdout the key in one of the formats specified by the -m 103 option. The default export format is ``RFC4716''. This option 104 allows exporting OpenSSH keys for use by other programs, 105 including several commercial SSH implementations. 106 107 -F hostname 108 Search for the specified hostname in a known_hosts file, listing 109 any occurrences found. This option is useful to find hashed host 110 names or addresses and may also be used in conjunction with the 111 -H option to print found keys in a hashed format. 112 113 -f filename 114 Specifies the filename of the key file. 115 116 -G output_file 117 Generate candidate primes for DH-GEX. These primes must be 118 screened for safety (using the -T option) before use. 119 120 -g Use generic DNS format when printing fingerprint resource records 121 using the -r command. 122 123 -H Hash a known_hosts file. This replaces all hostnames and 124 addresses with hashed representations within the specified file; 125 the original content is moved to a file with a .old suffix. 126 These hashes may be used normally by ssh and sshd, but they do 127 not reveal identifying information should the file's contents be 128 disclosed. This option will not modify existing hashed hostnames 129 and is therefore safe to use on files that mix hashed and non- 130 hashed names. 131 132 -h When signing a key, create a host certificate instead of a user 133 certificate. Please see the CERTIFICATES section for details. 134 135 -I certificate_identity 136 Specify the key identity when signing a public key. Please see 137 the CERTIFICATES section for details. 138 139 -i This option will read an unencrypted private (or public) key file 140 in the format specified by the -m option and print an OpenSSH 141 compatible private (or public) key to stdout. This option allows 142 importing keys from other software, including several commercial 143 SSH implementations. The default import format is ``RFC4716''. 144 145 -L Prints the contents of a certificate. 146 147 -l Show fingerprint of specified public key file. Private RSA1 keys 148 are also supported. For RSA and DSA keys ssh-keygen tries to 149 find the matching public key file and prints its fingerprint. If 150 combined with -v, an ASCII art representation of the key is 151 supplied with the fingerprint. 152 153 -M memory 154 Specify the amount of memory to use (in megabytes) when 155 generating candidate moduli for DH-GEX. 156 157 -m key_format 158 Specify a key format for the -i (import) or -e (export) 159 conversion options. The supported key formats are: ``RFC4716'' 160 (RFC 4716/SSH2 public or private key), ``PKCS8'' (PEM PKCS8 161 public key) or ``PEM'' (PEM public key). The default conversion 162 format is ``RFC4716''. 163 164 -N new_passphrase 165 Provides the new passphrase. 166 167 -n principals 168 Specify one or more principals (user or host names) to be 169 included in a certificate when signing a key. Multiple 170 principals may be specified, separated by commas. Please see the 171 CERTIFICATES section for details. 172 173 -O option 174 Specify a certificate option when signing a key. This option may 175 be specified multiple times. Please see the CERTIFICATES section 176 for details. The options that are valid for user certificates 177 are: 178 179 clear Clear all enabled permissions. This is useful for 180 clearing the default set of permissions so permissions 181 may be added individually. 182 183 force-command=command 184 Forces the execution of command instead of any shell or 185 command specified by the user when the certificate is 186 used for authentication. 187 188 no-agent-forwarding 189 Disable ssh-agent(1) forwarding (permitted by default). 190 191 no-port-forwarding 192 Disable port forwarding (permitted by default). 193 194 no-pty Disable PTY allocation (permitted by default). 195 196 no-user-rc 197 Disable execution of ~/.ssh/rc by sshd(8) (permitted by 198 default). 199 200 no-x11-forwarding 201 Disable X11 forwarding (permitted by default). 202 203 permit-agent-forwarding 204 Allows ssh-agent(1) forwarding. 205 206 permit-port-forwarding 207 Allows port forwarding. 208 209 permit-pty 210 Allows PTY allocation. 211 212 permit-user-rc 213 Allows execution of ~/.ssh/rc by sshd(8). 214 215 permit-x11-forwarding 216 Allows X11 forwarding. 217 218 source-address=address_list 219 Restrict the source addresses from which the certificate 220 is considered valid. The address_list is a comma- 221 separated list of one or more address/netmask pairs in 222 CIDR format. 223 224 At present, no options are valid for host keys. 225 226 -P passphrase 227 Provides the (old) passphrase. 228 229 -p Requests changing the passphrase of a private key file instead of 230 creating a new private key. The program will prompt for the file 231 containing the private key, for the old passphrase, and twice for 232 the new passphrase. 233 234 -q Silence ssh-keygen. Used by /etc/rc when creating a new key. 235 236 -R hostname 237 Removes all keys belonging to hostname from a known_hosts file. 238 This option is useful to delete hashed hosts (see the -H option 239 above). 240 241 -r hostname 242 Print the SSHFP fingerprint resource record named hostname for 243 the specified public key file. 244 245 -S start 246 Specify start point (in hex) when generating candidate moduli for 247 DH-GEX. 248 249 -s ca_key 250 Certify (sign) a public key using the specified CA key. Please 251 see the CERTIFICATES section for details. 252 253 -T output_file 254 Test DH group exchange candidate primes (generated using the -G 255 option) for safety. 256 257 -t type 258 Specifies the type of key to create. The possible values are 259 ``rsa1'' for protocol version 1 and ``dsa'', ``ecdsa'' or ``rsa'' 260 for protocol version 2. 261 262 -V validity_interval 263 Specify a validity interval when signing a certificate. A 264 validity interval may consist of a single time, indicating that 265 the certificate is valid beginning now and expiring at that time, 266 or may consist of two times separated by a colon to indicate an 267 explicit time interval. The start time may be specified as a 268 date in YYYYMMDD format, a time in YYYYMMDDHHMMSS format or a 269 relative time (to the current time) consisting of a minus sign 270 followed by a relative time in the format described in the TIME 271 FORMATS section of sshd_config(5). The end time may be specified 272 as a YYYYMMDD date, a YYYYMMDDHHMMSS time or a relative time 273 starting with a plus character. 274 275 For example: ``+52w1d'' (valid from now to 52 weeks and one day 276 from now), ``-4w:+4w'' (valid from four weeks ago to four weeks 277 from now), ``20100101123000:20110101123000'' (valid from 12:30 278 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011), 279 ``-1d:20110101'' (valid from yesterday to midnight, January 1st, 280 2011). 281 282 -v Verbose mode. Causes ssh-keygen to print debugging messages 283 about its progress. This is helpful for debugging moduli 284 generation. Multiple -v options increase the verbosity. The 285 maximum is 3. 286 287 -W generator 288 Specify desired generator when testing candidate moduli for DH- 289 GEX. 290 291 -y This option will read a private OpenSSH format file and print an 292 OpenSSH public key to stdout. 293 294 -z serial_number 295 Specifies a serial number to be embedded in the certificate to 296 distinguish this certificate from others from the same CA. The 297 default serial number is zero. 298 299MODULI GENERATION 300 ssh-keygen may be used to generate groups for the Diffie-Hellman Group 301 Exchange (DH-GEX) protocol. Generating these groups is a two-step 302 process: first, candidate primes are generated using a fast, but memory 303 intensive process. These candidate primes are then tested for 304 suitability (a CPU-intensive process). 305 306 Generation of primes is performed using the -G option. The desired 307 length of the primes may be specified by the -b option. For example: 308 309 # ssh-keygen -G moduli-2048.candidates -b 2048 310 311 By default, the search for primes begins at a random point in the desired 312 length range. This may be overridden using the -S option, which 313 specifies a different start point (in hex). 314 315 Once a set of candidates have been generated, they must be tested for 316 suitability. This may be performed using the -T option. In this mode 317 ssh-keygen will read candidates from standard input (or a file specified 318 using the -f option). For example: 319 320 # ssh-keygen -T moduli-2048 -f moduli-2048.candidates 321 322 By default, each candidate will be subjected to 100 primality tests. 323 This may be overridden using the -a option. The DH generator value will 324 be chosen automatically for the prime under consideration. If a specific 325 generator is desired, it may be requested using the -W option. Valid 326 generator values are 2, 3, and 5. 327 328 Screened DH groups may be installed in /etc/moduli. It is important that 329 this file contains moduli of a range of bit lengths and that both ends of 330 a connection share common moduli. 331 332CERTIFICATES 333 ssh-keygen supports signing of keys to produce certificates that may be 334 used for user or host authentication. Certificates consist of a public 335 key, some identity information, zero or more principal (user or host) 336 names and a set of options that are signed by a Certification Authority 337 (CA) key. Clients or servers may then trust only the CA key and verify 338 its signature on a certificate rather than trusting many user/host keys. 339 Note that OpenSSH certificates are a different, and much simpler, format 340 to the X.509 certificates used in ssl(8). 341 342 ssh-keygen supports two types of certificates: user and host. User 343 certificates authenticate users to servers, whereas host certificates 344 authenticate server hosts to users. To generate a user certificate: 345 346 $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub 347 348 The resultant certificate will be placed in /path/to/user_key-cert.pub. 349 A host certificate requires the -h option: 350 351 $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub 352 353 The host certificate will be output to /path/to/host_key-cert.pub. 354 355 It is possible to sign using a CA key stored in a PKCS#11 token by 356 providing the token library using -D and identifying the CA key by 357 providing its public half as an argument to -s: 358 359 $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub 360 361 In all cases, key_id is a "key identifier" that is logged by the server 362 when the certificate is used for authentication. 363 364 Certificates may be limited to be valid for a set of principal 365 (user/host) names. By default, generated certificates are valid for all 366 users or hosts. To generate a certificate for a specified set of 367 principals: 368 369 $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub 370 $ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub 371 372 Additional limitations on the validity and use of user certificates may 373 be specified through certificate options. A certificate option may 374 disable features of the SSH session, may be valid only when presented 375 from particular source addresses or may force the use of a specific 376 command. For a list of valid certificate options, see the documentation 377 for the -O option above. 378 379 Finally, certificates may be defined with a validity lifetime. The -V 380 option allows specification of certificate start and end times. A 381 certificate that is presented at a time outside this range will not be 382 considered valid. By default, certificates have a maximum validity 383 interval. 384 385 For certificates to be used for user or host authentication, the CA 386 public key must be trusted by sshd(8) or ssh(1). Please refer to those 387 manual pages for details. 388 389FILES 390 ~/.ssh/identity 391 Contains the protocol version 1 RSA authentication identity of 392 the user. This file should not be readable by anyone but the 393 user. It is possible to specify a passphrase when generating the 394 key; that passphrase will be used to encrypt the private part of 395 this file using 3DES. This file is not automatically accessed by 396 ssh-keygen but it is offered as the default file for the private 397 key. ssh(1) will read this file when a login attempt is made. 398 399 ~/.ssh/identity.pub 400 Contains the protocol version 1 RSA public key for 401 authentication. The contents of this file should be added to 402 ~/.ssh/authorized_keys on all machines where the user wishes to 403 log in using RSA authentication. There is no need to keep the 404 contents of this file secret. 405 406 ~/.ssh/id_dsa 407 ~/.ssh/id_ecdsa 408 ~/.ssh/id_rsa 409 Contains the protocol version 2 DSA, ECDSA or RSA authentication 410 identity of the user. This file should not be readable by anyone 411 but the user. It is possible to specify a passphrase when 412 generating the key; that passphrase will be used to encrypt the 413 private part of this file using 128-bit AES. This file is not 414 automatically accessed by ssh-keygen but it is offered as the 415 default file for the private key. ssh(1) will read this file 416 when a login attempt is made. 417 418 ~/.ssh/id_dsa.pub 419 ~/.ssh/id_ecdsa.pub 420 ~/.ssh/id_rsa.pub 421 Contains the protocol version 2 DSA, ECDSA or RSA public key for 422 authentication. The contents of this file should be added to 423 ~/.ssh/authorized_keys on all machines where the user wishes to 424 log in using public key authentication. There is no need to keep 425 the contents of this file secret. 426 427 /etc/moduli 428 Contains Diffie-Hellman groups used for DH-GEX. The file format 429 is described in moduli(5). 430 431SEE ALSO 432 ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8) 433 434 The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006. 435 436AUTHORS 437 OpenSSH is a derivative of the original and free ssh 1.2.12 release by 438 Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo 439 de Raadt and Dug Song removed many bugs, re-added newer features and 440 created OpenSSH. Markus Friedl contributed the support for SSH protocol 441 versions 1.5 and 2.0. 442 443OpenBSD 4.8 October 28, 2010 OpenBSD 4.8 444