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