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