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