1.\" $OpenBSD: ssh-keygen.1,v 1.109 2012/07/06 00:41:59 dtucker Exp $ 2.\" 3.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 4.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 5.\" All rights reserved 6.\" 7.\" As far as I am concerned, the code I have written for this software 8.\" can be used freely for any purpose. Any derived versions of this 9.\" software must be clearly marked as such, and if the derived work is 10.\" incompatible with the protocol description in the RFC file, it must be 11.\" called by a name other than "ssh" or "Secure Shell". 12.\" 13.\" 14.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. 15.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. 16.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. 17.\" 18.\" Redistribution and use in source and binary forms, with or without 19.\" modification, are permitted provided that the following conditions 20.\" are met: 21.\" 1. Redistributions of source code must retain the above copyright 22.\" notice, this list of conditions and the following disclaimer. 23.\" 2. Redistributions in binary form must reproduce the above copyright 24.\" notice, this list of conditions and the following disclaimer in the 25.\" documentation and/or other materials provided with the distribution. 26.\" 27.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 28.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 29.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 30.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 31.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 32.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 33.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 34.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 35.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 36.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd $Mdocdate: July 6 2012 $ 39.Dt SSH-KEYGEN 1 40.Os 41.Sh NAME 42.Nm ssh-keygen 43.Nd authentication key generation, management and conversion 44.Sh SYNOPSIS 45.Bk -words 46.Nm ssh-keygen 47.Op Fl q 48.Op Fl b Ar bits 49.Fl t Ar type 50.Op Fl N Ar new_passphrase 51.Op Fl C Ar comment 52.Op Fl f Ar output_keyfile 53.Nm ssh-keygen 54.Fl p 55.Op Fl P Ar old_passphrase 56.Op Fl N Ar new_passphrase 57.Op Fl f Ar keyfile 58.Nm ssh-keygen 59.Fl i 60.Op Fl m Ar key_format 61.Op Fl f Ar input_keyfile 62.Nm ssh-keygen 63.Fl e 64.Op Fl m Ar key_format 65.Op Fl f Ar input_keyfile 66.Nm ssh-keygen 67.Fl y 68.Op Fl f Ar input_keyfile 69.Nm ssh-keygen 70.Fl c 71.Op Fl P Ar passphrase 72.Op Fl C Ar comment 73.Op Fl f Ar keyfile 74.Nm ssh-keygen 75.Fl l 76.Op Fl f Ar input_keyfile 77.Nm ssh-keygen 78.Fl B 79.Op Fl f Ar input_keyfile 80.Nm ssh-keygen 81.Fl D Ar pkcs11 82.Nm ssh-keygen 83.Fl F Ar hostname 84.Op Fl f Ar known_hosts_file 85.Op Fl l 86.Nm ssh-keygen 87.Fl H 88.Op Fl f Ar known_hosts_file 89.Nm ssh-keygen 90.Fl R Ar hostname 91.Op Fl f Ar known_hosts_file 92.Nm ssh-keygen 93.Fl r Ar hostname 94.Op Fl f Ar input_keyfile 95.Op Fl g 96.Nm ssh-keygen 97.Fl G Ar output_file 98.Op Fl v 99.Op Fl b Ar bits 100.Op Fl M Ar memory 101.Op Fl S Ar start_point 102.Nm ssh-keygen 103.Fl T Ar output_file 104.Fl f Ar input_file 105.Op Fl v 106.Op Fl a Ar num_trials 107.Op Fl J Ar num_lines 108.Op Fl j Ar start_line 109.Op Fl K Ar checkpt 110.Op Fl W Ar generator 111.Nm ssh-keygen 112.Fl s Ar ca_key 113.Fl I Ar certificate_identity 114.Op Fl h 115.Op Fl n Ar principals 116.Op Fl O Ar option 117.Op Fl V Ar validity_interval 118.Op Fl z Ar serial_number 119.Ar 120.Nm ssh-keygen 121.Fl L 122.Op Fl f Ar input_keyfile 123.Nm ssh-keygen 124.Fl A 125.Ek 126.Sh DESCRIPTION 127.Nm 128generates, manages and converts authentication keys for 129.Xr ssh 1 . 130.Nm 131can create RSA keys for use by SSH protocol version 1 and DSA, ECDSA or RSA 132keys for use by SSH protocol version 2. 133The type of key to be generated is specified with the 134.Fl t 135option. 136If invoked without any arguments, 137.Nm 138will generate an RSA key for use in SSH protocol 2 connections. 139.Pp 140.Nm 141is also used to generate groups for use in Diffie-Hellman group 142exchange (DH-GEX). 143See the 144.Sx MODULI GENERATION 145section for details. 146.Pp 147Normally each user wishing to use SSH 148with public key authentication runs this once to create the authentication 149key in 150.Pa ~/.ssh/identity , 151.Pa ~/.ssh/id_ecdsa , 152.Pa ~/.ssh/id_dsa 153or 154.Pa ~/.ssh/id_rsa . 155Additionally, the system administrator may use this to generate host keys, 156as seen in 157.Pa /etc/rc . 158.Pp 159Normally this program generates the key and asks for a file in which 160to store the private key. 161The public key is stored in a file with the same name but 162.Dq .pub 163appended. 164The program also asks for a passphrase. 165The passphrase may be empty to indicate no passphrase 166(host keys must have an empty passphrase), or it may be a string of 167arbitrary length. 168A passphrase is similar to a password, except it can be a phrase with a 169series of words, punctuation, numbers, whitespace, or any string of 170characters you want. 171Good passphrases are 10-30 characters long, are 172not simple sentences or otherwise easily guessable (English 173prose has only 1-2 bits of entropy per character, and provides very bad 174passphrases), and contain a mix of upper and lowercase letters, 175numbers, and non-alphanumeric characters. 176The passphrase can be changed later by using the 177.Fl p 178option. 179.Pp 180There is no way to recover a lost passphrase. 181If the passphrase is lost or forgotten, a new key must be generated 182and the corresponding public key copied to other machines. 183.Pp 184For RSA1 keys, 185there is also a comment field in the key file that is only for 186convenience to the user to help identify the key. 187The comment can tell what the key is for, or whatever is useful. 188The comment is initialized to 189.Dq user@host 190when the key is created, but can be changed using the 191.Fl c 192option. 193.Pp 194After a key is generated, instructions below detail where the keys 195should be placed to be activated. 196.Pp 197The options are as follows: 198.Bl -tag -width Ds 199.It Fl A 200For each of the key types (rsa1, rsa, dsa and ecdsa) for which host keys 201do not exist, generate the host keys with the default key file path, 202an empty passphrase, default bits for the key type, and default comment. 203This is used by 204.Pa /etc/rc 205to generate new host keys. 206.It Fl a Ar trials 207Specifies the number of primality tests to perform when screening DH-GEX 208candidates using the 209.Fl T 210command. 211.It Fl B 212Show the bubblebabble digest of specified private or public key file. 213.It Fl b Ar bits 214Specifies the number of bits in the key to create. 215For RSA keys, the minimum size is 768 bits and the default is 2048 bits. 216Generally, 2048 bits is considered sufficient. 217DSA keys must be exactly 1024 bits as specified by FIPS 186-2. 218For ECDSA keys, the 219.Fl b 220flag determines the key length by selecting from one of three elliptic 221curve sizes: 256, 384 or 521 bits. 222Attempting to use bit lengths other than these three values for ECDSA keys 223will fail. 224.It Fl C Ar comment 225Provides a new comment. 226.It Fl c 227Requests changing the comment in the private and public key files. 228This operation is only supported for RSA1 keys. 229The program will prompt for the file containing the private keys, for 230the passphrase if the key has one, and for the new comment. 231.It Fl D Ar pkcs11 232Download the RSA public keys provided by the PKCS#11 shared library 233.Ar pkcs11 . 234When used in combination with 235.Fl s , 236this option indicates that a CA key resides in a PKCS#11 token (see the 237.Sx CERTIFICATES 238section for details). 239.It Fl e 240This option will read a private or public OpenSSH key file and 241print to stdout the key in one of the formats specified by the 242.Fl m 243option. 244The default export format is 245.Dq RFC4716 . 246This option allows exporting OpenSSH keys for use by other programs, including 247several commercial SSH implementations. 248.It Fl F Ar hostname 249Search for the specified 250.Ar hostname 251in a 252.Pa known_hosts 253file, listing any occurrences found. 254This option is useful to find hashed host names or addresses and may also be 255used in conjunction with the 256.Fl H 257option to print found keys in a hashed format. 258.It Fl f Ar filename 259Specifies the filename of the key file. 260.It Fl G Ar output_file 261Generate candidate primes for DH-GEX. 262These primes must be screened for 263safety (using the 264.Fl T 265option) before use. 266.It Fl g 267Use generic DNS format when printing fingerprint resource records using the 268.Fl r 269command. 270.It Fl H 271Hash a 272.Pa known_hosts 273file. 274This replaces all hostnames and addresses with hashed representations 275within the specified file; the original content is moved to a file with 276a .old suffix. 277These hashes may be used normally by 278.Nm ssh 279and 280.Nm sshd , 281but they do not reveal identifying information should the file's contents 282be disclosed. 283This option will not modify existing hashed hostnames and is therefore safe 284to use on files that mix hashed and non-hashed names. 285.It Fl h 286When signing a key, create a host certificate instead of a user 287certificate. 288Please see the 289.Sx CERTIFICATES 290section for details. 291.It Fl I Ar certificate_identity 292Specify the key identity when signing a public key. 293Please see the 294.Sx CERTIFICATES 295section for details. 296.It Fl i 297This option will read an unencrypted private (or public) key file 298in the format specified by the 299.Fl m 300option and print an OpenSSH compatible private 301(or public) key to stdout. 302.It Fl J Ar num_lines 303Exit after screening the specified number of lines 304while performing DH candidate screening using the 305.Fl T 306option. 307.It Fl j Ar start_line 308Start screening at the specified line number 309while performing DH candidate screening using the 310.Fl T 311option. 312.It Fl K Ar checkpt 313Write the last line processed to the file 314.Ar checkpt 315while performing DH candidate screening using the 316.Fl T 317option. 318This will be used to skip lines in the input file that have already been 319processed if the job is restarted. 320This option allows importing keys from other software, including several 321commercial SSH implementations. 322The default import format is 323.Dq RFC4716 . 324.It Fl L 325Prints the contents of a certificate. 326.It Fl l 327Show fingerprint of specified public key file. 328Private RSA1 keys are also supported. 329For RSA and DSA keys 330.Nm 331tries to find the matching public key file and prints its fingerprint. 332If combined with 333.Fl v , 334an ASCII art representation of the key is supplied with the fingerprint. 335.It Fl M Ar memory 336Specify the amount of memory to use (in megabytes) when generating 337candidate moduli for DH-GEX. 338.It Fl m Ar key_format 339Specify a key format for the 340.Fl i 341(import) or 342.Fl e 343(export) conversion options. 344The supported key formats are: 345.Dq RFC4716 346(RFC 4716/SSH2 public or private key), 347.Dq PKCS8 348(PEM PKCS8 public key) 349or 350.Dq PEM 351(PEM public key). 352The default conversion format is 353.Dq RFC4716 . 354.It Fl N Ar new_passphrase 355Provides the new passphrase. 356.It Fl n Ar principals 357Specify one or more principals (user or host names) to be included in 358a certificate when signing a key. 359Multiple principals may be specified, separated by commas. 360Please see the 361.Sx CERTIFICATES 362section for details. 363.It Fl O Ar option 364Specify a certificate option when signing a key. 365This option may be specified multiple times. 366Please see the 367.Sx CERTIFICATES 368section for details. 369The options that are valid for user certificates are: 370.Bl -tag -width Ds 371.It Ic clear 372Clear all enabled permissions. 373This is useful for clearing the default set of permissions so permissions may 374be added individually. 375.It Ic force-command Ns = Ns Ar command 376Forces the execution of 377.Ar command 378instead of any shell or command specified by the user when 379the certificate is used for authentication. 380.It Ic no-agent-forwarding 381Disable 382.Xr ssh-agent 1 383forwarding (permitted by default). 384.It Ic no-port-forwarding 385Disable port forwarding (permitted by default). 386.It Ic no-pty 387Disable PTY allocation (permitted by default). 388.It Ic no-user-rc 389Disable execution of 390.Pa ~/.ssh/rc 391by 392.Xr sshd 8 393(permitted by default). 394.It Ic no-x11-forwarding 395Disable X11 forwarding (permitted by default). 396.It Ic permit-agent-forwarding 397Allows 398.Xr ssh-agent 1 399forwarding. 400.It Ic permit-port-forwarding 401Allows port forwarding. 402.It Ic permit-pty 403Allows PTY allocation. 404.It Ic permit-user-rc 405Allows execution of 406.Pa ~/.ssh/rc 407by 408.Xr sshd 8 . 409.It Ic permit-x11-forwarding 410Allows X11 forwarding. 411.It Ic source-address Ns = Ns Ar address_list 412Restrict the source addresses from which the certificate is considered valid. 413The 414.Ar address_list 415is a comma-separated list of one or more address/netmask pairs in CIDR 416format. 417.El 418.Pp 419At present, no options are valid for host keys. 420.It Fl P Ar passphrase 421Provides the (old) passphrase. 422.It Fl p 423Requests changing the passphrase of a private key file instead of 424creating a new private key. 425The program will prompt for the file 426containing the private key, for the old passphrase, and twice for the 427new passphrase. 428.It Fl q 429Silence 430.Nm ssh-keygen . 431.It Fl R Ar hostname 432Removes all keys belonging to 433.Ar hostname 434from a 435.Pa known_hosts 436file. 437This option is useful to delete hashed hosts (see the 438.Fl H 439option above). 440.It Fl r Ar hostname 441Print the SSHFP fingerprint resource record named 442.Ar hostname 443for the specified public key file. 444.It Fl S Ar start 445Specify start point (in hex) when generating candidate moduli for DH-GEX. 446.It Fl s Ar ca_key 447Certify (sign) a public key using the specified CA key. 448Please see the 449.Sx CERTIFICATES 450section for details. 451.It Fl T Ar output_file 452Test DH group exchange candidate primes (generated using the 453.Fl G 454option) for safety. 455.It Fl t Ar type 456Specifies the type of key to create. 457The possible values are 458.Dq rsa1 459for protocol version 1 and 460.Dq dsa , 461.Dq ecdsa 462or 463.Dq rsa 464for protocol version 2. 465.It Fl V Ar validity_interval 466Specify a validity interval when signing a certificate. 467A validity interval may consist of a single time, indicating that the 468certificate is valid beginning now and expiring at that time, or may consist 469of two times separated by a colon to indicate an explicit time interval. 470The start time may be specified as a date in YYYYMMDD format, a time 471in YYYYMMDDHHMMSS format or a relative time (to the current time) consisting 472of a minus sign followed by a relative time in the format described in the 473.Sx TIME FORMATS 474section of 475.Xr sshd_config 5 . 476The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMMSS time or 477a relative time starting with a plus character. 478.Pp 479For example: 480.Dq +52w1d 481(valid from now to 52 weeks and one day from now), 482.Dq -4w:+4w 483(valid from four weeks ago to four weeks from now), 484.Dq 20100101123000:20110101123000 485(valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011), 486.Dq -1d:20110101 487(valid from yesterday to midnight, January 1st, 2011). 488.It Fl v 489Verbose mode. 490Causes 491.Nm 492to print debugging messages about its progress. 493This is helpful for debugging moduli generation. 494Multiple 495.Fl v 496options increase the verbosity. 497The maximum is 3. 498.It Fl W Ar generator 499Specify desired generator when testing candidate moduli for DH-GEX. 500.It Fl y 501This option will read a private 502OpenSSH format file and print an OpenSSH public key to stdout. 503.It Fl z Ar serial_number 504Specifies a serial number to be embedded in the certificate to distinguish 505this certificate from others from the same CA. 506The default serial number is zero. 507.El 508.Sh MODULI GENERATION 509.Nm 510may be used to generate groups for the Diffie-Hellman Group Exchange 511(DH-GEX) protocol. 512Generating these groups is a two-step process: first, candidate 513primes are generated using a fast, but memory intensive process. 514These candidate primes are then tested for suitability (a CPU-intensive 515process). 516.Pp 517Generation of primes is performed using the 518.Fl G 519option. 520The desired length of the primes may be specified by the 521.Fl b 522option. 523For example: 524.Pp 525.Dl # ssh-keygen -G moduli-2048.candidates -b 2048 526.Pp 527By default, the search for primes begins at a random point in the 528desired length range. 529This may be overridden using the 530.Fl S 531option, which specifies a different start point (in hex). 532.Pp 533Once a set of candidates have been generated, they must be screened for 534suitability. 535This may be performed using the 536.Fl T 537option. 538In this mode 539.Nm 540will read candidates from standard input (or a file specified using the 541.Fl f 542option). 543For example: 544.Pp 545.Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates 546.Pp 547By default, each candidate will be subjected to 100 primality tests. 548This may be overridden using the 549.Fl a 550option. 551The DH generator value will be chosen automatically for the 552prime under consideration. 553If a specific generator is desired, it may be requested using the 554.Fl W 555option. 556Valid generator values are 2, 3, and 5. 557.Pp 558Screened DH groups may be installed in 559.Pa /etc/moduli . 560It is important that this file contains moduli of a range of bit lengths and 561that both ends of a connection share common moduli. 562.Sh CERTIFICATES 563.Nm 564supports signing of keys to produce certificates that may be used for 565user or host authentication. 566Certificates consist of a public key, some identity information, zero or 567more principal (user or host) names and a set of options that 568are signed by a Certification Authority (CA) key. 569Clients or servers may then trust only the CA key and verify its signature 570on a certificate rather than trusting many user/host keys. 571Note that OpenSSH certificates are a different, and much simpler, format to 572the X.509 certificates used in 573.Xr ssl 8 . 574.Pp 575.Nm 576supports two types of certificates: user and host. 577User certificates authenticate users to servers, whereas host certificates 578authenticate server hosts to users. 579To generate a user certificate: 580.Pp 581.Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub 582.Pp 583The resultant certificate will be placed in 584.Pa /path/to/user_key-cert.pub . 585A host certificate requires the 586.Fl h 587option: 588.Pp 589.Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub 590.Pp 591The host certificate will be output to 592.Pa /path/to/host_key-cert.pub . 593.Pp 594It is possible to sign using a CA key stored in a PKCS#11 token by 595providing the token library using 596.Fl D 597and identifying the CA key by providing its public half as an argument 598to 599.Fl s : 600.Pp 601.Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id host_key.pub 602.Pp 603In all cases, 604.Ar key_id 605is a "key identifier" that is logged by the server when the certificate 606is used for authentication. 607.Pp 608Certificates may be limited to be valid for a set of principal (user/host) 609names. 610By default, generated certificates are valid for all users or hosts. 611To generate a certificate for a specified set of principals: 612.Pp 613.Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub 614.Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain user_key.pub" 615.Pp 616Additional limitations on the validity and use of user certificates may 617be specified through certificate options. 618A certificate option may disable features of the SSH session, may be 619valid only when presented from particular source addresses or may 620force the use of a specific command. 621For a list of valid certificate options, see the documentation for the 622.Fl O 623option above. 624.Pp 625Finally, certificates may be defined with a validity lifetime. 626The 627.Fl V 628option allows specification of certificate start and end times. 629A certificate that is presented at a time outside this range will not be 630considered valid. 631By default, certificates have a maximum validity interval. 632.Pp 633For certificates to be used for user or host authentication, the CA 634public key must be trusted by 635.Xr sshd 8 636or 637.Xr ssh 1 . 638Please refer to those manual pages for details. 639.Sh FILES 640.Bl -tag -width Ds -compact 641.It Pa ~/.ssh/identity 642Contains the protocol version 1 RSA authentication identity of the user. 643This file should not be readable by anyone but the user. 644It is possible to 645specify a passphrase when generating the key; that passphrase will be 646used to encrypt the private part of this file using 3DES. 647This file is not automatically accessed by 648.Nm 649but it is offered as the default file for the private key. 650.Xr ssh 1 651will read this file when a login attempt is made. 652.Pp 653.It Pa ~/.ssh/identity.pub 654Contains the protocol version 1 RSA public key for authentication. 655The contents of this file should be added to 656.Pa ~/.ssh/authorized_keys 657on all machines 658where the user wishes to log in using RSA authentication. 659There is no need to keep the contents of this file secret. 660.Pp 661.It Pa ~/.ssh/id_dsa 662.It Pa ~/.ssh/id_ecdsa 663.It Pa ~/.ssh/id_rsa 664Contains the protocol version 2 DSA, ECDSA or RSA authentication identity of the user. 665This file should not be readable by anyone but the user. 666It is possible to 667specify a passphrase when generating the key; that passphrase will be 668used to encrypt the private part of this file using 128-bit AES. 669This file is not automatically accessed by 670.Nm 671but it is offered as the default file for the private key. 672.Xr ssh 1 673will read this file when a login attempt is made. 674.Pp 675.It Pa ~/.ssh/id_dsa.pub 676.It Pa ~/.ssh/id_ecdsa.pub 677.It Pa ~/.ssh/id_rsa.pub 678Contains the protocol version 2 DSA, ECDSA or RSA public key for authentication. 679The contents of this file should be added to 680.Pa ~/.ssh/authorized_keys 681on all machines 682where the user wishes to log in using public key authentication. 683There is no need to keep the contents of this file secret. 684.Pp 685.It Pa /etc/moduli 686Contains Diffie-Hellman groups used for DH-GEX. 687The file format is described in 688.Xr moduli 5 . 689.El 690.Sh SEE ALSO 691.Xr ssh 1 , 692.Xr ssh-add 1 , 693.Xr ssh-agent 1 , 694.Xr moduli 5 , 695.Xr sshd 8 696.Rs 697.%R RFC 4716 698.%T "The Secure Shell (SSH) Public Key File Format" 699.%D 2006 700.Re 701.Sh AUTHORS 702OpenSSH is a derivative of the original and free 703ssh 1.2.12 release by Tatu Ylonen. 704Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 705Theo de Raadt and Dug Song 706removed many bugs, re-added newer features and 707created OpenSSH. 708Markus Friedl contributed the support for SSH 709protocol versions 1.5 and 2.0. 710