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