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