ssh-keygen.0 revision 239849
12061SjkhSSH-KEYGEN(1) OpenBSD Reference Manual SSH-KEYGEN(1) 250479Speter 32061SjkhNAME 438666Sjb ssh-keygen - authentication key generation, management and conversion 532427Sjb 6111131SruSYNOPSIS 7111131Sru ssh-keygen [-q] [-b bits] -t type [-N new_passphrase] [-C comment] 838666Sjb [-f output_keyfile] 938666Sjb ssh-keygen -p [-P old_passphrase] [-N new_passphrase] [-f keyfile] 1038666Sjb ssh-keygen -i [-m key_format] [-f input_keyfile] 1138666Sjb ssh-keygen -e [-m key_format] [-f input_keyfile] 1264049Salex ssh-keygen -y [-f input_keyfile] 1364049Salex ssh-keygen -c [-P passphrase] [-C comment] [-f keyfile] 14116679Ssimokawa ssh-keygen -l [-f input_keyfile] 1566071Smarkm ssh-keygen -B [-f input_keyfile] 16116679Ssimokawa ssh-keygen -D pkcs11 1773504Sobrien ssh-keygen -F hostname [-f known_hosts_file] [-l] 1838666Sjb ssh-keygen -H [-f known_hosts_file] 1938666Sjb ssh-keygen -R hostname [-f known_hosts_file] 2038666Sjb ssh-keygen -r hostname [-f input_keyfile] [-g] 2132427Sjb ssh-keygen -G output_file [-v] [-b bits] [-M memory] [-S start_point] 2238666Sjb ssh-keygen -T output_file -f input_file [-v] [-a num_trials] 23108451Sschweikh [-J num_lines] [-j start_line] [-K checkpt] [-W generator] 2438666Sjb ssh-keygen -s ca_key -I certificate_identity [-h] [-n principals] 2538666Sjb [-O option] [-V validity_interval] [-z serial_number] file ... 2638666Sjb ssh-keygen -L [-f input_keyfile] 2738666Sjb ssh-keygen -A 2817308Speter 2991606SkeramidaDESCRIPTION 3019175Sbde ssh-keygen generates, manages and converts authentication keys for 3196205Sjwd ssh(1). ssh-keygen can create RSA keys for use by SSH protocol version 1 3296205Sjwd and DSA, ECDSA or RSA keys for use by SSH protocol version 2. The type 3338042Sbde of key to be generated is specified with the -t option. If invoked 3496205Sjwd without any arguments, ssh-keygen will generate an RSA key for use in SSH 3596205Sjwd protocol 2 connections. 3638042Sbde 3796205Sjwd ssh-keygen is also used to generate groups for use in Diffie-Hellman 3896205Sjwd group exchange (DH-GEX). See the MODULI GENERATION section for details. 3917308Speter 4096205Sjwd Normally each user wishing to use SSH with public key authentication runs 4196205Sjwd this once to create the authentication key in ~/.ssh/identity, 4217308Speter ~/.ssh/id_ecdsa, ~/.ssh/id_dsa or ~/.ssh/id_rsa. Additionally, the 4396205Sjwd system administrator may use this to generate host keys, as seen in 4496205Sjwd /etc/rc. 4596205Sjwd 4696205Sjwd Normally this program generates the key and asks for a file in which to 4796205Sjwd store the private key. The public key is stored in a file with the same 4896205Sjwd name but ``.pub'' appended. The program also asks for a passphrase. The 4996205Sjwd passphrase may be empty to indicate no passphrase (host keys must have an 5096205Sjwd empty passphrase), or it may be a string of arbitrary length. A 5196205Sjwd passphrase is similar to a password, except it can be a phrase with a 5296205Sjwd series of words, punctuation, numbers, whitespace, or any string of 5396205Sjwd characters you want. Good passphrases are 10-30 characters long, are not 5496205Sjwd simple sentences or otherwise easily guessable (English prose has only 5598775Sdillon 1-2 bits of entropy per character, and provides very bad passphrases), 5698723Sdillon and contain a mix of upper and lowercase letters, numbers, and non- 5798723Sdillon alphanumeric characters. The passphrase can be changed later by using 5898723Sdillon the -p option. 5998723Sdillon 6038666Sjb There is no way to recover a lost passphrase. If the passphrase is lost 6138666Sjb or forgotten, a new key must be generated and the corresponding public 6217308Speter key copied to other machines. 6395509Sru 6495793Sru For RSA1 keys, there is also a comment field in the key file that is only 65116679Ssimokawa for convenience to the user to help identify the key. The comment can 66116679Ssimokawa tell what the key is for, or whatever is useful. The comment is 67116679Ssimokawa initialized to ``user@host'' when the key is created, but can be changed 6895146Sgshapiro using the -c option. 692061Sjkh 7097769Sru After a key is generated, instructions below detail where the keys should 7197252Sru be placed to be activated. 7297252Sru 7395730Sru The options are as follows: 7495793Sru 75111617Sru -A For each of the key types (rsa1, rsa, dsa and ecdsa) for which 7695730Sru host keys do not exist, generate the host keys with the default 77116679Ssimokawa key file path, an empty passphrase, default bits for the key 7895730Sru type, and default comment. This is used by /etc/rc to generate 79116679Ssimokawa new host keys. 8095730Sru 81110035Sru -a trials 82107516Sru Specifies the number of primality tests to perform when screening 83110035Sru DH-GEX candidates using the -T command. 84117229Sru 85110035Sru -B Show the bubblebabble digest of specified private or public key 86117229Sru file. 87117229Sru 8854324Smarcel -b bits 8917308Speter Specifies the number of bits in the key to create. For RSA keys, 9038666Sjb the minimum size is 768 bits and the default is 2048 bits. 9117308Speter Generally, 2048 bits is considered sufficient. DSA keys must be 9297252Sru exactly 1024 bits as specified by FIPS 186-2. For ECDSA keys, 9338666Sjb the -b flag determines the key length by selecting from one of 94110035Sru three elliptic curve sizes: 256, 384 or 521 bits. Attempting to 952302Spaul use bit lengths other than these three values for ECDSA keys will 9639206Sjkh fail. 9739206Sjkh 9839206Sjkh -C comment 9973349Sru Provides a new comment. 10017308Speter 10154324Smarcel -c Requests changing the comment in the private and public key 10254324Smarcel files. This operation is only supported for RSA1 keys. The 10354324Smarcel program will prompt for the file containing the private keys, for 10454324Smarcel the passphrase if the key has one, and for the new comment. 10554324Smarcel 10654324Smarcel -D pkcs11 10754324Smarcel Download the RSA public keys provided by the PKCS#11 shared 108103436Speter library pkcs11. When used in combination with -s, this option 10954324Smarcel indicates that a CA key resides in a PKCS#11 token (see the 11054324Smarcel CERTIFICATES section for details). 11154324Smarcel 11254324Smarcel -e This option will read a private or public OpenSSH key file and 11354324Smarcel print to stdout the key in one of the formats specified by the -m 11454324Smarcel option. The default export format is ``RFC4716''. This option 115110035Sru allows exporting OpenSSH keys for use by other programs, 11654324Smarcel including several commercial SSH implementations. 117110035Sru 118110035Sru -F hostname 11954324Smarcel Search for the specified hostname in a known_hosts file, listing 12054324Smarcel any occurrences found. This option is useful to find hashed host 12154324Smarcel names or addresses and may also be used in conjunction with the 12254324Smarcel -H option to print found keys in a hashed format. 12354324Smarcel 124110035Sru -f filename 12554324Smarcel Specifies the filename of the key file. 12654324Smarcel 12754324Smarcel -G output_file 128103436Speter Generate candidate primes for DH-GEX. These primes must be 12954324Smarcel screened for safety (using the -T option) before use. 13054324Smarcel 13154324Smarcel -g Use generic DNS format when printing fingerprint resource records 13295730Sru using the -r command. 13395730Sru 13495730Sru -H Hash a known_hosts file. This replaces all hostnames and 13595730Sru addresses with hashed representations within the specified file; 13695730Sru the original content is moved to a file with a .old suffix. 13795730Sru These hashes may be used normally by ssh and sshd, but they do 13895730Sru not reveal identifying information should the file's contents be 13938666Sjb disclosed. This option will not modify existing hashed hostnames 140107374Sru and is therefore safe to use on files that mix hashed and non- 14117308Speter hashed names. 14255678Smarcel 143110035Sru -h When signing a key, create a host certificate instead of a user 144116696Sru certificate. Please see the CERTIFICATES section for details. 145110035Sru 146110035Sru -I certificate_identity 147110035Sru Specify the key identity when signing a public key. Please see 1482061Sjkh the CERTIFICATES section for details. 14917308Speter 150107516Sru -i This option will read an unencrypted private (or public) key file 151107374Sru in the format specified by the -m option and print an OpenSSH 15255678Smarcel compatible private (or public) key to stdout. 153107516Sru 154107516Sru -J num_lines 155107516Sru Exit after screening the specified number of lines while 156107516Sru performing DH candidate screening using the -T option. 157107516Sru 158107516Sru -j start_line 159107516Sru Start screening at the specified line number while performing DH 160107516Sru candidate screening using the -T option. 16155678Smarcel 16255678Smarcel -K checkpt 16355678Smarcel Write the last line processed to the file checkpt while 164116696Sru performing DH candidate screening using the -T option. This will 16555678Smarcel be used to skip lines in the input file that have already been 16655678Smarcel processed if the job is restarted. This option allows importing 167107516Sru keys from other software, including several commercial SSH 168107516Sru implementations. The default import format is ``RFC4716''. 169107516Sru 170107516Sru -L Prints the contents of a certificate. 17155678Smarcel 17255678Smarcel -l Show fingerprint of specified public key file. Private RSA1 keys 173111131Sru are also supported. For RSA and DSA keys ssh-keygen tries to 174111131Sru find the matching public key file and prints its fingerprint. If 175111131Sru combined with -v, an ASCII art representation of the key is 176111131Sru supplied with the fingerprint. 177111131Sru 178111131Sru -M memory 179111131Sru Specify the amount of memory to use (in megabytes) when 180103985Sphk generating candidate moduli for DH-GEX. 181103985Sphk 182103985Sphk -m key_format 183103985Sphk Specify a key format for the -i (import) or -e (export) 184111089Sphk conversion options. The supported key formats are: ``RFC4716'' 185111131Sru (RFC 4716/SSH2 public or private key), ``PKCS8'' (PEM PKCS8 186111131Sru public key) or ``PEM'' (PEM public key). The default conversion 187111131Sru format is ``RFC4716''. 188111131Sru 189111131Sru -N new_passphrase 190111131Sru Provides the new passphrase. 191111131Sru 192111131Sru -n principals 193111131Sru Specify one or more principals (user or host names) to be 194111133Sru included in a certificate when signing a key. Multiple 195103985Sphk principals may be specified, separated by commas. Please see the 196111131Sru CERTIFICATES section for details. 197111131Sru 198103985Sphk -O option 199111131Sru Specify a certificate option when signing a key. This option may 200103985Sphk be specified multiple times. Please see the CERTIFICATES section 201107884Simp for details. The options that are valid for user certificates 202103985Sphk are: 203103985Sphk 204111131Sru clear Clear all enabled permissions. This is useful for 205111131Sru clearing the default set of permissions so permissions 206103985Sphk may be added individually. 207103985Sphk 208111131Sru force-command=command 209111131Sru Forces the execution of command instead of any shell or 210111131Sru command specified by the user when the certificate is 211111131Sru used for authentication. 212111131Sru 213103985Sphk no-agent-forwarding 214 Disable ssh-agent(1) forwarding (permitted by default). 215 216 no-port-forwarding 217 Disable port forwarding (permitted by default). 218 219 no-pty Disable PTY allocation (permitted by default). 220 221 no-user-rc 222 Disable execution of ~/.ssh/rc by sshd(8) (permitted by 223 default). 224 225 no-x11-forwarding 226 Disable X11 forwarding (permitted by default). 227 228 permit-agent-forwarding 229 Allows ssh-agent(1) forwarding. 230 231 permit-port-forwarding 232 Allows port forwarding. 233 234 permit-pty 235 Allows PTY allocation. 236 237 permit-user-rc 238 Allows execution of ~/.ssh/rc by sshd(8). 239 240 permit-x11-forwarding 241 Allows X11 forwarding. 242 243 source-address=address_list 244 Restrict the source addresses from which the certificate 245 is considered valid. The address_list is a comma- 246 separated list of one or more address/netmask pairs in 247 CIDR format. 248 249 At present, no options are valid for host keys. 250 251 -P passphrase 252 Provides the (old) passphrase. 253 254 -p Requests changing the passphrase of a private key file instead of 255 creating a new private key. The program will prompt for the file 256 containing the private key, for the old passphrase, and twice for 257 the new passphrase. 258 259 -q Silence ssh-keygen. 260 261 -R hostname 262 Removes all keys belonging to hostname from a known_hosts file. 263 This option is useful to delete hashed hosts (see the -H option 264 above). 265 266 -r hostname 267 Print the SSHFP fingerprint resource record named hostname for 268 the specified public key file. 269 270 -S start 271 Specify start point (in hex) when generating candidate moduli for 272 DH-GEX. 273 274 -s ca_key 275 Certify (sign) a public key using the specified CA key. Please 276 see the CERTIFICATES section for details. 277 278 -T output_file 279 Test DH group exchange candidate primes (generated using the -G 280 option) for safety. 281 282 -t type 283 Specifies the type of key to create. The possible values are 284 ``rsa1'' for protocol version 1 and ``dsa'', ``ecdsa'' or ``rsa'' 285 for protocol version 2. 286 287 -V validity_interval 288 Specify a validity interval when signing a certificate. A 289 validity interval may consist of a single time, indicating that 290 the certificate is valid beginning now and expiring at that time, 291 or may consist of two times separated by a colon to indicate an 292 explicit time interval. The start time may be specified as a 293 date in YYYYMMDD format, a time in YYYYMMDDHHMMSS format or a 294 relative time (to the current time) consisting of a minus sign 295 followed by a relative time in the format described in the TIME 296 FORMATS section of sshd_config(5). The end time may be specified 297 as a YYYYMMDD date, a YYYYMMDDHHMMSS time or a relative time 298 starting with a plus character. 299 300 For example: ``+52w1d'' (valid from now to 52 weeks and one day 301 from now), ``-4w:+4w'' (valid from four weeks ago to four weeks 302 from now), ``20100101123000:20110101123000'' (valid from 12:30 303 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011), 304 ``-1d:20110101'' (valid from yesterday to midnight, January 1st, 305 2011). 306 307 -v Verbose mode. Causes ssh-keygen to print debugging messages 308 about its progress. This is helpful for debugging moduli 309 generation. Multiple -v options increase the verbosity. The 310 maximum is 3. 311 312 -W generator 313 Specify desired generator when testing candidate moduli for DH- 314 GEX. 315 316 -y This option will read a private OpenSSH format file and print an 317 OpenSSH public key to stdout. 318 319 -z serial_number 320 Specifies a serial number to be embedded in the certificate to 321 distinguish this certificate from others from the same CA. The 322 default serial number is zero. 323 324MODULI GENERATION 325 ssh-keygen may be used to generate groups for the Diffie-Hellman Group 326 Exchange (DH-GEX) protocol. Generating these groups is a two-step 327 process: first, candidate primes are generated using a fast, but memory 328 intensive process. These candidate primes are then tested for 329 suitability (a CPU-intensive process). 330 331 Generation of primes is performed using the -G option. The desired 332 length of the primes may be specified by the -b option. For example: 333 334 # ssh-keygen -G moduli-2048.candidates -b 2048 335 336 By default, the search for primes begins at a random point in the desired 337 length range. This may be overridden using the -S option, which 338 specifies a different start point (in hex). 339 340 Once a set of candidates have been generated, they must be screened for 341 suitability. This may be performed using the -T option. In this mode 342 ssh-keygen will read candidates from standard input (or a file specified 343 using the -f option). For example: 344 345 # ssh-keygen -T moduli-2048 -f moduli-2048.candidates 346 347 By default, each candidate will be subjected to 100 primality tests. 348 This may be overridden using the -a option. The DH generator value will 349 be chosen automatically for the prime under consideration. If a specific 350 generator is desired, it may be requested using the -W option. Valid 351 generator values are 2, 3, and 5. 352 353 Screened DH groups may be installed in /etc/moduli. It is important that 354 this file contains moduli of a range of bit lengths and that both ends of 355 a connection share common moduli. 356 357CERTIFICATES 358 ssh-keygen supports signing of keys to produce certificates that may be 359 used for user or host authentication. Certificates consist of a public 360 key, some identity information, zero or more principal (user or host) 361 names and a set of options that are signed by a Certification Authority 362 (CA) key. Clients or servers may then trust only the CA key and verify 363 its signature on a certificate rather than trusting many user/host keys. 364 Note that OpenSSH certificates are a different, and much simpler, format 365 to the X.509 certificates used in ssl(8). 366 367 ssh-keygen supports two types of certificates: user and host. User 368 certificates authenticate users to servers, whereas host certificates 369 authenticate server hosts to users. To generate a user certificate: 370 371 $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub 372 373 The resultant certificate will be placed in /path/to/user_key-cert.pub. 374 A host certificate requires the -h option: 375 376 $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub 377 378 The host certificate will be output to /path/to/host_key-cert.pub. 379 380 It is possible to sign using a CA key stored in a PKCS#11 token by 381 providing the token library using -D and identifying the CA key by 382 providing its public half as an argument to -s: 383 384 $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub 385 386 In all cases, key_id is a "key identifier" that is logged by the server 387 when the certificate is used for authentication. 388 389 Certificates may be limited to be valid for a set of principal 390 (user/host) names. By default, generated certificates are valid for all 391 users or hosts. To generate a certificate for a specified set of 392 principals: 393 394 $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub 395 $ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub 396 397 Additional limitations on the validity and use of user certificates may 398 be specified through certificate options. A certificate option may 399 disable features of the SSH session, may be valid only when presented 400 from particular source addresses or may force the use of a specific 401 command. For a list of valid certificate options, see the documentation 402 for the -O option above. 403 404 Finally, certificates may be defined with a validity lifetime. The -V 405 option allows specification of certificate start and end times. A 406 certificate that is presented at a time outside this range will not be 407 considered valid. By default, certificates have a maximum validity 408 interval. 409 410 For certificates to be used for user or host authentication, the CA 411 public key must be trusted by sshd(8) or ssh(1). Please refer to those 412 manual pages for details. 413 414FILES 415 ~/.ssh/identity 416 Contains the protocol version 1 RSA authentication identity of 417 the user. This file should not be readable by anyone but the 418 user. It is possible to specify a passphrase when generating the 419 key; that passphrase will be used to encrypt the private part of 420 this file using 3DES. This file is not automatically accessed by 421 ssh-keygen but it is offered as the default file for the private 422 key. ssh(1) will read this file when a login attempt is made. 423 424 ~/.ssh/identity.pub 425 Contains the protocol version 1 RSA public key for 426 authentication. The contents of this file should be added to 427 ~/.ssh/authorized_keys on all machines where the user wishes to 428 log in using RSA authentication. There is no need to keep the 429 contents of this file secret. 430 431 ~/.ssh/id_dsa 432 ~/.ssh/id_ecdsa 433 ~/.ssh/id_rsa 434 Contains the protocol version 2 DSA, ECDSA or RSA authentication 435 identity of the user. This file should not be readable by anyone 436 but the user. It is possible to specify a passphrase when 437 generating the key; that passphrase will be used to encrypt the 438 private part of this file using 128-bit AES. This file is not 439 automatically accessed by ssh-keygen but it is offered as the 440 default file for the private key. ssh(1) will read this file 441 when a login attempt is made. 442 443 ~/.ssh/id_dsa.pub 444 ~/.ssh/id_ecdsa.pub 445 ~/.ssh/id_rsa.pub 446 Contains the protocol version 2 DSA, ECDSA or RSA public key for 447 authentication. The contents of this file should be added to 448 ~/.ssh/authorized_keys on all machines where the user wishes to 449 log in using public key authentication. There is no need to keep 450 the contents of this file secret. 451 452 /etc/moduli 453 Contains Diffie-Hellman groups used for DH-GEX. The file format 454 is described in moduli(5). 455 456SEE ALSO 457 ssh(1), ssh-add(1), ssh-agent(1), moduli(5), sshd(8) 458 459 The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006. 460 461AUTHORS 462 OpenSSH is a derivative of the original and free ssh 1.2.12 release by 463 Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo 464 de Raadt and Dug Song removed many bugs, re-added newer features and 465 created OpenSSH. Markus Friedl contributed the support for SSH protocol 466 versions 1.5 and 2.0. 467 468OpenBSD 5.2 July 6, 2012 OpenBSD 5.2 469