1.\" $OpenBSD: ssh-keygen.1,v 1.203 2020/04/03 02:26:56 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 3 2020 $ 39.Dt SSH-KEYGEN 1 40.Os 41.Sh NAME 42.Nm ssh-keygen 43.Nd OpenSSH authentication key utility 44.Sh SYNOPSIS 45.Nm ssh-keygen 46.Op Fl q 47.Op Fl b Ar bits 48.Op Fl C Ar comment 49.Op Fl f Ar output_keyfile 50.Op Fl m Ar format 51.Op Fl t Cm dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa 52.Op Fl N Ar new_passphrase 53.Op Fl O Ar option 54.Op Fl w Ar provider 55.Nm ssh-keygen 56.Fl p 57.Op Fl f Ar keyfile 58.Op Fl m Ar format 59.Op Fl N Ar new_passphrase 60.Op Fl P Ar old_passphrase 61.Nm ssh-keygen 62.Fl i 63.Op Fl f Ar input_keyfile 64.Op Fl m Ar key_format 65.Nm ssh-keygen 66.Fl e 67.Op Fl f Ar input_keyfile 68.Op Fl m Ar key_format 69.Nm ssh-keygen 70.Fl y 71.Op Fl f Ar input_keyfile 72.Nm ssh-keygen 73.Fl c 74.Op Fl C Ar comment 75.Op Fl f Ar keyfile 76.Op Fl P Ar passphrase 77.Nm ssh-keygen 78.Fl l 79.Op Fl v 80.Op Fl E Ar fingerprint_hash 81.Op Fl f Ar input_keyfile 82.Nm ssh-keygen 83.Fl B 84.Op Fl f Ar input_keyfile 85.Nm ssh-keygen 86.Fl D Ar pkcs11 87.Nm ssh-keygen 88.Fl F Ar hostname 89.Op Fl lv 90.Op Fl f Ar known_hosts_file 91.Nm ssh-keygen 92.Fl H 93.Op Fl f Ar known_hosts_file 94.Nm ssh-keygen 95.Fl K 96.Op Fl w Ar provider 97.Nm ssh-keygen 98.Fl R Ar hostname 99.Op Fl f Ar known_hosts_file 100.Nm ssh-keygen 101.Fl r Ar hostname 102.Op Fl g 103.Op Fl f Ar input_keyfile 104.Nm ssh-keygen 105.Fl M Cm generate 106.Op Fl O Ar option 107.Ar output_file 108.Nm ssh-keygen 109.Fl M Cm screen 110.Op Fl f Ar input_file 111.Op Fl O Ar option 112.Ar output_file 113.Nm ssh-keygen 114.Fl I Ar certificate_identity 115.Fl s Ar ca_key 116.Op Fl hU 117.Op Fl D Ar pkcs11_provider 118.Op Fl n Ar principals 119.Op Fl O Ar option 120.Op Fl V Ar validity_interval 121.Op Fl z Ar serial_number 122.Ar 123.Nm ssh-keygen 124.Fl L 125.Op Fl f Ar input_keyfile 126.Nm ssh-keygen 127.Fl A 128.Op Fl f Ar prefix_path 129.Nm ssh-keygen 130.Fl k 131.Fl f Ar krl_file 132.Op Fl u 133.Op Fl s Ar ca_public 134.Op Fl z Ar version_number 135.Ar 136.Nm ssh-keygen 137.Fl Q 138.Op Fl l 139.Fl f Ar krl_file 140.Ar 141.Nm ssh-keygen 142.Fl Y Cm find-principals 143.Fl s Ar signature_file 144.Fl f Ar allowed_signers_file 145.Nm ssh-keygen 146.Fl Y Cm check-novalidate 147.Fl n Ar namespace 148.Fl s Ar signature_file 149.Nm ssh-keygen 150.Fl Y Cm sign 151.Fl f Ar key_file 152.Fl n Ar namespace 153.Ar 154.Nm ssh-keygen 155.Fl Y Cm verify 156.Fl f Ar allowed_signers_file 157.Fl I Ar signer_identity 158.Fl n Ar namespace 159.Fl s Ar signature_file 160.Op Fl r Ar revocation_file 161.Sh DESCRIPTION 162.Nm 163generates, manages and converts authentication keys for 164.Xr ssh 1 . 165.Nm 166can create keys for use by SSH protocol version 2. 167.Pp 168The type of key to be generated is specified with the 169.Fl t 170option. 171If invoked without any arguments, 172.Nm 173will generate an RSA key. 174.Pp 175.Nm 176is also used to generate groups for use in Diffie-Hellman group 177exchange (DH-GEX). 178See the 179.Sx MODULI GENERATION 180section for details. 181.Pp 182Finally, 183.Nm 184can be used to generate and update Key Revocation Lists, and to test whether 185given keys have been revoked by one. 186See the 187.Sx KEY REVOCATION LISTS 188section for details. 189.Pp 190Normally each user wishing to use SSH 191with public key authentication runs this once to create the authentication 192key in 193.Pa ~/.ssh/id_dsa , 194.Pa ~/.ssh/id_ecdsa , 195.Pa ~/.ssh/id_ecdsa_sk , 196.Pa ~/.ssh/id_ed25519 , 197.Pa ~/.ssh/id_ed25519_sk 198or 199.Pa ~/.ssh/id_rsa . 200Additionally, the system administrator may use this to generate host keys, 201as seen in 202.Pa /etc/rc . 203.Pp 204Normally this program generates the key and asks for a file in which 205to store the private key. 206The public key is stored in a file with the same name but 207.Dq .pub 208appended. 209The program also asks for a passphrase. 210The passphrase may be empty to indicate no passphrase 211(host keys must have an empty passphrase), or it may be a string of 212arbitrary length. 213A passphrase is similar to a password, except it can be a phrase with a 214series of words, punctuation, numbers, whitespace, or any string of 215characters you want. 216Good passphrases are 10-30 characters long, are 217not simple sentences or otherwise easily guessable (English 218prose has only 1-2 bits of entropy per character, and provides very bad 219passphrases), and contain a mix of upper and lowercase letters, 220numbers, and non-alphanumeric characters. 221The passphrase can be changed later by using the 222.Fl p 223option. 224.Pp 225There is no way to recover a lost passphrase. 226If the passphrase is lost or forgotten, a new key must be generated 227and the corresponding public key copied to other machines. 228.Pp 229.Nm 230will by default write keys in an OpenSSH-specific format. 231This format is preferred as it offers better protection for 232keys at rest as well as allowing storage of key comments within 233the private key file itself. 234The key comment may be useful to help identify the key. 235The comment is initialized to 236.Dq user@host 237when the key is created, but can be changed using the 238.Fl c 239option. 240.Pp 241It is still possible for 242.Nm 243to write the previously-used PEM format private keys using the 244.Fl m 245flag. 246This may be used when generating new keys, and existing new-format 247keys may be converted using this option in conjunction with the 248.Fl p 249(change passphrase) flag. 250.Pp 251After a key is generated, instructions below detail where the keys 252should be placed to be activated. 253.Pp 254The options are as follows: 255.Bl -tag -width Ds 256.It Fl A 257For each of the key types (rsa, dsa, ecdsa and ed25519) 258for which host keys 259do not exist, generate the host keys with the default key file path, 260an empty passphrase, default bits for the key type, and default comment. 261If 262.Fl f 263has also been specified, its argument is used as a prefix to the 264default path for the resulting host key files. 265This is used by 266.Pa /etc/rc 267to generate new host keys. 268.It Fl a Ar rounds 269When saving a private key, this option specifies the number of KDF 270(key derivation function) rounds used. 271Higher numbers result in slower passphrase verification and increased 272resistance to brute-force password cracking (should the keys be stolen). 273.It Fl B 274Show the bubblebabble digest of specified private or public key file. 275.It Fl b Ar bits 276Specifies the number of bits in the key to create. 277For RSA keys, the minimum size is 1024 bits and the default is 3072 bits. 278Generally, 3072 bits is considered sufficient. 279DSA keys must be exactly 1024 bits as specified by FIPS 186-2. 280For ECDSA keys, the 281.Fl b 282flag determines the key length by selecting from one of three elliptic 283curve sizes: 256, 384 or 521 bits. 284Attempting to use bit lengths other than these three values for ECDSA keys 285will fail. 286ECDSA-SK, Ed25519 and Ed25519-SK keys have a fixed length and the 287.Fl b 288flag will be ignored. 289.It Fl C Ar comment 290Provides a new comment. 291.It Fl c 292Requests changing the comment in the private and public key files. 293The program will prompt for the file containing the private keys, for 294the passphrase if the key has one, and for the new comment. 295.It Fl D Ar pkcs11 296Download the public keys provided by the PKCS#11 shared library 297.Ar pkcs11 . 298When used in combination with 299.Fl s , 300this option indicates that a CA key resides in a PKCS#11 token (see the 301.Sx CERTIFICATES 302section for details). 303.It Fl E Ar fingerprint_hash 304Specifies the hash algorithm used when displaying key fingerprints. 305Valid options are: 306.Dq md5 307and 308.Dq sha256 . 309The default is 310.Dq sha256 . 311.It Fl e 312This option will read a private or public OpenSSH key file and 313print to stdout a public key in one of the formats specified by the 314.Fl m 315option. 316The default export format is 317.Dq RFC4716 . 318This option allows exporting OpenSSH keys for use by other programs, including 319several commercial SSH implementations. 320.It Fl F Ar hostname | [hostname]:port 321Search for the specified 322.Ar hostname 323(with optional port number) 324in a 325.Pa known_hosts 326file, listing any occurrences found. 327This option is useful to find hashed host names or addresses and may also be 328used in conjunction with the 329.Fl H 330option to print found keys in a hashed format. 331.It Fl f Ar filename 332Specifies the filename of the key file. 333.It Fl g 334Use generic DNS format when printing fingerprint resource records using the 335.Fl r 336command. 337.It Fl H 338Hash a 339.Pa known_hosts 340file. 341This replaces all hostnames and addresses with hashed representations 342within the specified file; the original content is moved to a file with 343a .old suffix. 344These hashes may be used normally by 345.Nm ssh 346and 347.Nm sshd , 348but they do not reveal identifying information should the file's contents 349be disclosed. 350This option will not modify existing hashed hostnames and is therefore safe 351to use on files that mix hashed and non-hashed names. 352.It Fl h 353When signing a key, create a host certificate instead of a user 354certificate. 355Please see the 356.Sx CERTIFICATES 357section for details. 358.It Fl I Ar certificate_identity 359Specify the key identity when signing a public key. 360Please see the 361.Sx CERTIFICATES 362section for details. 363.It Fl i 364This option will read an unencrypted private (or public) key file 365in the format specified by the 366.Fl m 367option and print an OpenSSH compatible private 368(or public) key to stdout. 369This option allows importing keys from other software, including several 370commercial SSH implementations. 371The default import format is 372.Dq RFC4716 . 373.It Fl K 374Download resident keys from a FIDO authenticator. 375Public and private key files will be written to the current directory for 376each downloaded key. 377.It Fl k 378Generate a KRL file. 379In this mode, 380.Nm 381will generate a KRL file at the location specified via the 382.Fl f 383flag that revokes every key or certificate presented on the command line. 384Keys/certificates to be revoked may be specified by public key file or 385using the format described in the 386.Sx KEY REVOCATION LISTS 387section. 388.It Fl L 389Prints the contents of one or more certificates. 390.It Fl l 391Show fingerprint of specified public key file. 392For RSA and DSA keys 393.Nm 394tries to find the matching public key file and prints its fingerprint. 395If combined with 396.Fl v , 397a visual ASCII art representation of the key is supplied with the 398fingerprint. 399.It Fl M Cm generate 400Generate candidate Diffie-Hellman Group Exchange (DH-GEX) parameters for 401eventual use by the 402.Sq diffie-hellman-group-exchange-* 403key exchange methods. 404The numbers generated by this operation must be further screened before 405use. 406See the 407.Sx MODULI GENERATION 408section for more information. 409.It Fl M Cm screen 410Screen candidate parameters for Diffie-Hellman Group Exchange. 411This will accept a list of candidate numbers and test that they are 412safe (Sophie Germain) primes with acceptable group generators. 413The results of this operation may be added to the 414.Pa /etc/moduli 415file. 416See the 417.Sx MODULI GENERATION 418section for more information. 419.It Fl m Ar key_format 420Specify a key format for key generation, the 421.Fl i 422(import), 423.Fl e 424(export) conversion options, and the 425.Fl p 426change passphrase operation. 427The latter may be used to convert between OpenSSH private key and PEM 428private key formats. 429The supported key formats are: 430.Dq RFC4716 431(RFC 4716/SSH2 public or private key), 432.Dq PKCS8 433(PKCS8 public or private key) 434or 435.Dq PEM 436(PEM public key). 437By default OpenSSH will write newly-generated private keys in its own 438format, but when converting public keys for export the default format is 439.Dq RFC4716 . 440Setting a format of 441.Dq PEM 442when generating or updating a supported private key type will cause the 443key to be stored in the legacy PEM private key format. 444.It Fl N Ar new_passphrase 445Provides the new passphrase. 446.It Fl n Ar principals 447Specify one or more principals (user or host names) to be included in 448a certificate when signing a key. 449Multiple principals may be specified, separated by commas. 450Please see the 451.Sx CERTIFICATES 452section for details. 453.It Fl O Ar option 454Specify a key/value option. 455These are specific to the operation that 456.Nm 457has been requested to perform. 458.Pp 459When signing certificates, one of the options listed in the 460.Sx CERTIFICATES 461section may be specified here. 462.Pp 463When performing moduli generation or screening, one of the options 464listed in the 465.Sx MODULI GENERATION 466section may be specified. 467.Pp 468When generating a key that will be hosted on a FIDO authenticator, 469this flag may be used to specify key-specific options. 470Those supported at present are: 471.Bl -tag -width Ds 472.It Cm application 473Override the default FIDO application/origin string of 474.Dq ssh: . 475This may be useful when generating host or domain-specific resident keys. 476The specified application string must begin with 477.Dq ssh: . 478.It Cm challenge Ns = Ns Ar path 479Specifies a path to a challenge string that will be passed to the 480FIDO token during key generation. 481The challenge string may be used as part of an out-of-band 482protocol for key enrollment 483(a random challenge is used by default). 484.It Cm device 485Explicitly specify a 486.Xr fido 4 487device to use, rather than letting the token middleware select one. 488.It Cm no-touch-required 489Indicate that the generated private key should not require touch 490events (user presence) when making signatures. 491Note that 492.Xr sshd 8 493will refuse such signatures by default, unless overridden via 494an authorized_keys option. 495.It Cm resident 496Indicate that the key should be stored on the FIDO authenticator itself. 497Resident keys may be supported on FIDO2 tokens and typically require that 498a PIN be set on the token prior to generation. 499Resident keys may be loaded off the token using 500.Xr ssh-add 1 . 501.It Cm user 502A username to be associated with a resident key, 503overriding the empty default username. 504Specifying a username may be useful when generating multiple resident keys 505for the same application name. 506.It Cm write-attestation Ns = Ns Ar path 507May be used at key generation time to record the attestation certificate 508returned from FIDO tokens during key generation. 509By default this information is discarded. 510.El 511.Pp 512The 513.Fl O 514option may be specified multiple times. 515.It Fl P Ar passphrase 516Provides the (old) passphrase. 517.It Fl p 518Requests changing the passphrase of a private key file instead of 519creating a new private key. 520The program will prompt for the file 521containing the private key, for the old passphrase, and twice for the 522new passphrase. 523.It Fl Q 524Test whether keys have been revoked in a KRL. 525If the 526.Fl l 527option is also specified then the contents of the KRL will be printed. 528.It Fl q 529Silence 530.Nm ssh-keygen . 531.It Fl R Ar hostname | [hostname]:port 532Removes all keys belonging to the specified 533.Ar hostname 534(with optional port number) 535from a 536.Pa known_hosts 537file. 538This option is useful to delete hashed hosts (see the 539.Fl H 540option above). 541.It Fl r Ar hostname 542Print the SSHFP fingerprint resource record named 543.Ar hostname 544for the specified public key file. 545.It Fl s Ar ca_key 546Certify (sign) a public key using the specified CA key. 547Please see the 548.Sx CERTIFICATES 549section for details. 550.Pp 551When generating a KRL, 552.Fl s 553specifies a path to a CA public key file used to revoke certificates directly 554by key ID or serial number. 555See the 556.Sx KEY REVOCATION LISTS 557section for details. 558.It Fl t Cm dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa 559Specifies the type of key to create. 560The possible values are 561.Dq dsa , 562.Dq ecdsa , 563.Dq ecdsa-sk , 564.Dq ed25519 , 565.Dq ed25519-sk , 566or 567.Dq rsa . 568.Pp 569This flag may also be used to specify the desired signature type when 570signing certificates using an RSA CA key. 571The available RSA signature variants are 572.Dq ssh-rsa 573(SHA1 signatures, not recommended), 574.Dq rsa-sha2-256 , 575and 576.Dq rsa-sha2-512 577(the default). 578.It Fl U 579When used in combination with 580.Fl s , 581this option indicates that a CA key resides in a 582.Xr ssh-agent 1 . 583See the 584.Sx CERTIFICATES 585section for more information. 586.It Fl u 587Update a KRL. 588When specified with 589.Fl k , 590keys listed via the command line are added to the existing KRL rather than 591a new KRL being created. 592.It Fl V Ar validity_interval 593Specify a validity interval when signing a certificate. 594A validity interval may consist of a single time, indicating that the 595certificate is valid beginning now and expiring at that time, or may consist 596of two times separated by a colon to indicate an explicit time interval. 597.Pp 598The start time may be specified as the string 599.Dq always 600to indicate the certificate has no specified start time, 601a date in YYYYMMDD format, a time in YYYYMMDDHHMM[SS] format, 602a relative time (to the current time) consisting of a minus sign followed by 603an interval in the format described in the 604TIME FORMATS section of 605.Xr sshd_config 5 . 606.Pp 607The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMM[SS] time, 608a relative time starting with a plus character or the string 609.Dq forever 610to indicate that the certificate has no expiry date. 611.Pp 612For example: 613.Dq +52w1d 614(valid from now to 52 weeks and one day from now), 615.Dq -4w:+4w 616(valid from four weeks ago to four weeks from now), 617.Dq 20100101123000:20110101123000 618(valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011), 619.Dq -1d:20110101 620(valid from yesterday to midnight, January 1st, 2011). 621.Dq -1m:forever 622(valid from one minute ago and never expiring). 623.It Fl v 624Verbose mode. 625Causes 626.Nm 627to print debugging messages about its progress. 628This is helpful for debugging moduli generation. 629Multiple 630.Fl v 631options increase the verbosity. 632The maximum is 3. 633.It Fl w Ar provider 634Specifies a path to a library that will be used when creating 635FIDO authenticator-hosted keys, overriding the default of using 636the internal USB HID support. 637.It Fl Y Cm find-principals 638Find the principal(s) associated with the public key of a signature, 639provided using the 640.Fl s 641flag in an authorized signers file provided using the 642.Fl f 643flag. 644The format of the allowed signers file is documented in the 645.Sx ALLOWED SIGNERS 646section below. 647If one or more matching principals are found, they are returned on 648standard output. 649.It Fl Y Cm check-novalidate 650Checks that a signature generated using 651.Nm 652.Fl Y Cm sign 653has a valid structure. 654This does not validate if a signature comes from an authorized signer. 655When testing a signature, 656.Nm 657accepts a message on standard input and a signature namespace using 658.Fl n . 659A file containing the corresponding signature must also be supplied using the 660.Fl s 661flag. 662Successful testing of the signature is signalled by 663.Nm 664returning a zero exit status. 665.It Fl Y Cm sign 666Cryptographically sign a file or some data using a SSH key. 667When signing, 668.Nm 669accepts zero or more files to sign on the command-line - if no files 670are specified then 671.Nm 672will sign data presented on standard input. 673Signatures are written to the path of the input file with 674.Dq .sig 675appended, or to standard output if the message to be signed was read from 676standard input. 677.Pp 678The key used for signing is specified using the 679.Fl f 680option and may refer to either a private key, or a public key with the private 681half available via 682.Xr ssh-agent 1 . 683An additional signature namespace, used to prevent signature confusion across 684different domains of use (e.g. file signing vs email signing) must be provided 685via the 686.Fl n 687flag. 688Namespaces are arbitrary strings, and may include: 689.Dq file 690for file signing, 691.Dq email 692for email signing. 693For custom uses, it is recommended to use names following a 694NAMESPACE@YOUR.DOMAIN pattern to generate unambiguous namespaces. 695.It Fl Y Cm verify 696Request to verify a signature generated using 697.Nm 698.Fl Y Cm sign 699as described above. 700When verifying a signature, 701.Nm 702accepts a message on standard input and a signature namespace using 703.Fl n . 704A file containing the corresponding signature must also be supplied using the 705.Fl s 706flag, along with the identity of the signer using 707.Fl I 708and a list of allowed signers via the 709.Fl f 710flag. 711The format of the allowed signers file is documented in the 712.Sx ALLOWED SIGNERS 713section below. 714A file containing revoked keys can be passed using the 715.Fl r 716flag. 717The revocation file may be a KRL or a one-per-line list of public keys. 718Successful verification by an authorized signer is signalled by 719.Nm 720returning a zero exit status. 721.It Fl y 722This option will read a private 723OpenSSH format file and print an OpenSSH public key to stdout. 724.It Fl z Ar serial_number 725Specifies a serial number to be embedded in the certificate to distinguish 726this certificate from others from the same CA. 727If the 728.Ar serial_number 729is prefixed with a 730.Sq + 731character, then the serial number will be incremented for each certificate 732signed on a single command-line. 733The default serial number is zero. 734.Pp 735When generating a KRL, the 736.Fl z 737flag is used to specify a KRL version number. 738.El 739.Sh MODULI GENERATION 740.Nm 741may be used to generate groups for the Diffie-Hellman Group Exchange 742(DH-GEX) protocol. 743Generating these groups is a two-step process: first, candidate 744primes are generated using a fast, but memory intensive process. 745These candidate primes are then tested for suitability (a CPU-intensive 746process). 747.Pp 748Generation of primes is performed using the 749.Fl M Cm generate 750option. 751The desired length of the primes may be specified by the 752.Fl O Cm bits 753option. 754For example: 755.Pp 756.Dl # ssh-keygen -M generate -O bits=2048 moduli-2048.candidates 757.Pp 758By default, the search for primes begins at a random point in the 759desired length range. 760This may be overridden using the 761.Fl O Cm start 762option, which specifies a different start point (in hex). 763.Pp 764Once a set of candidates have been generated, they must be screened for 765suitability. 766This may be performed using the 767.Fl M Cm screen 768option. 769In this mode 770.Nm 771will read candidates from standard input (or a file specified using the 772.Fl f 773option). 774For example: 775.Pp 776.Dl # ssh-keygen -M screen -f moduli-2048.candidates moduli-2048 777.Pp 778By default, each candidate will be subjected to 100 primality tests. 779This may be overridden using the 780.Fl O Cm prime-tests 781option. 782The DH generator value will be chosen automatically for the 783prime under consideration. 784If a specific generator is desired, it may be requested using the 785.Fl O Cm generator 786option. 787Valid generator values are 2, 3, and 5. 788.Pp 789Screened DH groups may be installed in 790.Pa /etc/moduli . 791It is important that this file contains moduli of a range of bit lengths and 792that both ends of a connection share common moduli. 793.Pp 794A number of options are available for moduli generation and screening via the 795.Fl O 796flag: 797.Bl -tag -width Ds 798.It Ic lines Ns = Ns Ar number 799Exit after screening the specified number of lines while performing DH 800candidate screening. 801.It Ic start-line Ns = Ns Ar line-number 802Start screening at the specified line number while performing DH candidate 803screening. 804.It Ic checkpoint Ns = Ns Ar filename 805Write the last line processed to the specified file while performing DH 806candidate screening. 807This will be used to skip lines in the input file that have already been 808processed if the job is restarted. 809.It Ic memory Ns = Ns Ar mbytes 810Specify the amount of memory to use (in megabytes) when generating 811candidate moduli for DH-GEX. 812.It Ic start Ns = Ns Ar hex-value 813Specify start point (in hex) when generating candidate moduli for DH-GEX. 814.It Ic generator Ns = Ns Ar value 815Specify desired generator (in decimal) when testing candidate moduli for DH-GEX. 816.El 817.Sh CERTIFICATES 818.Nm 819supports signing of keys to produce certificates that may be used for 820user or host authentication. 821Certificates consist of a public key, some identity information, zero or 822more principal (user or host) names and a set of options that 823are signed by a Certification Authority (CA) key. 824Clients or servers may then trust only the CA key and verify its signature 825on a certificate rather than trusting many user/host keys. 826Note that OpenSSH certificates are a different, and much simpler, format to 827the X.509 certificates used in 828.Xr ssl 8 . 829.Pp 830.Nm 831supports two types of certificates: user and host. 832User certificates authenticate users to servers, whereas host certificates 833authenticate server hosts to users. 834To generate a user certificate: 835.Pp 836.Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub 837.Pp 838The resultant certificate will be placed in 839.Pa /path/to/user_key-cert.pub . 840A host certificate requires the 841.Fl h 842option: 843.Pp 844.Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub 845.Pp 846The host certificate will be output to 847.Pa /path/to/host_key-cert.pub . 848.Pp 849It is possible to sign using a CA key stored in a PKCS#11 token by 850providing the token library using 851.Fl D 852and identifying the CA key by providing its public half as an argument 853to 854.Fl s : 855.Pp 856.Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub 857.Pp 858Similarly, it is possible for the CA key to be hosted in a 859.Xr ssh-agent 1 . 860This is indicated by the 861.Fl U 862flag and, again, the CA key must be identified by its public half. 863.Pp 864.Dl $ ssh-keygen -Us ca_key.pub -I key_id user_key.pub 865.Pp 866In all cases, 867.Ar key_id 868is a "key identifier" that is logged by the server when the certificate 869is used for authentication. 870.Pp 871Certificates may be limited to be valid for a set of principal (user/host) 872names. 873By default, generated certificates are valid for all users or hosts. 874To generate a certificate for a specified set of principals: 875.Pp 876.Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub 877.Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain host_key.pub" 878.Pp 879Additional limitations on the validity and use of user certificates may 880be specified through certificate options. 881A certificate option may disable features of the SSH session, may be 882valid only when presented from particular source addresses or may 883force the use of a specific command. 884.Pp 885The options that are valid for user certificates are: 886.Pp 887.Bl -tag -width Ds -compact 888.It Ic clear 889Clear all enabled permissions. 890This is useful for clearing the default set of permissions so permissions may 891be added individually. 892.Pp 893.It Ic critical : Ns Ar name Ns Op Ns = Ns Ar contents 894.It Ic extension : Ns Ar name Ns Op Ns = Ns Ar contents 895Includes an arbitrary certificate critical option or extension. 896The specified 897.Ar name 898should include a domain suffix, e.g.\& 899.Dq name@example.com . 900If 901.Ar contents 902is specified then it is included as the contents of the extension/option 903encoded as a string, otherwise the extension/option is created with no 904contents (usually indicating a flag). 905Extensions may be ignored by a client or server that does not recognise them, 906whereas unknown critical options will cause the certificate to be refused. 907.Pp 908.It Ic force-command Ns = Ns Ar command 909Forces the execution of 910.Ar command 911instead of any shell or command specified by the user when 912the certificate is used for authentication. 913.Pp 914.It Ic no-agent-forwarding 915Disable 916.Xr ssh-agent 1 917forwarding (permitted by default). 918.Pp 919.It Ic no-port-forwarding 920Disable port forwarding (permitted by default). 921.Pp 922.It Ic no-pty 923Disable PTY allocation (permitted by default). 924.Pp 925.It Ic no-user-rc 926Disable execution of 927.Pa ~/.ssh/rc 928by 929.Xr sshd 8 930(permitted by default). 931.Pp 932.It Ic no-x11-forwarding 933Disable X11 forwarding (permitted by default). 934.Pp 935.It Ic permit-agent-forwarding 936Allows 937.Xr ssh-agent 1 938forwarding. 939.Pp 940.It Ic permit-port-forwarding 941Allows port forwarding. 942.Pp 943.It Ic permit-pty 944Allows PTY allocation. 945.Pp 946.It Ic permit-user-rc 947Allows execution of 948.Pa ~/.ssh/rc 949by 950.Xr sshd 8 . 951.Pp 952.It Ic permit-X11-forwarding 953Allows X11 forwarding. 954.Pp 955.It Ic no-touch-required 956Do not require signatures made using this key require demonstration 957of user presence (e.g. by having the user touch the authenticator). 958This option only makes sense for the FIDO authenticator algorithms 959.Cm ecdsa-sk 960and 961.Cm ed25519-sk . 962.Pp 963.It Ic source-address Ns = Ns Ar address_list 964Restrict the source addresses from which the certificate is considered valid. 965The 966.Ar address_list 967is a comma-separated list of one or more address/netmask pairs in CIDR 968format. 969.El 970.Pp 971At present, no standard options are valid for host keys. 972.Pp 973Finally, certificates may be defined with a validity lifetime. 974The 975.Fl V 976option allows specification of certificate start and end times. 977A certificate that is presented at a time outside this range will not be 978considered valid. 979By default, certificates are valid from 980.Ux 981Epoch to the distant future. 982.Pp 983For certificates to be used for user or host authentication, the CA 984public key must be trusted by 985.Xr sshd 8 986or 987.Xr ssh 1 . 988Please refer to those manual pages for details. 989.Sh KEY REVOCATION LISTS 990.Nm 991is able to manage OpenSSH format Key Revocation Lists (KRLs). 992These binary files specify keys or certificates to be revoked using a 993compact format, taking as little as one bit per certificate if they are being 994revoked by serial number. 995.Pp 996KRLs may be generated using the 997.Fl k 998flag. 999This option reads one or more files from the command line and generates a new 1000KRL. 1001The files may either contain a KRL specification (see below) or public keys, 1002listed one per line. 1003Plain public keys are revoked by listing their hash or contents in the KRL and 1004certificates revoked by serial number or key ID (if the serial is zero or 1005not available). 1006.Pp 1007Revoking keys using a KRL specification offers explicit control over the 1008types of record used to revoke keys and may be used to directly revoke 1009certificates by serial number or key ID without having the complete original 1010certificate on hand. 1011A KRL specification consists of lines containing one of the following directives 1012followed by a colon and some directive-specific information. 1013.Bl -tag -width Ds 1014.It Cm serial : Ar serial_number Ns Op - Ns Ar serial_number 1015Revokes a certificate with the specified serial number. 1016Serial numbers are 64-bit values, not including zero and may be expressed 1017in decimal, hex or octal. 1018If two serial numbers are specified separated by a hyphen, then the range 1019of serial numbers including and between each is revoked. 1020The CA key must have been specified on the 1021.Nm 1022command line using the 1023.Fl s 1024option. 1025.It Cm id : Ar key_id 1026Revokes a certificate with the specified key ID string. 1027The CA key must have been specified on the 1028.Nm 1029command line using the 1030.Fl s 1031option. 1032.It Cm key : Ar public_key 1033Revokes the specified key. 1034If a certificate is listed, then it is revoked as a plain public key. 1035.It Cm sha1 : Ar public_key 1036Revokes the specified key by including its SHA1 hash in the KRL. 1037.It Cm sha256 : Ar public_key 1038Revokes the specified key by including its SHA256 hash in the KRL. 1039KRLs that revoke keys by SHA256 hash are not supported by OpenSSH versions 1040prior to 7.9. 1041.It Cm hash : Ar fingerprint 1042Revokes a key using a fingerprint hash, as obtained from a 1043.Xr sshd 8 1044authentication log message or the 1045.Nm 1046.Fl l 1047flag. 1048Only SHA256 fingerprints are supported here and resultant KRLs are 1049not supported by OpenSSH versions prior to 7.9. 1050.El 1051.Pp 1052KRLs may be updated using the 1053.Fl u 1054flag in addition to 1055.Fl k . 1056When this option is specified, keys listed via the command line are merged into 1057the KRL, adding to those already there. 1058.Pp 1059It is also possible, given a KRL, to test whether it revokes a particular key 1060(or keys). 1061The 1062.Fl Q 1063flag will query an existing KRL, testing each key specified on the command line. 1064If any key listed on the command line has been revoked (or an error encountered) 1065then 1066.Nm 1067will exit with a non-zero exit status. 1068A zero exit status will only be returned if no key was revoked. 1069.Sh ALLOWED SIGNERS 1070When verifying signatures, 1071.Nm 1072uses a simple list of identities and keys to determine whether a signature 1073comes from an authorized source. 1074This "allowed signers" file uses a format patterned after the 1075AUTHORIZED_KEYS FILE FORMAT described in 1076.Xr sshd 8 . 1077Each line of the file contains the following space-separated fields: 1078principals, options, keytype, base64-encoded key. 1079Empty lines and lines starting with a 1080.Ql # 1081are ignored as comments. 1082.Pp 1083The principals field is a pattern-list (See PATTERNS in 1084.Xr ssh_config 5 ) 1085consisting of one or more comma-separated USER@DOMAIN identity patterns 1086that are accepted for signing. 1087When verifying, the identity presented via the 1088.Fl I 1089option must match a principals pattern in order for the corresponding key to be 1090considered acceptable for verification. 1091.Pp 1092The options (if present) consist of comma-separated option specifications. 1093No spaces are permitted, except within double quotes. 1094The following option specifications are supported (note that option keywords 1095are case-insensitive): 1096.Bl -tag -width Ds 1097.It Cm cert-authority 1098Indicates that this key is accepted as a certificate authority (CA) and 1099that certificates signed by this CA may be accepted for verification. 1100.It Cm namespaces="namespace-list" 1101Specifies a pattern-list of namespaces that are accepted for this key. 1102If this option is present, the signature namespace embedded in the 1103signature object and presented on the verification command-line must 1104match the specified list before the key will be considered acceptable. 1105.El 1106.Pp 1107When verifying signatures made by certificates, the expected principal 1108name must match both the principals pattern in the allowed signers file and 1109the principals embedded in the certificate itself. 1110.Pp 1111An example allowed signers file: 1112.Bd -literal -offset 3n 1113# Comments allowed at start of line 1114user1@example.com,user2@example.com ssh-rsa AAAAX1... 1115# A certificate authority, trusted for all principals in a domain. 1116*@example.com cert-authority ssh-ed25519 AAAB4... 1117# A key that is accepted only for file signing. 1118user2@example.com namespaces="file" ssh-ed25519 AAA41... 1119.Ed 1120.Sh ENVIRONMENT 1121.Bl -tag -width Ds 1122.It Ev SSH_SK_PROVIDER 1123Specifies a path to a library that will be used when loading any 1124FIDO authenticator-hosted keys, overriding the default of using 1125the built-in USB HID support. 1126.El 1127.Sh FILES 1128.Bl -tag -width Ds -compact 1129.It Pa ~/.ssh/id_dsa 1130.It Pa ~/.ssh/id_ecdsa 1131.It Pa ~/.ssh/id_ecdsa_sk 1132.It Pa ~/.ssh/id_ed25519 1133.It Pa ~/.ssh/id_ed25519_sk 1134.It Pa ~/.ssh/id_rsa 1135Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, 1136authenticator-hosted Ed25519 or RSA authentication identity of the user. 1137This file should not be readable by anyone but the user. 1138It is possible to 1139specify a passphrase when generating the key; that passphrase will be 1140used to encrypt the private part of this file using 128-bit AES. 1141This file is not automatically accessed by 1142.Nm 1143but it is offered as the default file for the private key. 1144.Xr ssh 1 1145will read this file when a login attempt is made. 1146.Pp 1147.It Pa ~/.ssh/id_dsa.pub 1148.It Pa ~/.ssh/id_ecdsa.pub 1149.It Pa ~/.ssh/id_ecdsa_sk.pub 1150.It Pa ~/.ssh/id_ed25519.pub 1151.It Pa ~/.ssh/id_ed25519_sk.pub 1152.It Pa ~/.ssh/id_rsa.pub 1153Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519, 1154authenticator-hosted Ed25519 or RSA public key for authentication. 1155The contents of this file should be added to 1156.Pa ~/.ssh/authorized_keys 1157on all machines 1158where the user wishes to log in using public key authentication. 1159There is no need to keep the contents of this file secret. 1160.Pp 1161.It Pa /etc/moduli 1162Contains Diffie-Hellman groups used for DH-GEX. 1163The file format is described in 1164.Xr moduli 5 . 1165.El 1166.Sh SEE ALSO 1167.Xr ssh 1 , 1168.Xr ssh-add 1 , 1169.Xr ssh-agent 1 , 1170.Xr moduli 5 , 1171.Xr sshd 8 1172.Rs 1173.%R RFC 4716 1174.%T "The Secure Shell (SSH) Public Key File Format" 1175.%D 2006 1176.Re 1177.Sh AUTHORS 1178OpenSSH is a derivative of the original and free 1179ssh 1.2.12 release by Tatu Ylonen. 1180Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 1181Theo de Raadt and Dug Song 1182removed many bugs, re-added newer features and 1183created OpenSSH. 1184Markus Friedl contributed the support for SSH 1185protocol versions 1.5 and 2.0. 1186