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