1.\" $OpenBSD: ssh-keygen.1,v 1.157 2019/03/05 16:17:12 naddy 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: March 5 2019 $ 39.Dt SSH-KEYGEN 1 40.Os 41.Sh NAME 42.Nm ssh-keygen 43.Nd authentication key generation, management and conversion 44.Sh SYNOPSIS 45.Bk -words 46.Nm ssh-keygen 47.Op Fl q 48.Op Fl b Ar bits 49.Op Fl t Cm dsa | ecdsa | ed25519 | rsa 50.Op Fl N Ar new_passphrase 51.Op Fl C Ar comment 52.Op Fl f Ar output_keyfile 53.Op Fl m Ar format 54.Nm ssh-keygen 55.Fl p 56.Op Fl P Ar old_passphrase 57.Op Fl N Ar new_passphrase 58.Op Fl f Ar keyfile 59.Op Fl m Ar format 60.Nm ssh-keygen 61.Fl i 62.Op Fl m Ar key_format 63.Op Fl f Ar input_keyfile 64.Nm ssh-keygen 65.Fl e 66.Op Fl m Ar key_format 67.Op Fl f Ar input_keyfile 68.Nm ssh-keygen 69.Fl y 70.Op Fl f Ar input_keyfile 71.Nm ssh-keygen 72.Fl c 73.Op Fl P Ar passphrase 74.Op Fl C Ar comment 75.Op Fl f Ar keyfile 76.Nm ssh-keygen 77.Fl l 78.Op Fl v 79.Op Fl E Ar fingerprint_hash 80.Op Fl f Ar input_keyfile 81.Nm ssh-keygen 82.Fl B 83.Op Fl f Ar input_keyfile 84.Nm ssh-keygen 85.Fl D Ar pkcs11 86.Nm ssh-keygen 87.Fl F Ar hostname 88.Op Fl f Ar known_hosts_file 89.Op Fl l 90.Nm ssh-keygen 91.Fl H 92.Op Fl f Ar known_hosts_file 93.Nm ssh-keygen 94.Fl R Ar hostname 95.Op Fl f Ar known_hosts_file 96.Nm ssh-keygen 97.Fl r Ar hostname 98.Op Fl f Ar input_keyfile 99.Op Fl g 100.Nm ssh-keygen 101.Fl G Ar output_file 102.Op Fl v 103.Op Fl b Ar bits 104.Op Fl M Ar memory 105.Op Fl S Ar start_point 106.Nm ssh-keygen 107.Fl T Ar output_file 108.Fl f Ar input_file 109.Op Fl v 110.Op Fl a Ar rounds 111.Op Fl J Ar num_lines 112.Op Fl j Ar start_line 113.Op Fl K Ar checkpt 114.Op Fl W Ar generator 115.Nm ssh-keygen 116.Fl s Ar ca_key 117.Fl I Ar certificate_identity 118.Op Fl h 119.Op Fl U 120.Op Fl D Ar pkcs11_provider 121.Op Fl n Ar principals 122.Op Fl O Ar option 123.Op Fl V Ar validity_interval 124.Op Fl z Ar serial_number 125.Ar 126.Nm ssh-keygen 127.Fl L 128.Op Fl f Ar input_keyfile 129.Nm ssh-keygen 130.Fl A 131.Op Fl f Ar prefix_path 132.Nm ssh-keygen 133.Fl k 134.Fl f Ar krl_file 135.Op Fl u 136.Op Fl s Ar ca_public 137.Op Fl z Ar version_number 138.Ar 139.Nm ssh-keygen 140.Fl Q 141.Fl f Ar krl_file 142.Ar 143.Ek 144.Sh DESCRIPTION 145.Nm 146generates, manages and converts authentication keys for 147.Xr ssh 1 . 148.Nm 149can create keys for use by SSH protocol version 2. 150.Pp 151The type of key to be generated is specified with the 152.Fl t 153option. 154If invoked without any arguments, 155.Nm 156will generate an RSA key. 157.Pp 158.Nm 159is also used to generate groups for use in Diffie-Hellman group 160exchange (DH-GEX). 161See the 162.Sx MODULI GENERATION 163section for details. 164.Pp 165Finally, 166.Nm 167can be used to generate and update Key Revocation Lists, and to test whether 168given keys have been revoked by one. 169See the 170.Sx KEY REVOCATION LISTS 171section for details. 172.Pp 173Normally each user wishing to use SSH 174with public key authentication runs this once to create the authentication 175key in 176.Pa ~/.ssh/id_dsa , 177.Pa ~/.ssh/id_ecdsa , 178.Pa ~/.ssh/id_ed25519 179or 180.Pa ~/.ssh/id_rsa . 181Additionally, the system administrator may use this to generate host keys, 182as seen in 183.Pa /etc/rc . 184.Pp 185Normally this program generates the key and asks for a file in which 186to store the private key. 187The public key is stored in a file with the same name but 188.Dq .pub 189appended. 190The program also asks for a passphrase. 191The passphrase may be empty to indicate no passphrase 192(host keys must have an empty passphrase), or it may be a string of 193arbitrary length. 194A passphrase is similar to a password, except it can be a phrase with a 195series of words, punctuation, numbers, whitespace, or any string of 196characters you want. 197Good passphrases are 10-30 characters long, are 198not simple sentences or otherwise easily guessable (English 199prose has only 1-2 bits of entropy per character, and provides very bad 200passphrases), and contain a mix of upper and lowercase letters, 201numbers, and non-alphanumeric characters. 202The passphrase can be changed later by using the 203.Fl p 204option. 205.Pp 206There is no way to recover a lost passphrase. 207If the passphrase is lost or forgotten, a new key must be generated 208and the corresponding public key copied to other machines. 209.Pp 210.Nm 211will by default write keys in an OpenSSH-specific format. 212This format is preferred as it offers better protection for 213keys at rest as well as allowing storage of key comments within 214the private key file itself. 215The key comment may be useful to help identify the key. 216The comment is initialized to 217.Dq user@host 218when the key is created, but can be changed using the 219.Fl c 220option. 221.Pp 222It is still possible for 223.Nm 224to write the previously-used PEM format private keys using the 225.Fl m 226flag. 227This may be used when generating new keys, and existing new-format 228keys may be converted using this option in conjunction with the 229.Fl p 230(change passphrase) flag. 231.Pp 232After a key is generated, instructions below detail where the keys 233should be placed to be activated. 234.Pp 235The options are as follows: 236.Bl -tag -width Ds 237.It Fl A 238For each of the key types (rsa, dsa, ecdsa and ed25519) 239for which host keys 240do not exist, generate the host keys with the default key file path, 241an empty passphrase, default bits for the key type, and default comment. 242If 243.Fl f 244has also been specified, its argument is used as a prefix to the 245default path for the resulting host key files. 246This is used by 247.Pa /etc/rc 248to generate new host keys. 249.It Fl a Ar rounds 250When saving a private key this option specifies the number of KDF 251(key derivation function) rounds used. 252Higher numbers result in slower passphrase verification and increased 253resistance to brute-force password cracking (should the keys be stolen). 254.Pp 255When screening DH-GEX candidates (using the 256.Fl T 257command). 258This option specifies the number of primality tests to perform. 259.It Fl B 260Show the bubblebabble digest of specified private or public key file. 261.It Fl b Ar bits 262Specifies the number of bits in the key to create. 263For RSA keys, the minimum size is 1024 bits and the default is 2048 bits. 264Generally, 2048 bits is considered sufficient. 265DSA keys must be exactly 1024 bits as specified by FIPS 186-2. 266For ECDSA keys, the 267.Fl b 268flag determines the key length by selecting from one of three elliptic 269curve sizes: 256, 384 or 521 bits. 270Attempting to use bit lengths other than these three values for ECDSA keys 271will fail. 272Ed25519 keys have a fixed length and the 273.Fl b 274flag will be ignored. 275.It Fl C Ar comment 276Provides a new comment. 277.It Fl c 278Requests changing the comment in the private and public key files. 279The program will prompt for the file containing the private keys, for 280the passphrase if the key has one, and for the new comment. 281.It Fl D Ar pkcs11 282Download the public keys provided by the PKCS#11 shared library 283.Ar pkcs11 . 284When used in combination with 285.Fl s , 286this option indicates that a CA key resides in a PKCS#11 token (see the 287.Sx CERTIFICATES 288section for details). 289.It Fl E Ar fingerprint_hash 290Specifies the hash algorithm used when displaying key fingerprints. 291Valid options are: 292.Dq md5 293and 294.Dq sha256 . 295The default is 296.Dq sha256 . 297.It Fl e 298This option will read a private or public OpenSSH key file and 299print to stdout a public key in one of the formats specified by the 300.Fl m 301option. 302The default export format is 303.Dq RFC4716 . 304This option allows exporting OpenSSH keys for use by other programs, including 305several commercial SSH implementations. 306.It Fl F Ar hostname | [hostname]:port 307Search for the specified 308.Ar hostname 309(with optional port number) 310in a 311.Pa known_hosts 312file, listing any occurrences found. 313This option is useful to find hashed host names or addresses and may also be 314used in conjunction with the 315.Fl H 316option to print found keys in a hashed format. 317.It Fl f Ar filename 318Specifies the filename of the key file. 319.It Fl G Ar output_file 320Generate candidate primes for DH-GEX. 321These primes must be screened for 322safety (using the 323.Fl T 324option) before use. 325.It Fl g 326Use generic DNS format when printing fingerprint resource records using the 327.Fl r 328command. 329.It Fl H 330Hash a 331.Pa known_hosts 332file. 333This replaces all hostnames and addresses with hashed representations 334within the specified file; the original content is moved to a file with 335a .old suffix. 336These hashes may be used normally by 337.Nm ssh 338and 339.Nm sshd , 340but they do not reveal identifying information should the file's contents 341be disclosed. 342This option will not modify existing hashed hostnames and is therefore safe 343to use on files that mix hashed and non-hashed names. 344.It Fl h 345When signing a key, create a host certificate instead of a user 346certificate. 347Please see the 348.Sx CERTIFICATES 349section for details. 350.It Fl I Ar certificate_identity 351Specify the key identity when signing a public key. 352Please see the 353.Sx CERTIFICATES 354section for details. 355.It Fl i 356This option will read an unencrypted private (or public) key file 357in the format specified by the 358.Fl m 359option and print an OpenSSH compatible private 360(or public) key to stdout. 361This option allows importing keys from other software, including several 362commercial SSH implementations. 363The default import format is 364.Dq RFC4716 . 365.It Fl J Ar num_lines 366Exit after screening the specified number of lines 367while performing DH candidate screening using the 368.Fl T 369option. 370.It Fl j Ar start_line 371Start screening at the specified line number 372while performing DH candidate screening using the 373.Fl T 374option. 375.It Fl K Ar checkpt 376Write the last line processed to the file 377.Ar checkpt 378while performing DH candidate screening using the 379.Fl T 380option. 381This will be used to skip lines in the input file that have already been 382processed if the job is restarted. 383.It Fl k 384Generate a KRL file. 385In this mode, 386.Nm 387will generate a KRL file at the location specified via the 388.Fl f 389flag that revokes every key or certificate presented on the command line. 390Keys/certificates to be revoked may be specified by public key file or 391using the format described in the 392.Sx KEY REVOCATION LISTS 393section. 394.It Fl L 395Prints the contents of one or more certificates. 396.It Fl l 397Show fingerprint of specified public key file. 398For RSA and DSA keys 399.Nm 400tries to find the matching public key file and prints its fingerprint. 401If combined with 402.Fl v , 403a visual ASCII art representation of the key is supplied with the 404fingerprint. 405.It Fl M Ar memory 406Specify the amount of memory to use (in megabytes) when generating 407candidate moduli for DH-GEX. 408.It Fl m Ar key_format 409Specify a key format for key generation, the 410.Fl i 411(import), 412.Fl e 413(export) conversion options, and the 414.Fl p 415change passphrase operation. 416The latter may be used to convert between OpenSSH private key and PEM 417private key formats. 418The supported key formats are: 419.Dq RFC4716 420(RFC 4716/SSH2 public or private key), 421.Dq PKCS8 422(PEM PKCS8 public key) 423or 424.Dq PEM 425(PEM public key). 426The default conversion format is 427.Dq RFC4716 . 428Setting a format of 429.Dq PEM 430when generating or updating a supported private key type will cause the 431key to be stored in the legacy PEM private key format. 432.It Fl N Ar new_passphrase 433Provides the new passphrase. 434.It Fl n Ar principals 435Specify one or more principals (user or host names) to be included in 436a certificate when signing a key. 437Multiple principals may be specified, separated by commas. 438Please see the 439.Sx CERTIFICATES 440section for details. 441.It Fl O Ar option 442Specify a certificate option when signing a key. 443This option may be specified multiple times. 444See also the 445.Sx CERTIFICATES 446section for further details. 447.Pp 448At present, no standard options are valid for host keys. 449The options that are valid for user certificates are: 450.Pp 451.Bl -tag -width Ds -compact 452.It Ic clear 453Clear all enabled permissions. 454This is useful for clearing the default set of permissions so permissions may 455be added individually. 456.Pp 457.It Ic critical : Ns Ar name Ns Op Ns = Ns Ar contents 458.It Ic extension : Ns Ar name Ns Op Ns = Ns Ar contents 459Includes an arbitrary certificate critical option or extension. 460The specified 461.Ar name 462should include a domain suffix, e.g.\& 463.Dq name@example.com . 464If 465.Ar contents 466is specified then it is included as the contents of the extension/option 467encoded as a string, otherwise the extension/option is created with no 468contents (usually indicating a flag). 469Extensions may be ignored by a client or server that does not recognise them, 470whereas unknown critical options will cause the certificate to be refused. 471.Pp 472.It Ic force-command Ns = Ns Ar command 473Forces the execution of 474.Ar command 475instead of any shell or command specified by the user when 476the certificate is used for authentication. 477.Pp 478.It Ic no-agent-forwarding 479Disable 480.Xr ssh-agent 1 481forwarding (permitted by default). 482.Pp 483.It Ic no-port-forwarding 484Disable port forwarding (permitted by default). 485.Pp 486.It Ic no-pty 487Disable PTY allocation (permitted by default). 488.Pp 489.It Ic no-user-rc 490Disable execution of 491.Pa ~/.ssh/rc 492by 493.Xr sshd 8 494(permitted by default). 495.Pp 496.It Ic no-x11-forwarding 497Disable X11 forwarding (permitted by default). 498.Pp 499.It Ic permit-agent-forwarding 500Allows 501.Xr ssh-agent 1 502forwarding. 503.Pp 504.It Ic permit-port-forwarding 505Allows port forwarding. 506.Pp 507.It Ic permit-pty 508Allows PTY allocation. 509.Pp 510.It Ic permit-user-rc 511Allows execution of 512.Pa ~/.ssh/rc 513by 514.Xr sshd 8 . 515.Pp 516.It Ic permit-X11-forwarding 517Allows X11 forwarding. 518.Pp 519.It Ic source-address Ns = Ns Ar address_list 520Restrict the source addresses from which the certificate is considered valid. 521The 522.Ar address_list 523is a comma-separated list of one or more address/netmask pairs in CIDR 524format. 525.El 526.It Fl P Ar passphrase 527Provides the (old) passphrase. 528.It Fl p 529Requests changing the passphrase of a private key file instead of 530creating a new private key. 531The program will prompt for the file 532containing the private key, for the old passphrase, and twice for the 533new passphrase. 534.It Fl Q 535Test whether keys have been revoked in a KRL. 536.It Fl q 537Silence 538.Nm ssh-keygen . 539.It Fl R Ar hostname | [hostname]:port 540Removes all keys belonging to the specified 541.Ar hostname 542(with optional port number) 543from a 544.Pa known_hosts 545file. 546This option is useful to delete hashed hosts (see the 547.Fl H 548option above). 549.It Fl r Ar hostname 550Print the SSHFP fingerprint resource record named 551.Ar hostname 552for the specified public key file. 553.It Fl S Ar start 554Specify start point (in hex) when generating candidate moduli for DH-GEX. 555.It Fl s Ar ca_key 556Certify (sign) a public key using the specified CA key. 557Please see the 558.Sx CERTIFICATES 559section for details. 560.Pp 561When generating a KRL, 562.Fl s 563specifies a path to a CA public key file used to revoke certificates directly 564by key ID or serial number. 565See the 566.Sx KEY REVOCATION LISTS 567section for details. 568.It Fl T Ar output_file 569Test DH group exchange candidate primes (generated using the 570.Fl G 571option) for safety. 572.It Fl t Cm dsa | ecdsa | ed25519 | rsa 573Specifies the type of key to create. 574The possible values are 575.Dq dsa , 576.Dq ecdsa , 577.Dq ed25519 , 578or 579.Dq rsa . 580.It Fl U 581When used in combination with 582.Fl s , 583this option indicates that a CA key resides in a 584.Xr ssh-agent 1 . 585See the 586.Sx CERTIFICATES 587section for more information. 588.It Fl u 589Update a KRL. 590When specified with 591.Fl k , 592keys listed via the command line are added to the existing KRL rather than 593a new KRL being created. 594.It Fl V Ar validity_interval 595Specify a validity interval when signing a certificate. 596A validity interval may consist of a single time, indicating that the 597certificate is valid beginning now and expiring at that time, or may consist 598of two times separated by a colon to indicate an explicit time interval. 599.Pp 600The start time may be specified as the string 601.Dq always 602to indicate the certificate has no specified start time, 603a date in YYYYMMDD format, a time in YYYYMMDDHHMM[SS] format, 604a relative time (to the current time) consisting of a minus sign followed by 605an interval in the format described in the 606TIME FORMATS section of 607.Xr sshd_config 5 . 608.Pp 609The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMM[SS] time, 610a relative time starting with a plus character or the string 611.Dq forever 612to indicate that the certificate has no expirty date. 613.Pp 614For example: 615.Dq +52w1d 616(valid from now to 52 weeks and one day from now), 617.Dq -4w:+4w 618(valid from four weeks ago to four weeks from now), 619.Dq 20100101123000:20110101123000 620(valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011), 621.Dq -1d:20110101 622(valid from yesterday to midnight, January 1st, 2011). 623.Dq -1m:forever 624(valid from one minute ago and never expiring). 625.It Fl v 626Verbose mode. 627Causes 628.Nm 629to print debugging messages about its progress. 630This is helpful for debugging moduli generation. 631Multiple 632.Fl v 633options increase the verbosity. 634The maximum is 3. 635.It Fl W Ar generator 636Specify desired generator when testing candidate moduli for DH-GEX. 637.It Fl y 638This option will read a private 639OpenSSH format file and print an OpenSSH public key to stdout. 640.It Fl z Ar serial_number 641Specifies a serial number to be embedded in the certificate to distinguish 642this certificate from others from the same CA. 643If the 644.Ar serial_number 645is prefixed with a 646.Sq + 647character, then the serial number will be incremented for each certificate 648signed on a single command-line. 649The default serial number is zero. 650.Pp 651When generating a KRL, the 652.Fl z 653flag is used to specify a KRL version number. 654.El 655.Sh MODULI GENERATION 656.Nm 657may be used to generate groups for the Diffie-Hellman Group Exchange 658(DH-GEX) protocol. 659Generating these groups is a two-step process: first, candidate 660primes are generated using a fast, but memory intensive process. 661These candidate primes are then tested for suitability (a CPU-intensive 662process). 663.Pp 664Generation of primes is performed using the 665.Fl G 666option. 667The desired length of the primes may be specified by the 668.Fl b 669option. 670For example: 671.Pp 672.Dl # ssh-keygen -G moduli-2048.candidates -b 2048 673.Pp 674By default, the search for primes begins at a random point in the 675desired length range. 676This may be overridden using the 677.Fl S 678option, which specifies a different start point (in hex). 679.Pp 680Once a set of candidates have been generated, they must be screened for 681suitability. 682This may be performed using the 683.Fl T 684option. 685In this mode 686.Nm 687will read candidates from standard input (or a file specified using the 688.Fl f 689option). 690For example: 691.Pp 692.Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates 693.Pp 694By default, each candidate will be subjected to 100 primality tests. 695This may be overridden using the 696.Fl a 697option. 698The DH generator value will be chosen automatically for the 699prime under consideration. 700If a specific generator is desired, it may be requested using the 701.Fl W 702option. 703Valid generator values are 2, 3, and 5. 704.Pp 705Screened DH groups may be installed in 706.Pa /etc/moduli . 707It is important that this file contains moduli of a range of bit lengths and 708that both ends of a connection share common moduli. 709.Sh CERTIFICATES 710.Nm 711supports signing of keys to produce certificates that may be used for 712user or host authentication. 713Certificates consist of a public key, some identity information, zero or 714more principal (user or host) names and a set of options that 715are signed by a Certification Authority (CA) key. 716Clients or servers may then trust only the CA key and verify its signature 717on a certificate rather than trusting many user/host keys. 718Note that OpenSSH certificates are a different, and much simpler, format to 719the X.509 certificates used in 720.Xr ssl 8 . 721.Pp 722.Nm 723supports two types of certificates: user and host. 724User certificates authenticate users to servers, whereas host certificates 725authenticate server hosts to users. 726To generate a user certificate: 727.Pp 728.Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub 729.Pp 730The resultant certificate will be placed in 731.Pa /path/to/user_key-cert.pub . 732A host certificate requires the 733.Fl h 734option: 735.Pp 736.Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub 737.Pp 738The host certificate will be output to 739.Pa /path/to/host_key-cert.pub . 740.Pp 741It is possible to sign using a CA key stored in a PKCS#11 token by 742providing the token library using 743.Fl D 744and identifying the CA key by providing its public half as an argument 745to 746.Fl s : 747.Pp 748.Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub 749.Pp 750Similarly, it is possible for the CA key to be hosted in a 751.Xr ssh-agent 1 . 752This is indicated by the 753.Fl U 754flag and, again, the CA key must be identified by its public half. 755.Pp 756.Dl $ ssh-keygen -Us ca_key.pub -I key_id user_key.pub 757.Pp 758In all cases, 759.Ar key_id 760is a "key identifier" that is logged by the server when the certificate 761is used for authentication. 762.Pp 763Certificates may be limited to be valid for a set of principal (user/host) 764names. 765By default, generated certificates are valid for all users or hosts. 766To generate a certificate for a specified set of principals: 767.Pp 768.Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub 769.Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain host_key.pub" 770.Pp 771Additional limitations on the validity and use of user certificates may 772be specified through certificate options. 773A certificate option may disable features of the SSH session, may be 774valid only when presented from particular source addresses or may 775force the use of a specific command. 776For a list of valid certificate options, see the documentation for the 777.Fl O 778option above. 779.Pp 780Finally, certificates may be defined with a validity lifetime. 781The 782.Fl V 783option allows specification of certificate start and end times. 784A certificate that is presented at a time outside this range will not be 785considered valid. 786By default, certificates are valid from 787.Ux 788Epoch to the distant future. 789.Pp 790For certificates to be used for user or host authentication, the CA 791public key must be trusted by 792.Xr sshd 8 793or 794.Xr ssh 1 . 795Please refer to those manual pages for details. 796.Sh KEY REVOCATION LISTS 797.Nm 798is able to manage OpenSSH format Key Revocation Lists (KRLs). 799These binary files specify keys or certificates to be revoked using a 800compact format, taking as little as one bit per certificate if they are being 801revoked by serial number. 802.Pp 803KRLs may be generated using the 804.Fl k 805flag. 806This option reads one or more files from the command line and generates a new 807KRL. 808The files may either contain a KRL specification (see below) or public keys, 809listed one per line. 810Plain public keys are revoked by listing their hash or contents in the KRL and 811certificates revoked by serial number or key ID (if the serial is zero or 812not available). 813.Pp 814Revoking keys using a KRL specification offers explicit control over the 815types of record used to revoke keys and may be used to directly revoke 816certificates by serial number or key ID without having the complete original 817certificate on hand. 818A KRL specification consists of lines containing one of the following directives 819followed by a colon and some directive-specific information. 820.Bl -tag -width Ds 821.It Cm serial : Ar serial_number Ns Op - Ns Ar serial_number 822Revokes a certificate with the specified serial number. 823Serial numbers are 64-bit values, not including zero and may be expressed 824in decimal, hex or octal. 825If two serial numbers are specified separated by a hyphen, then the range 826of serial numbers including and between each is revoked. 827The CA key must have been specified on the 828.Nm 829command line using the 830.Fl s 831option. 832.It Cm id : Ar key_id 833Revokes a certificate with the specified key ID string. 834The CA key must have been specified on the 835.Nm 836command line using the 837.Fl s 838option. 839.It Cm key : Ar public_key 840Revokes the specified key. 841If a certificate is listed, then it is revoked as a plain public key. 842.It Cm sha1 : Ar public_key 843Revokes the specified key by including its SHA1 hash in the KRL. 844.It Cm sha256 : Ar public_key 845Revokes the specified key by including its SHA256 hash in the KRL. 846KRLs that revoke keys by SHA256 hash are not supported by OpenSSH versions 847prior to 7.9. 848.It Cm hash : Ar fingerprint 849Revokes a key using a fingerprint hash, as obtained from a 850.Xr sshd 8 851authentication log message or the 852.Nm 853.Fl l 854flag. 855Only SHA256 fingerprints are supported here and resultant KRLs are 856not supported by OpenSSH versions prior to 7.9. 857.El 858.Pp 859KRLs may be updated using the 860.Fl u 861flag in addition to 862.Fl k . 863When this option is specified, keys listed via the command line are merged into 864the KRL, adding to those already there. 865.Pp 866It is also possible, given a KRL, to test whether it revokes a particular key 867(or keys). 868The 869.Fl Q 870flag will query an existing KRL, testing each key specified on the command line. 871If any key listed on the command line has been revoked (or an error encountered) 872then 873.Nm 874will exit with a non-zero exit status. 875A zero exit status will only be returned if no key was revoked. 876.Sh FILES 877.Bl -tag -width Ds -compact 878.It Pa ~/.ssh/id_dsa 879.It Pa ~/.ssh/id_ecdsa 880.It Pa ~/.ssh/id_ed25519 881.It Pa ~/.ssh/id_rsa 882Contains the DSA, ECDSA, Ed25519 or RSA 883authentication identity of the user. 884This file should not be readable by anyone but the user. 885It is possible to 886specify a passphrase when generating the key; that passphrase will be 887used to encrypt the private part of this file using 128-bit AES. 888This file is not automatically accessed by 889.Nm 890but it is offered as the default file for the private key. 891.Xr ssh 1 892will read this file when a login attempt is made. 893.Pp 894.It Pa ~/.ssh/id_dsa.pub 895.It Pa ~/.ssh/id_ecdsa.pub 896.It Pa ~/.ssh/id_ed25519.pub 897.It Pa ~/.ssh/id_rsa.pub 898Contains the DSA, ECDSA, Ed25519 or RSA 899public key for authentication. 900The contents of this file should be added to 901.Pa ~/.ssh/authorized_keys 902on all machines 903where the user wishes to log in using public key authentication. 904There is no need to keep the contents of this file secret. 905.Pp 906.It Pa /etc/moduli 907Contains Diffie-Hellman groups used for DH-GEX. 908The file format is described in 909.Xr moduli 5 . 910.El 911.Sh SEE ALSO 912.Xr ssh 1 , 913.Xr ssh-add 1 , 914.Xr ssh-agent 1 , 915.Xr moduli 5 , 916.Xr sshd 8 917.Rs 918.%R RFC 4716 919.%T "The Secure Shell (SSH) Public Key File Format" 920.%D 2006 921.Re 922.Sh AUTHORS 923OpenSSH is a derivative of the original and free 924ssh 1.2.12 release by Tatu Ylonen. 925Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 926Theo de Raadt and Dug Song 927removed many bugs, re-added newer features and 928created OpenSSH. 929Markus Friedl contributed the support for SSH 930protocol versions 1.5 and 2.0. 931