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