1.\" $OpenBSD: ssh-keygen.1,v 1.152 2018/12/07 03:33:18 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: December 7 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 | [hostname]:port 293Search for the specified 294.Ar hostname 295(with optional port number) 296in a 297.Pa known_hosts 298file, listing any occurrences found. 299This option is useful to find hashed host names or addresses and may also be 300used in conjunction with the 301.Fl H 302option to print found keys in a hashed format. 303.It Fl f Ar filename 304Specifies the filename of the key file. 305.It Fl G Ar output_file 306Generate candidate primes for DH-GEX. 307These primes must be screened for 308safety (using the 309.Fl T 310option) before use. 311.It Fl g 312Use generic DNS format when printing fingerprint resource records using the 313.Fl r 314command. 315.It Fl H 316Hash a 317.Pa known_hosts 318file. 319This replaces all hostnames and addresses with hashed representations 320within the specified file; the original content is moved to a file with 321a .old suffix. 322These hashes may be used normally by 323.Nm ssh 324and 325.Nm sshd , 326but they do not reveal identifying information should the file's contents 327be disclosed. 328This option will not modify existing hashed hostnames and is therefore safe 329to use on files that mix hashed and non-hashed names. 330.It Fl h 331When signing a key, create a host certificate instead of a user 332certificate. 333Please see the 334.Sx CERTIFICATES 335section for details. 336.It Fl I Ar certificate_identity 337Specify the key identity when signing a public key. 338Please see the 339.Sx CERTIFICATES 340section for details. 341.It Fl i 342This option will read an unencrypted private (or public) key file 343in the format specified by the 344.Fl m 345option and print an OpenSSH compatible private 346(or public) key to stdout. 347This option allows importing keys from other software, including several 348commercial SSH implementations. 349The default import format is 350.Dq RFC4716 . 351.It Fl J Ar num_lines 352Exit after screening the specified number of lines 353while performing DH candidate screening using the 354.Fl T 355option. 356.It Fl j Ar start_line 357Start screening at the specified line number 358while performing DH candidate screening using the 359.Fl T 360option. 361.It Fl K Ar checkpt 362Write the last line processed to the file 363.Ar checkpt 364while performing DH candidate screening using the 365.Fl T 366option. 367This will be used to skip lines in the input file that have already been 368processed if the job is restarted. 369.It Fl k 370Generate a KRL file. 371In this mode, 372.Nm 373will generate a KRL file at the location specified via the 374.Fl f 375flag that revokes every key or certificate presented on the command line. 376Keys/certificates to be revoked may be specified by public key file or 377using the format described in the 378.Sx KEY REVOCATION LISTS 379section. 380.It Fl L 381Prints the contents of one or more certificates. 382.It Fl l 383Show fingerprint of specified public key file. 384For RSA and DSA keys 385.Nm 386tries to find the matching public key file and prints its fingerprint. 387If combined with 388.Fl v , 389a visual ASCII art representation of the key is supplied with the 390fingerprint. 391.It Fl M Ar memory 392Specify the amount of memory to use (in megabytes) when generating 393candidate moduli for DH-GEX. 394.It Fl m Ar key_format 395Specify a key format for the 396.Fl i 397(import) or 398.Fl e 399(export) conversion options. 400The supported key formats are: 401.Dq RFC4716 402(RFC 4716/SSH2 public or private key), 403.Dq PKCS8 404(PEM PKCS8 public key) 405or 406.Dq PEM 407(PEM public key). 408The default conversion format is 409.Dq RFC4716 . 410Setting a format of 411.Dq PEM 412when generating or updating a supported private key type will cause the 413key to be stored in the legacy PEM private key format. 414.It Fl N Ar new_passphrase 415Provides the new passphrase. 416.It Fl n Ar principals 417Specify one or more principals (user or host names) to be included in 418a certificate when signing a key. 419Multiple principals may be specified, separated by commas. 420Please see the 421.Sx CERTIFICATES 422section for details. 423.It Fl O Ar option 424Specify a certificate option when signing a key. 425This option may be specified multiple times. 426See also the 427.Sx CERTIFICATES 428section for further details. 429.Pp 430At present, no standard options are valid for host keys. 431The options that are valid for user certificates are: 432.Pp 433.Bl -tag -width Ds -compact 434.It Ic clear 435Clear all enabled permissions. 436This is useful for clearing the default set of permissions so permissions may 437be added individually. 438.Pp 439.It Ic critical : Ns Ar name Ns Op Ns = Ns Ar contents 440.It Ic extension : Ns Ar name Ns Op Ns = Ns Ar contents 441Includes an arbitrary certificate critical option or extension. 442The specified 443.Ar name 444should include a domain suffix, e.g.\& 445.Dq name@example.com . 446If 447.Ar contents 448is specified then it is included as the contents of the extension/option 449encoded as a string, otherwise the extension/option is created with no 450contents (usually indicating a flag). 451Extensions may be ignored by a client or server that does not recognise them, 452whereas unknown critical options will cause the certificate to be refused. 453.Pp 454.It Ic force-command Ns = Ns Ar command 455Forces the execution of 456.Ar command 457instead of any shell or command specified by the user when 458the certificate is used for authentication. 459.Pp 460.It Ic no-agent-forwarding 461Disable 462.Xr ssh-agent 1 463forwarding (permitted by default). 464.Pp 465.It Ic no-port-forwarding 466Disable port forwarding (permitted by default). 467.Pp 468.It Ic no-pty 469Disable PTY allocation (permitted by default). 470.Pp 471.It Ic no-user-rc 472Disable execution of 473.Pa ~/.ssh/rc 474by 475.Xr sshd 8 476(permitted by default). 477.Pp 478.It Ic no-x11-forwarding 479Disable X11 forwarding (permitted by default). 480.Pp 481.It Ic permit-agent-forwarding 482Allows 483.Xr ssh-agent 1 484forwarding. 485.Pp 486.It Ic permit-port-forwarding 487Allows port forwarding. 488.Pp 489.It Ic permit-pty 490Allows PTY allocation. 491.Pp 492.It Ic permit-user-rc 493Allows execution of 494.Pa ~/.ssh/rc 495by 496.Xr sshd 8 . 497.Pp 498.It Ic permit-X11-forwarding 499Allows X11 forwarding. 500.Pp 501.It Ic source-address Ns = Ns Ar address_list 502Restrict the source addresses from which the certificate is considered valid. 503The 504.Ar address_list 505is a comma-separated list of one or more address/netmask pairs in CIDR 506format. 507.El 508.It Fl P Ar passphrase 509Provides the (old) passphrase. 510.It Fl p 511Requests changing the passphrase of a private key file instead of 512creating a new private key. 513The program will prompt for the file 514containing the private key, for the old passphrase, and twice for the 515new passphrase. 516.It Fl Q 517Test whether keys have been revoked in a KRL. 518.It Fl q 519Silence 520.Nm ssh-keygen . 521.It Fl R Ar hostname | [hostname]:port 522Removes all keys belonging to the specified 523.Ar hostname 524(with optional port number) 525from a 526.Pa known_hosts 527file. 528This option is useful to delete hashed hosts (see the 529.Fl H 530option above). 531.It Fl r Ar hostname 532Print the SSHFP fingerprint resource record named 533.Ar hostname 534for the specified public key file. 535.It Fl S Ar start 536Specify start point (in hex) when generating candidate moduli for DH-GEX. 537.It Fl s Ar ca_key 538Certify (sign) a public key using the specified CA key. 539Please see the 540.Sx CERTIFICATES 541section for details. 542.Pp 543When generating a KRL, 544.Fl s 545specifies a path to a CA public key file used to revoke certificates directly 546by key ID or serial number. 547See the 548.Sx KEY REVOCATION LISTS 549section for details. 550.It Fl T Ar output_file 551Test DH group exchange candidate primes (generated using the 552.Fl G 553option) for safety. 554.It Fl t Cm dsa | ecdsa | ed25519 | rsa 555Specifies the type of key to create. 556The possible values are 557.Dq dsa , 558.Dq ecdsa , 559.Dq ed25519 , 560or 561.Dq rsa . 562.It Fl U 563When used in combination with 564.Fl s , 565this option indicates that a CA key resides in a 566.Xr ssh-agent 1 . 567See the 568.Sx CERTIFICATES 569section for more information. 570.It Fl u 571Update a KRL. 572When specified with 573.Fl k , 574keys listed via the command line are added to the existing KRL rather than 575a new KRL being created. 576.It Fl V Ar validity_interval 577Specify a validity interval when signing a certificate. 578A validity interval may consist of a single time, indicating that the 579certificate is valid beginning now and expiring at that time, or may consist 580of two times separated by a colon to indicate an explicit time interval. 581.Pp 582The start time may be specified as the string 583.Dq always 584to indicate the certificate has no specified start time, 585a date in YYYYMMDD format, a time in YYYYMMDDHHMM[SS] format, 586a relative time (to the current time) consisting of a minus sign followed by 587an interval in the format described in the 588TIME FORMATS section of 589.Xr sshd_config 5 . 590.Pp 591The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMM[SS] time, 592a relative time starting with a plus character or the string 593.Dq forever 594to indicate that the certificate has no expirty date. 595.Pp 596For example: 597.Dq +52w1d 598(valid from now to 52 weeks and one day from now), 599.Dq -4w:+4w 600(valid from four weeks ago to four weeks from now), 601.Dq 20100101123000:20110101123000 602(valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011), 603.Dq -1d:20110101 604(valid from yesterday to midnight, January 1st, 2011). 605.Dq -1m:forever 606(valid from one minute ago and never expiring). 607.It Fl v 608Verbose mode. 609Causes 610.Nm 611to print debugging messages about its progress. 612This is helpful for debugging moduli generation. 613Multiple 614.Fl v 615options increase the verbosity. 616The maximum is 3. 617.It Fl W Ar generator 618Specify desired generator when testing candidate moduli for DH-GEX. 619.It Fl y 620This option will read a private 621OpenSSH format file and print an OpenSSH public key to stdout. 622.It Fl z Ar serial_number 623Specifies a serial number to be embedded in the certificate to distinguish 624this certificate from others from the same CA. 625The default serial number is zero. 626.Pp 627When generating a KRL, the 628.Fl z 629flag is used to specify a KRL version number. 630.El 631.Sh MODULI GENERATION 632.Nm 633may be used to generate groups for the Diffie-Hellman Group Exchange 634(DH-GEX) protocol. 635Generating these groups is a two-step process: first, candidate 636primes are generated using a fast, but memory intensive process. 637These candidate primes are then tested for suitability (a CPU-intensive 638process). 639.Pp 640Generation of primes is performed using the 641.Fl G 642option. 643The desired length of the primes may be specified by the 644.Fl b 645option. 646For example: 647.Pp 648.Dl # ssh-keygen -G moduli-2048.candidates -b 2048 649.Pp 650By default, the search for primes begins at a random point in the 651desired length range. 652This may be overridden using the 653.Fl S 654option, which specifies a different start point (in hex). 655.Pp 656Once a set of candidates have been generated, they must be screened for 657suitability. 658This may be performed using the 659.Fl T 660option. 661In this mode 662.Nm 663will read candidates from standard input (or a file specified using the 664.Fl f 665option). 666For example: 667.Pp 668.Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates 669.Pp 670By default, each candidate will be subjected to 100 primality tests. 671This may be overridden using the 672.Fl a 673option. 674The DH generator value will be chosen automatically for the 675prime under consideration. 676If a specific generator is desired, it may be requested using the 677.Fl W 678option. 679Valid generator values are 2, 3, and 5. 680.Pp 681Screened DH groups may be installed in 682.Pa /etc/moduli . 683It is important that this file contains moduli of a range of bit lengths and 684that both ends of a connection share common moduli. 685.Sh CERTIFICATES 686.Nm 687supports signing of keys to produce certificates that may be used for 688user or host authentication. 689Certificates consist of a public key, some identity information, zero or 690more principal (user or host) names and a set of options that 691are signed by a Certification Authority (CA) key. 692Clients or servers may then trust only the CA key and verify its signature 693on a certificate rather than trusting many user/host keys. 694Note that OpenSSH certificates are a different, and much simpler, format to 695the X.509 certificates used in 696.Xr ssl 8 . 697.Pp 698.Nm 699supports two types of certificates: user and host. 700User certificates authenticate users to servers, whereas host certificates 701authenticate server hosts to users. 702To generate a user certificate: 703.Pp 704.Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub 705.Pp 706The resultant certificate will be placed in 707.Pa /path/to/user_key-cert.pub . 708A host certificate requires the 709.Fl h 710option: 711.Pp 712.Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub 713.Pp 714The host certificate will be output to 715.Pa /path/to/host_key-cert.pub . 716.Pp 717It is possible to sign using a CA key stored in a PKCS#11 token by 718providing the token library using 719.Fl D 720and identifying the CA key by providing its public half as an argument 721to 722.Fl s : 723.Pp 724.Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub 725.Pp 726Similarly, it is possible for the CA key to be hosted in a 727.Xr ssh-agent 1 . 728This is indicated by the 729.Fl U 730flag and, again, the CA key must be identified by its public half. 731.Pp 732.Dl $ ssh-keygen -Us ca_key.pub -I key_id user_key.pub 733.Pp 734In all cases, 735.Ar key_id 736is a "key identifier" that is logged by the server when the certificate 737is used for authentication. 738.Pp 739Certificates may be limited to be valid for a set of principal (user/host) 740names. 741By default, generated certificates are valid for all users or hosts. 742To generate a certificate for a specified set of principals: 743.Pp 744.Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub 745.Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain host_key.pub" 746.Pp 747Additional limitations on the validity and use of user certificates may 748be specified through certificate options. 749A certificate option may disable features of the SSH session, may be 750valid only when presented from particular source addresses or may 751force the use of a specific command. 752For a list of valid certificate options, see the documentation for the 753.Fl O 754option above. 755.Pp 756Finally, certificates may be defined with a validity lifetime. 757The 758.Fl V 759option allows specification of certificate start and end times. 760A certificate that is presented at a time outside this range will not be 761considered valid. 762By default, certificates are valid from 763.Ux 764Epoch to the distant future. 765.Pp 766For certificates to be used for user or host authentication, the CA 767public key must be trusted by 768.Xr sshd 8 769or 770.Xr ssh 1 . 771Please refer to those manual pages for details. 772.Sh KEY REVOCATION LISTS 773.Nm 774is able to manage OpenSSH format Key Revocation Lists (KRLs). 775These binary files specify keys or certificates to be revoked using a 776compact format, taking as little as one bit per certificate if they are being 777revoked by serial number. 778.Pp 779KRLs may be generated using the 780.Fl k 781flag. 782This option reads one or more files from the command line and generates a new 783KRL. 784The files may either contain a KRL specification (see below) or public keys, 785listed one per line. 786Plain public keys are revoked by listing their hash or contents in the KRL and 787certificates revoked by serial number or key ID (if the serial is zero or 788not available). 789.Pp 790Revoking keys using a KRL specification offers explicit control over the 791types of record used to revoke keys and may be used to directly revoke 792certificates by serial number or key ID without having the complete original 793certificate on hand. 794A KRL specification consists of lines containing one of the following directives 795followed by a colon and some directive-specific information. 796.Bl -tag -width Ds 797.It Cm serial : Ar serial_number Ns Op - Ns Ar serial_number 798Revokes a certificate with the specified serial number. 799Serial numbers are 64-bit values, not including zero and may be expressed 800in decimal, hex or octal. 801If two serial numbers are specified separated by a hyphen, then the range 802of serial numbers including and between each is revoked. 803The CA key must have been specified on the 804.Nm 805command line using the 806.Fl s 807option. 808.It Cm id : Ar key_id 809Revokes a certificate with the specified key ID string. 810The CA key must have been specified on the 811.Nm 812command line using the 813.Fl s 814option. 815.It Cm key : Ar public_key 816Revokes the specified key. 817If a certificate is listed, then it is revoked as a plain public key. 818.It Cm sha1 : Ar public_key 819Revokes the specified key by including its SHA1 hash in the KRL. 820.It Cm sha256 : Ar public_key 821Revokes the specified key by including its SHA256 hash in the KRL. 822KRLs that revoke keys by SHA256 hash are not supported by OpenSSH versions 823prior to 7.9. 824.It Cm hash : Ar fingerprint 825Revokes a key using a fingerprint hash, as obtained from a 826.Xr sshd 8 827authentication log message or the 828.Nm 829.Fl l 830flag. 831Only SHA256 fingerprints are supported here and resultant KRLs are 832not supported by OpenSSH versions prior to 7.9. 833.El 834.Pp 835KRLs may be updated using the 836.Fl u 837flag in addition to 838.Fl k . 839When this option is specified, keys listed via the command line are merged into 840the KRL, adding to those already there. 841.Pp 842It is also possible, given a KRL, to test whether it revokes a particular key 843(or keys). 844The 845.Fl Q 846flag will query an existing KRL, testing each key specified on the command line. 847If any key listed on the command line has been revoked (or an error encountered) 848then 849.Nm 850will exit with a non-zero exit status. 851A zero exit status will only be returned if no key was revoked. 852.Sh FILES 853.Bl -tag -width Ds -compact 854.It Pa ~/.ssh/id_dsa 855.It Pa ~/.ssh/id_ecdsa 856.It Pa ~/.ssh/id_ed25519 857.It Pa ~/.ssh/id_rsa 858Contains the DSA, ECDSA, Ed25519 or RSA 859authentication identity of the user. 860This file should not be readable by anyone but the user. 861It is possible to 862specify a passphrase when generating the key; that passphrase will be 863used to encrypt the private part of this file using 128-bit AES. 864This file is not automatically accessed by 865.Nm 866but it is offered as the default file for the private key. 867.Xr ssh 1 868will read this file when a login attempt is made. 869.Pp 870.It Pa ~/.ssh/id_dsa.pub 871.It Pa ~/.ssh/id_ecdsa.pub 872.It Pa ~/.ssh/id_ed25519.pub 873.It Pa ~/.ssh/id_rsa.pub 874Contains the DSA, ECDSA, Ed25519 or RSA 875public key for authentication. 876The contents of this file should be added to 877.Pa ~/.ssh/authorized_keys 878on all machines 879where the user wishes to log in using public key authentication. 880There is no need to keep the contents of this file secret. 881.Pp 882.It Pa /etc/moduli 883Contains Diffie-Hellman groups used for DH-GEX. 884The file format is described in 885.Xr moduli 5 . 886.El 887.Sh SEE ALSO 888.Xr ssh 1 , 889.Xr ssh-add 1 , 890.Xr ssh-agent 1 , 891.Xr moduli 5 , 892.Xr sshd 8 893.Rs 894.%R RFC 4716 895.%T "The Secure Shell (SSH) Public Key File Format" 896.%D 2006 897.Re 898.Sh AUTHORS 899OpenSSH is a derivative of the original and free 900ssh 1.2.12 release by Tatu Ylonen. 901Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 902Theo de Raadt and Dug Song 903removed many bugs, re-added newer features and 904created OpenSSH. 905Markus Friedl contributed the support for SSH 906protocol versions 1.5 and 2.0. 907