ssh-keygen.0 revision 259065
1SSH-KEYGEN(1) OpenBSD Reference Manual SSH-KEYGEN(1) 2 3NAME 4 ssh-keygen - authentication key generation, management and conversion 5 6SYNOPSIS 7 ssh-keygen [-q] [-b bits] -t type [-N new_passphrase] [-C comment] 8 [-f output_keyfile] 9 ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile] 10 ssh-keygen -i [-m key_format] [-f input_keyfile] 11 ssh-keygen -e [-m key_format] [-f input_keyfile] 12 ssh-keygen -y [-f input_keyfile] 13 ssh-keygen -c [-P passphrase] [-C comment] [-f keyfile] 14 ssh-keygen -l [-f input_keyfile] 15 ssh-keygen -B [-f input_keyfile] 16 ssh-keygen -D pkcs11 17 ssh-keygen -F hostname [-f known_hosts_file] [-l] 18 ssh-keygen -H [-f known_hosts_file] 19 ssh-keygen -R hostname [-f known_hosts_file] 20 ssh-keygen -r hostname [-f input_keyfile] [-g] 21 ssh-keygen -G output_file [-v] [-b bits] [-M memory] [-S start_point] 22 ssh-keygen -T output_file -f input_file [-v] [-a num_trials] 23 [-J num_lines] [-j start_line] [-K checkpt] [-W generator] 24 ssh-keygen -s ca_key -I certificate_identity [-h] [-n principals] 25 [-O option] [-V validity_interval] [-z serial_number] file ... 26 ssh-keygen -L [-f input_keyfile] 27 ssh-keygen -A 28 ssh-keygen -k -f krl_file [-u] [-s ca_public] [-z version_number] 29 file ... 30 ssh-keygen -Q -f krl_file file ... 31 32DESCRIPTION 33 ssh-keygen generates, manages and converts authentication keys for 34 ssh(1). ssh-keygen can create RSA keys for use by SSH protocol version 1 35 and DSA, ECDSA or RSA keys for use by SSH protocol version 2. The type 36 of key to be generated is specified with the -t option. If invoked 37 without any arguments, ssh-keygen will generate an RSA key for use in SSH 38 protocol 2 connections. 39 40 ssh-keygen is also used to generate groups for use in Diffie-Hellman 41 group exchange (DH-GEX). See the MODULI GENERATION section for details. 42 43 Finally, ssh-keygen can be used to generate and update Key Revocation 44 Lists, and to test whether given keys have been revoked by one. See the 45 KEY REVOCATION LISTS section for details. 46 47 Normally each user wishing to use SSH with public key authentication runs 48 this once to create the authentication key in ~/.ssh/identity, 49 ~/.ssh/id_ecdsa, ~/.ssh/id_dsa or ~/.ssh/id_rsa. Additionally, the 50 system administrator may use this to generate host keys, as seen in 51 /etc/rc. 52 53 Normally this program generates the key and asks for a file in which to 54 store the private key. The public key is stored in a file with the same 55 name but ``.pub'' appended. The program also asks for a passphrase. The 56 passphrase may be empty to indicate no passphrase (host keys must have an 57 empty passphrase), or it may be a string of arbitrary length. A 58 passphrase is similar to a password, except it can be a phrase with a 59 series of words, punctuation, numbers, whitespace, or any string of 60 characters you want. Good passphrases are 10-30 characters long, are not 61 simple sentences or otherwise easily guessable (English prose has only 62 1-2 bits of entropy per character, and provides very bad passphrases), 63 and contain a mix of upper and lowercase letters, numbers, and non- 64 alphanumeric characters. The passphrase can be changed later by using 65 the -p option. 66 67 There is no way to recover a lost passphrase. If the passphrase is lost 68 or forgotten, a new key must be generated and the corresponding public 69 key copied to other machines. 70 71 For RSA1 keys, there is also a comment field in the key file that is only 72 for convenience to the user to help identify the key. The comment can 73 tell what the key is for, or whatever is useful. The comment is 74 initialized to ``user@host'' when the key is created, but can be changed 75 using the -c option. 76 77 After a key is generated, instructions below detail where the keys should 78 be placed to be activated. 79 80 The options are as follows: 81 82 -A For each of the key types (rsa1, rsa, dsa and ecdsa) for which 83 host keys do not exist, generate the host keys with the default 84 key file path, an empty passphrase, default bits for the key 85 type, and default comment. This is used by /etc/rc to generate 86 new host keys. 87 88 -a trials 89 Specifies the number of primality tests to perform when screening 90 DH-GEX candidates using the -T command. 91 92 -B Show the bubblebabble digest of specified private or public key 93 file. 94 95 -b bits 96 Specifies the number of bits in the key to create. For RSA keys, 97 the minimum size is 768 bits and the default is 2048 bits. 98 Generally, 2048 bits is considered sufficient. DSA keys must be 99 exactly 1024 bits as specified by FIPS 186-2. For ECDSA keys, 100 the -b flag determines the key length by selecting from one of 101 three elliptic curve sizes: 256, 384 or 521 bits. Attempting to 102 use bit lengths other than these three values for ECDSA keys will 103 fail. 104 105 -C comment 106 Provides a new comment. 107 108 -c Requests changing the comment in the private and public key 109 files. This operation is only supported for RSA1 keys. The 110 program will prompt for the file containing the private keys, for 111 the passphrase if the key has one, and for the new comment. 112 113 -D pkcs11 114 Download the RSA public keys provided by the PKCS#11 shared 115 library pkcs11. When used in combination with -s, this option 116 indicates that a CA key resides in a PKCS#11 token (see the 117 CERTIFICATES section for details). 118 119 -e This option will read a private or public OpenSSH key file and 120 print to stdout the key in one of the formats specified by the -m 121 option. The default export format is ``RFC4716''. This option 122 allows exporting OpenSSH keys for use by other programs, 123 including several commercial SSH implementations. 124 125 -F hostname 126 Search for the specified hostname in a known_hosts file, listing 127 any occurrences found. This option is useful to find hashed host 128 names or addresses and may also be used in conjunction with the 129 -H option to print found keys in a hashed format. 130 131 -f filename 132 Specifies the filename of the key file. 133 134 -G output_file 135 Generate candidate primes for DH-GEX. These primes must be 136 screened for safety (using the -T option) before use. 137 138 -g Use generic DNS format when printing fingerprint resource records 139 using the -r command. 140 141 -H Hash a known_hosts file. This replaces all hostnames and 142 addresses with hashed representations within the specified file; 143 the original content is moved to a file with a .old suffix. 144 These hashes may be used normally by ssh and sshd, but they do 145 not reveal identifying information should the file's contents be 146 disclosed. This option will not modify existing hashed hostnames 147 and is therefore safe to use on files that mix hashed and non- 148 hashed names. 149 150 -h When signing a key, create a host certificate instead of a user 151 certificate. Please see the CERTIFICATES section for details. 152 153 -I certificate_identity 154 Specify the key identity when signing a public key. Please see 155 the CERTIFICATES section for details. 156 157 -i This option will read an unencrypted private (or public) key file 158 in the format specified by the -m option and print an OpenSSH 159 compatible private (or public) key to stdout. 160 161 -J num_lines 162 Exit after screening the specified number of lines while 163 performing DH candidate screening using the -T option. 164 165 -j start_line 166 Start screening at the specified line number while performing DH 167 candidate screening using the -T option. 168 169 -K checkpt 170 Write the last line processed to the file checkpt while 171 performing DH candidate screening using the -T option. This will 172 be used to skip lines in the input file that have already been 173 processed if the job is restarted. This option allows importing 174 keys from other software, including several commercial SSH 175 implementations. The default import format is ``RFC4716''. 176 177 -k Generate a KRL file. In this mode, ssh-keygen will generate a 178 KRL file at the location specified via the -f flag that revokes 179 every key or certificate presented on the command line. 180 Keys/certificates to be revoked may be specified by public key 181 file or using the format described in the KEY REVOCATION LISTS 182 section. 183 184 -L Prints the contents of a certificate. 185 186 -l Show fingerprint of specified public key file. Private RSA1 keys 187 are also supported. For RSA and DSA keys ssh-keygen tries to 188 find the matching public key file and prints its fingerprint. If 189 combined with -v, an ASCII art representation of the key is 190 supplied with the fingerprint. 191 192 -M memory 193 Specify the amount of memory to use (in megabytes) when 194 generating candidate moduli for DH-GEX. 195 196 -m key_format 197 Specify a key format for the -i (import) or -e (export) 198 conversion options. The supported key formats are: ``RFC4716'' 199 (RFC 4716/SSH2 public or private key), ``PKCS8'' (PEM PKCS8 200 public key) or ``PEM'' (PEM public key). The default conversion 201 format is ``RFC4716''. 202 203 -N new_passphrase 204 Provides the new passphrase. 205 206 -n principals 207 Specify one or more principals (user or host names) to be 208 included in a certificate when signing a key. Multiple 209 principals may be specified, separated by commas. Please see the 210 CERTIFICATES section for details. 211 212 -O option 213 Specify a certificate option when signing a key. This option may 214 be specified multiple times. Please see the CERTIFICATES section 215 for details. The options that are valid for user certificates 216 are: 217 218 clear Clear all enabled permissions. This is useful for 219 clearing the default set of permissions so permissions 220 may be added individually. 221 222 force-command=command 223 Forces the execution of command instead of any shell or 224 command specified by the user when the certificate is 225 used for authentication. 226 227 no-agent-forwarding 228 Disable ssh-agent(1) forwarding (permitted by default). 229 230 no-port-forwarding 231 Disable port forwarding (permitted by default). 232 233 no-pty Disable PTY allocation (permitted by default). 234 235 no-user-rc 236 Disable execution of ~/.ssh/rc by sshd(8) (permitted by 237 default). 238 239 no-x11-forwarding 240 Disable X11 forwarding (permitted by default). 241 242 permit-agent-forwarding 243 Allows ssh-agent(1) forwarding. 244 245 permit-port-forwarding 246 Allows port forwarding. 247 248 permit-pty 249 Allows PTY allocation. 250 251 permit-user-rc 252 Allows execution of ~/.ssh/rc by sshd(8). 253 254 permit-x11-forwarding 255 Allows X11 forwarding. 256 257 source-address=address_list 258 Restrict the source addresses from which the certificate 259 is considered valid. The address_list is a comma- 260 separated list of one or more address/netmask pairs in 261 CIDR format. 262 263 At present, no options are valid for host keys. 264 265 -P passphrase 266 Provides the (old) passphrase. 267 268 -p Requests changing the passphrase of a private key file instead of 269 creating a new private key. The program will prompt for the file 270 containing the private key, for the old passphrase, and twice for 271 the new passphrase. 272 273 -Q Test whether keys have been revoked in a KRL. 274 275 -q Silence ssh-keygen. 276 277 -R hostname 278 Removes all keys belonging to hostname from a known_hosts file. 279 This option is useful to delete hashed hosts (see the -H option 280 above). 281 282 -r hostname 283 Print the SSHFP fingerprint resource record named hostname for 284 the specified public key file. 285 286 -S start 287 Specify start point (in hex) when generating candidate moduli for 288 DH-GEX. 289 290 -s ca_key 291 Certify (sign) a public key using the specified CA key. Please 292 see the CERTIFICATES section for details. 293 294 When generating a KRL, -s specifies a path to a CA public key 295 file used to revoke certificates directly by key ID or serial 296 number. See the KEY REVOCATION LISTS section for details. 297 298 -T output_file 299 Test DH group exchange candidate primes (generated using the -G 300 option) for safety. 301 302 -t type 303 Specifies the type of key to create. The possible values are 304 ``rsa1'' for protocol version 1 and ``dsa'', ``ecdsa'' or ``rsa'' 305 for protocol version 2. 306 307 -u Update a KRL. When specified with -k, keys listed via the 308 command line are added to the existing KRL rather than a new KRL 309 being created. 310 311 -V validity_interval 312 Specify a validity interval when signing a certificate. A 313 validity interval may consist of a single time, indicating that 314 the certificate is valid beginning now and expiring at that time, 315 or may consist of two times separated by a colon to indicate an 316 explicit time interval. The start time may be specified as a 317 date in YYYYMMDD format, a time in YYYYMMDDHHMMSS format or a 318 relative time (to the current time) consisting of a minus sign 319 followed by a relative time in the format described in the TIME 320 FORMATS section of sshd_config(5). The end time may be specified 321 as a YYYYMMDD date, a YYYYMMDDHHMMSS time or a relative time 322 starting with a plus character. 323 324 For example: ``+52w1d'' (valid from now to 52 weeks and one day 325 from now), ``-4w:+4w'' (valid from four weeks ago to four weeks 326 from now), ``20100101123000:20110101123000'' (valid from 12:30 327 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011), 328 ``-1d:20110101'' (valid from yesterday to midnight, January 1st, 329 2011). 330 331 -v Verbose mode. Causes ssh-keygen to print debugging messages 332 about its progress. This is helpful for debugging moduli 333 generation. Multiple -v options increase the verbosity. The 334 maximum is 3. 335 336 -W generator 337 Specify desired generator when testing candidate moduli for DH- 338 GEX. 339 340 -y This option will read a private OpenSSH format file and print an 341 OpenSSH public key to stdout. 342 343 -z serial_number 344 Specifies a serial number to be embedded in the certificate to 345 distinguish this certificate from others from the same CA. The 346 default serial number is zero. 347 348 When generating a KRL, the -z flag is used to specify a KRL 349 version number. 350 351MODULI GENERATION 352 ssh-keygen may be used to generate groups for the Diffie-Hellman Group 353 Exchange (DH-GEX) protocol. Generating these groups is a two-step 354 process: first, candidate primes are generated using a fast, but memory 355 intensive process. These candidate primes are then tested for 356 suitability (a CPU-intensive process). 357 358 Generation of primes is performed using the -G option. The desired 359 length of the primes may be specified by the -b option. For example: 360 361 # ssh-keygen -G moduli-2048.candidates -b 2048 362 363 By default, the search for primes begins at a random point in the desired 364 length range. This may be overridden using the -S option, which 365 specifies a different start point (in hex). 366 367 Once a set of candidates have been generated, they must be screened for 368 suitability. This may be performed using the -T option. In this mode 369 ssh-keygen will read candidates from standard input (or a file specified 370 using the -f option). For example: 371 372 # ssh-keygen -T moduli-2048 -f moduli-2048.candidates 373 374 By default, each candidate will be subjected to 100 primality tests. 375 This may be overridden using the -a option. The DH generator value will 376 be chosen automatically for the prime under consideration. If a specific 377 generator is desired, it may be requested using the -W option. Valid 378 generator values are 2, 3, and 5. 379 380 Screened DH groups may be installed in /etc/moduli. It is important that 381 this file contains moduli of a range of bit lengths and that both ends of 382 a connection share common moduli. 383 384CERTIFICATES 385 ssh-keygen supports signing of keys to produce certificates that may be 386 used for user or host authentication. Certificates consist of a public 387 key, some identity information, zero or more principal (user or host) 388 names and a set of options that are signed by a Certification Authority 389 (CA) key. Clients or servers may then trust only the CA key and verify 390 its signature on a certificate rather than trusting many user/host keys. 391 Note that OpenSSH certificates are a different, and much simpler, format 392 to the X.509 certificates used in ssl(8). 393 394 ssh-keygen supports two types of certificates: user and host. User 395 certificates authenticate users to servers, whereas host certificates 396 authenticate server hosts to users. To generate a user certificate: 397 398 $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub 399 400 The resultant certificate will be placed in /path/to/user_key-cert.pub. 401 A host certificate requires the -h option: 402 403 $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub 404 405 The host certificate will be output to /path/to/host_key-cert.pub. 406 407 It is possible to sign using a CA key stored in a PKCS#11 token by 408 providing the token library using -D and identifying the CA key by 409 providing its public half as an argument to -s: 410 411 $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub 412 413 In all cases, key_id is a "key identifier" that is logged by the server 414 when the certificate is used for authentication. 415 416 Certificates may be limited to be valid for a set of principal 417 (user/host) names. By default, generated certificates are valid for all 418 users or hosts. To generate a certificate for a specified set of 419 principals: 420 421 $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub 422 $ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub 423 424 Additional limitations on the validity and use of user certificates may 425 be specified through certificate options. A certificate option may 426 disable features of the SSH session, may be valid only when presented 427 from particular source addresses or may force the use of a specific 428 command. For a list of valid certificate options, see the documentation 429 for the -O option above. 430 431 Finally, certificates may be defined with a validity lifetime. The -V 432 option allows specification of certificate start and end times. A 433 certificate that is presented at a time outside this range will not be 434 considered valid. By default, certificates are valid from UNIX Epoch to 435 the distant future. 436 437 For certificates to be used for user or host authentication, the CA 438 public key must be trusted by sshd(8) or ssh(1). Please refer to those 439 manual pages for details. 440 441KEY REVOCATION LISTS 442 ssh-keygen is able to manage OpenSSH format Key Revocation Lists (KRLs). 443 These binary files specify keys or certificates to be revoked using a 444 compact format, taking as little a one bit per certificate if they are 445 being revoked by serial number. 446 447 KRLs may be generated using the -k flag. This option reads one or more 448 files from the command line and generates a new KRL. The files may 449 either contain a KRL specification (see below) or public keys, listed one 450 per line. Plain public keys are revoked by listing their hash or 451 contents in the KRL and certificates revoked by serial number or key ID 452 (if the serial is zero or not available). 453 454 Revoking keys using a KRL specification offers explicit control over the 455 types of record used to revoke keys and may be used to directly revoke 456 certificates by serial number or key ID without having the complete 457 original certificate on hand. A KRL specification consists of lines 458 containing one of the following directives followed by a colon and some 459 directive-specific information. 460 461 serial: serial_number[-serial_number] 462 Revokes a certificate with the specified serial number. Serial 463 numbers are 64-bit values, not including zero and may be 464 expressed in decimal, hex or octal. If two serial numbers are 465 specified separated by a hyphen, then the range of serial numbers 466 including and between each is revoked. The CA key must have been 467 specified on the ssh-keygen command line using the -s option. 468 469 id: key_id 470 Revokes a certificate with the specified key ID string. The CA 471 key must have been specified on the ssh-keygen command line using 472 the -s option. 473 474 key: public_key 475 Revokes the specified key. If a certificate is listed, then it 476 is revoked as a plain public key. 477 478 sha1: public_key 479 Revokes the specified key by its SHA1 hash. 480 481 KRLs may be updated using the -u flag in addition to -k. When this 482 option is specified, keys listed via the command line are merged into the 483 KRL, adding to those already there. 484 485 It is also possible, given a KRL, to test whether it revokes a particular 486 key (or keys). The -Q flag will query an existing KRL, testing each key 487 specified on the commandline. If any key listed on the command line has 488 been revoked (or an error encountered) then ssh-keygen will exit with a 489 non-zero exit status. A zero exit status will only be returned if no key 490 was revoked. 491 492FILES 493 ~/.ssh/identity 494 Contains the protocol version 1 RSA authentication identity of 495 the user. This file should not be readable by anyone but the 496 user. It is possible to specify a passphrase when generating the 497 key; that passphrase will be used to encrypt the private part of 498 this file using 3DES. This file is not automatically accessed by 499 ssh-keygen but it is offered as the default file for the private 500 key. ssh(1) will read this file when a login attempt is made. 501 502 ~/.ssh/identity.pub 503 Contains the protocol version 1 RSA public key for 504 authentication. The contents of this file should be added to 505 ~/.ssh/authorized_keys on all machines where the user wishes to 506 log in using RSA authentication. There is no need to keep the 507 contents of this file secret. 508 509 ~/.ssh/id_dsa 510 ~/.ssh/id_ecdsa 511 ~/.ssh/id_rsa 512 Contains the protocol version 2 DSA, ECDSA or RSA authentication 513 identity of the user. This file should not be readable by anyone 514 but the user. It is possible to specify a passphrase when 515 generating the key; that passphrase will be used to encrypt the 516 private part of this file using 128-bit AES. This file is not 517 automatically accessed by ssh-keygen but it is offered as the 518 default file for the private key. ssh(1) will read this file 519 when a login attempt is made. 520 521 ~/.ssh/id_dsa.pub 522 ~/.ssh/id_ecdsa.pub 523 ~/.ssh/id_rsa.pub 524 Contains the protocol version 2 DSA, ECDSA or RSA public key for 525 authentication. The contents of this file should be added to 526 ~/.ssh/authorized_keys on all machines where the user wishes to 527 log in using public key authentication. There is no need to keep 528 the contents of this file secret. 529 530 /etc/moduli 531 Contains Diffie-Hellman groups used for DH-GEX. The file format 532 is described in moduli(5). 533 534SEE ALSO 535 ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8) 536 537 The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006. 538 539AUTHORS 540 OpenSSH is a derivative of the original and free ssh 1.2.12 release by 541 Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo 542 de Raadt and Dug Song removed many bugs, re-added newer features and 543 created OpenSSH. Markus Friedl contributed the support for SSH protocol 544 versions 1.5 and 2.0. 545 546OpenBSD 5.4 June 27, 2013 OpenBSD 5.4 547