| .\" $OpenBSD: ssh-keygen.1,v 1.162 2019/07/19 03:38:01 djm Exp $ |
| .\" |
| .\" Author: Tatu Ylonen <ylo@cs.hut.fi> |
| .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland |
| .\" All rights reserved |
| .\" |
| .\" As far as I am concerned, the code I have written for this software |
| .\" can be used freely for any purpose. Any derived versions of this |
| .\" software must be clearly marked as such, and if the derived work is |
| .\" incompatible with the protocol description in the RFC file, it must be |
| .\" called by a name other than "ssh" or "Secure Shell". |
| .\" |
| .\" |
| .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. |
| .\" Copyright (c) 1999 Aaron Campbell. All rights reserved. |
| .\" Copyright (c) 1999 Theo de Raadt. All rights reserved. |
| .\" |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR |
| .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
| .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
| .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, |
| .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
| .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
| .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| .\" |
| .Dd $Mdocdate: July 19 2019 $ |
| .Dt SSH-KEYGEN 1 |
| .Os |
| .Sh NAME |
| .Nm ssh-keygen |
| .Nd authentication key generation, management and conversion |
| .Sh SYNOPSIS |
| .Bk -words |
| .Nm ssh-keygen |
| .Op Fl q |
| .Op Fl b Ar bits |
| .Op Fl t Cm dsa | ecdsa | ed25519 | rsa |
| .Op Fl N Ar new_passphrase |
| .Op Fl C Ar comment |
| .Op Fl f Ar output_keyfile |
| .Op Fl m Ar format |
| .Nm ssh-keygen |
| .Fl p |
| .Op Fl P Ar old_passphrase |
| .Op Fl N Ar new_passphrase |
| .Op Fl f Ar keyfile |
| .Op Fl m Ar format |
| .Nm ssh-keygen |
| .Fl i |
| .Op Fl m Ar key_format |
| .Op Fl f Ar input_keyfile |
| .Nm ssh-keygen |
| .Fl e |
| .Op Fl m Ar key_format |
| .Op Fl f Ar input_keyfile |
| .Nm ssh-keygen |
| .Fl y |
| .Op Fl f Ar input_keyfile |
| .Nm ssh-keygen |
| .Fl c |
| .Op Fl P Ar passphrase |
| .Op Fl C Ar comment |
| .Op Fl f Ar keyfile |
| .Nm ssh-keygen |
| .Fl l |
| .Op Fl v |
| .Op Fl E Ar fingerprint_hash |
| .Op Fl f Ar input_keyfile |
| .Nm ssh-keygen |
| .Fl B |
| .Op Fl f Ar input_keyfile |
| .Nm ssh-keygen |
| .Fl D Ar pkcs11 |
| .Nm ssh-keygen |
| .Fl F Ar hostname |
| .Op Fl f Ar known_hosts_file |
| .Op Fl l |
| .Op Fl v |
| .Nm ssh-keygen |
| .Fl H |
| .Op Fl f Ar known_hosts_file |
| .Nm ssh-keygen |
| .Fl R Ar hostname |
| .Op Fl f Ar known_hosts_file |
| .Nm ssh-keygen |
| .Fl r Ar hostname |
| .Op Fl f Ar input_keyfile |
| .Op Fl g |
| .Nm ssh-keygen |
| .Fl G Ar output_file |
| .Op Fl v |
| .Op Fl b Ar bits |
| .Op Fl M Ar memory |
| .Op Fl S Ar start_point |
| .Nm ssh-keygen |
| .Fl T Ar output_file |
| .Fl f Ar input_file |
| .Op Fl v |
| .Op Fl a Ar rounds |
| .Op Fl J Ar num_lines |
| .Op Fl j Ar start_line |
| .Op Fl K Ar checkpt |
| .Op Fl W Ar generator |
| .Nm ssh-keygen |
| .Fl s Ar ca_key |
| .Fl I Ar certificate_identity |
| .Op Fl h |
| .Op Fl U |
| .Op Fl D Ar pkcs11_provider |
| .Op Fl n Ar principals |
| .Op Fl O Ar option |
| .Op Fl V Ar validity_interval |
| .Op Fl z Ar serial_number |
| .Ar |
| .Nm ssh-keygen |
| .Fl L |
| .Op Fl f Ar input_keyfile |
| .Nm ssh-keygen |
| .Fl A |
| .Op Fl f Ar prefix_path |
| .Nm ssh-keygen |
| .Fl k |
| .Fl f Ar krl_file |
| .Op Fl u |
| .Op Fl s Ar ca_public |
| .Op Fl z Ar version_number |
| .Ar |
| .Nm ssh-keygen |
| .Fl Q |
| .Fl f Ar krl_file |
| .Ar |
| .Ek |
| .Sh DESCRIPTION |
| .Nm |
| generates, manages and converts authentication keys for |
| .Xr ssh 1 . |
| .Nm |
| can create keys for use by SSH protocol version 2. |
| .Pp |
| The type of key to be generated is specified with the |
| .Fl t |
| option. |
| If invoked without any arguments, |
| .Nm |
| will generate an RSA key. |
| .Pp |
| .Nm |
| is also used to generate groups for use in Diffie-Hellman group |
| exchange (DH-GEX). |
| See the |
| .Sx MODULI GENERATION |
| section for details. |
| .Pp |
| Finally, |
| .Nm |
| can be used to generate and update Key Revocation Lists, and to test whether |
| given keys have been revoked by one. |
| See the |
| .Sx KEY REVOCATION LISTS |
| section for details. |
| .Pp |
| Normally each user wishing to use SSH |
| with public key authentication runs this once to create the authentication |
| key in |
| .Pa ~/.ssh/id_dsa , |
| .Pa ~/.ssh/id_ecdsa , |
| .Pa ~/.ssh/id_ed25519 |
| or |
| .Pa ~/.ssh/id_rsa . |
| Additionally, the system administrator may use this to generate host keys, |
| as seen in |
| .Pa /etc/rc . |
| .Pp |
| Normally this program generates the key and asks for a file in which |
| to store the private key. |
| The public key is stored in a file with the same name but |
| .Dq .pub |
| appended. |
| The program also asks for a passphrase. |
| The passphrase may be empty to indicate no passphrase |
| (host keys must have an empty passphrase), or it may be a string of |
| arbitrary length. |
| A passphrase is similar to a password, except it can be a phrase with a |
| series of words, punctuation, numbers, whitespace, or any string of |
| characters you want. |
| Good passphrases are 10-30 characters long, are |
| not simple sentences or otherwise easily guessable (English |
| prose has only 1-2 bits of entropy per character, and provides very bad |
| passphrases), and contain a mix of upper and lowercase letters, |
| numbers, and non-alphanumeric characters. |
| The passphrase can be changed later by using the |
| .Fl p |
| option. |
| .Pp |
| There is no way to recover a lost passphrase. |
| If the passphrase is lost or forgotten, a new key must be generated |
| and the corresponding public key copied to other machines. |
| .Pp |
| .Nm |
| will by default write keys in an OpenSSH-specific format. |
| This format is preferred as it offers better protection for |
| keys at rest as well as allowing storage of key comments within |
| the private key file itself. |
| The key comment may be useful to help identify the key. |
| The comment is initialized to |
| .Dq user@host |
| when the key is created, but can be changed using the |
| .Fl c |
| option. |
| .Pp |
| It is still possible for |
| .Nm |
| to write the previously-used PEM format private keys using the |
| .Fl m |
| flag. |
| This may be used when generating new keys, and existing new-format |
| keys may be converted using this option in conjunction with the |
| .Fl p |
| (change passphrase) flag. |
| .Pp |
| After a key is generated, instructions below detail where the keys |
| should be placed to be activated. |
| .Pp |
| The options are as follows: |
| .Bl -tag -width Ds |
| .It Fl A |
| For each of the key types (rsa, dsa, ecdsa and ed25519) |
| for which host keys |
| do not exist, generate the host keys with the default key file path, |
| an empty passphrase, default bits for the key type, and default comment. |
| If |
| .Fl f |
| has also been specified, its argument is used as a prefix to the |
| default path for the resulting host key files. |
| This is used by |
| .Pa /etc/rc |
| to generate new host keys. |
| .It Fl a Ar rounds |
| When saving a private key this option specifies the number of KDF |
| (key derivation function) rounds used. |
| Higher numbers result in slower passphrase verification and increased |
| resistance to brute-force password cracking (should the keys be stolen). |
| .Pp |
| When screening DH-GEX candidates (using the |
| .Fl T |
| command). |
| This option specifies the number of primality tests to perform. |
| .It Fl B |
| Show the bubblebabble digest of specified private or public key file. |
| .It Fl b Ar bits |
| Specifies the number of bits in the key to create. |
| For RSA keys, the minimum size is 1024 bits and the default is 3072 bits. |
| Generally, 3072 bits is considered sufficient. |
| DSA keys must be exactly 1024 bits as specified by FIPS 186-2. |
| For ECDSA keys, the |
| .Fl b |
| flag determines the key length by selecting from one of three elliptic |
| curve sizes: 256, 384 or 521 bits. |
| Attempting to use bit lengths other than these three values for ECDSA keys |
| will fail. |
| Ed25519 keys have a fixed length and the |
| .Fl b |
| flag will be ignored. |
| .It Fl C Ar comment |
| Provides a new comment. |
| .It Fl c |
| Requests changing the comment in the private and public key files. |
| The program will prompt for the file containing the private keys, for |
| the passphrase if the key has one, and for the new comment. |
| .It Fl D Ar pkcs11 |
| Download the public keys provided by the PKCS#11 shared library |
| .Ar pkcs11 . |
| When used in combination with |
| .Fl s , |
| this option indicates that a CA key resides in a PKCS#11 token (see the |
| .Sx CERTIFICATES |
| section for details). |
| .It Fl E Ar fingerprint_hash |
| Specifies the hash algorithm used when displaying key fingerprints. |
| Valid options are: |
| .Dq md5 |
| and |
| .Dq sha256 . |
| The default is |
| .Dq sha256 . |
| .It Fl e |
| This option will read a private or public OpenSSH key file and |
| print to stdout a public key in one of the formats specified by the |
| .Fl m |
| option. |
| The default export format is |
| .Dq RFC4716 . |
| This option allows exporting OpenSSH keys for use by other programs, including |
| several commercial SSH implementations. |
| .It Fl F Ar hostname | [hostname]:port |
| Search for the specified |
| .Ar hostname |
| (with optional port number) |
| in a |
| .Pa known_hosts |
| file, listing any occurrences found. |
| This option is useful to find hashed host names or addresses and may also be |
| used in conjunction with the |
| .Fl H |
| option to print found keys in a hashed format. |
| .It Fl f Ar filename |
| Specifies the filename of the key file. |
| .It Fl G Ar output_file |
| Generate candidate primes for DH-GEX. |
| These primes must be screened for |
| safety (using the |
| .Fl T |
| option) before use. |
| .It Fl g |
| Use generic DNS format when printing fingerprint resource records using the |
| .Fl r |
| command. |
| .It Fl H |
| Hash a |
| .Pa known_hosts |
| file. |
| This replaces all hostnames and addresses with hashed representations |
| within the specified file; the original content is moved to a file with |
| a .old suffix. |
| These hashes may be used normally by |
| .Nm ssh |
| and |
| .Nm sshd , |
| but they do not reveal identifying information should the file's contents |
| be disclosed. |
| This option will not modify existing hashed hostnames and is therefore safe |
| to use on files that mix hashed and non-hashed names. |
| .It Fl h |
| When signing a key, create a host certificate instead of a user |
| certificate. |
| Please see the |
| .Sx CERTIFICATES |
| section for details. |
| .It Fl I Ar certificate_identity |
| Specify the key identity when signing a public key. |
| Please see the |
| .Sx CERTIFICATES |
| section for details. |
| .It Fl i |
| This option will read an unencrypted private (or public) key file |
| in the format specified by the |
| .Fl m |
| option and print an OpenSSH compatible private |
| (or public) key to stdout. |
| This option allows importing keys from other software, including several |
| commercial SSH implementations. |
| The default import format is |
| .Dq RFC4716 . |
| .It Fl J Ar num_lines |
| Exit after screening the specified number of lines |
| while performing DH candidate screening using the |
| .Fl T |
| option. |
| .It Fl j Ar start_line |
| Start screening at the specified line number |
| while performing DH candidate screening using the |
| .Fl T |
| option. |
| .It Fl K Ar checkpt |
| Write the last line processed to the file |
| .Ar checkpt |
| while performing DH candidate screening using the |
| .Fl T |
| option. |
| This will be used to skip lines in the input file that have already been |
| processed if the job is restarted. |
| .It Fl k |
| Generate a KRL file. |
| In this mode, |
| .Nm |
| will generate a KRL file at the location specified via the |
| .Fl f |
| flag that revokes every key or certificate presented on the command line. |
| Keys/certificates to be revoked may be specified by public key file or |
| using the format described in the |
| .Sx KEY REVOCATION LISTS |
| section. |
| .It Fl L |
| Prints the contents of one or more certificates. |
| .It Fl l |
| Show fingerprint of specified public key file. |
| For RSA and DSA keys |
| .Nm |
| tries to find the matching public key file and prints its fingerprint. |
| If combined with |
| .Fl v , |
| a visual ASCII art representation of the key is supplied with the |
| fingerprint. |
| .It Fl M Ar memory |
| Specify the amount of memory to use (in megabytes) when generating |
| candidate moduli for DH-GEX. |
| .It Fl m Ar key_format |
| Specify a key format for key generation, the |
| .Fl i |
| (import), |
| .Fl e |
| (export) conversion options, and the |
| .Fl p |
| change passphrase operation. |
| The latter may be used to convert between OpenSSH private key and PEM |
| private key formats. |
| The supported key formats are: |
| .Dq RFC4716 |
| (RFC 4716/SSH2 public or private key), |
| .Dq PKCS8 |
| (PKCS8 public or private key) |
| or |
| .Dq PEM |
| (PEM public key). |
| By default OpenSSH will write newly-generated private keys in its own |
| format, but when converting public keys for export the default format is |
| .Dq RFC4716 . |
| Setting a format of |
| .Dq PEM |
| when generating or updating a supported private key type will cause the |
| key to be stored in the legacy PEM private key format. |
| .It Fl N Ar new_passphrase |
| Provides the new passphrase. |
| .It Fl n Ar principals |
| Specify one or more principals (user or host names) to be included in |
| a certificate when signing a key. |
| Multiple principals may be specified, separated by commas. |
| Please see the |
| .Sx CERTIFICATES |
| section for details. |
| .It Fl O Ar option |
| Specify a certificate option when signing a key. |
| This option may be specified multiple times. |
| See also the |
| .Sx CERTIFICATES |
| section for further details. |
| .Pp |
| At present, no standard options are valid for host keys. |
| The options that are valid for user certificates are: |
| .Pp |
| .Bl -tag -width Ds -compact |
| .It Ic clear |
| Clear all enabled permissions. |
| This is useful for clearing the default set of permissions so permissions may |
| be added individually. |
| .Pp |
| .It Ic critical : Ns Ar name Ns Op Ns = Ns Ar contents |
| .It Ic extension : Ns Ar name Ns Op Ns = Ns Ar contents |
| Includes an arbitrary certificate critical option or extension. |
| The specified |
| .Ar name |
| should include a domain suffix, e.g.\& |
| .Dq name@example.com . |
| If |
| .Ar contents |
| is specified then it is included as the contents of the extension/option |
| encoded as a string, otherwise the extension/option is created with no |
| contents (usually indicating a flag). |
| Extensions may be ignored by a client or server that does not recognise them, |
| whereas unknown critical options will cause the certificate to be refused. |
| .Pp |
| .It Ic force-command Ns = Ns Ar command |
| Forces the execution of |
| .Ar command |
| instead of any shell or command specified by the user when |
| the certificate is used for authentication. |
| .Pp |
| .It Ic no-agent-forwarding |
| Disable |
| .Xr ssh-agent 1 |
| forwarding (permitted by default). |
| .Pp |
| .It Ic no-port-forwarding |
| Disable port forwarding (permitted by default). |
| .Pp |
| .It Ic no-pty |
| Disable PTY allocation (permitted by default). |
| .Pp |
| .It Ic no-user-rc |
| Disable execution of |
| .Pa ~/.ssh/rc |
| by |
| .Xr sshd 8 |
| (permitted by default). |
| .Pp |
| .It Ic no-x11-forwarding |
| Disable X11 forwarding (permitted by default). |
| .Pp |
| .It Ic permit-agent-forwarding |
| Allows |
| .Xr ssh-agent 1 |
| forwarding. |
| .Pp |
| .It Ic permit-port-forwarding |
| Allows port forwarding. |
| .Pp |
| .It Ic permit-pty |
| Allows PTY allocation. |
| .Pp |
| .It Ic permit-user-rc |
| Allows execution of |
| .Pa ~/.ssh/rc |
| by |
| .Xr sshd 8 . |
| .Pp |
| .It Ic permit-X11-forwarding |
| Allows X11 forwarding. |
| .Pp |
| .It Ic source-address Ns = Ns Ar address_list |
| Restrict the source addresses from which the certificate is considered valid. |
| The |
| .Ar address_list |
| is a comma-separated list of one or more address/netmask pairs in CIDR |
| format. |
| .El |
| .It Fl P Ar passphrase |
| Provides the (old) passphrase. |
| .It Fl p |
| Requests changing the passphrase of a private key file instead of |
| creating a new private key. |
| The program will prompt for the file |
| containing the private key, for the old passphrase, and twice for the |
| new passphrase. |
| .It Fl Q |
| Test whether keys have been revoked in a KRL. |
| .It Fl q |
| Silence |
| .Nm ssh-keygen . |
| .It Fl R Ar hostname | [hostname]:port |
| Removes all keys belonging to the specified |
| .Ar hostname |
| (with optional port number) |
| from a |
| .Pa known_hosts |
| file. |
| This option is useful to delete hashed hosts (see the |
| .Fl H |
| option above). |
| .It Fl r Ar hostname |
| Print the SSHFP fingerprint resource record named |
| .Ar hostname |
| for the specified public key file. |
| .It Fl S Ar start |
| Specify start point (in hex) when generating candidate moduli for DH-GEX. |
| .It Fl s Ar ca_key |
| Certify (sign) a public key using the specified CA key. |
| Please see the |
| .Sx CERTIFICATES |
| section for details. |
| .Pp |
| When generating a KRL, |
| .Fl s |
| specifies a path to a CA public key file used to revoke certificates directly |
| by key ID or serial number. |
| See the |
| .Sx KEY REVOCATION LISTS |
| section for details. |
| .It Fl T Ar output_file |
| Test DH group exchange candidate primes (generated using the |
| .Fl G |
| option) for safety. |
| .It Fl t Cm dsa | ecdsa | ed25519 | rsa |
| Specifies the type of key to create. |
| The possible values are |
| .Dq dsa , |
| .Dq ecdsa , |
| .Dq ed25519 , |
| or |
| .Dq rsa . |
| .Pp |
| This flag may also be used to specify the desired signature type when |
| signing certificates using an RSA CA key. |
| The available RSA signature variants are |
| .Dq ssh-rsa |
| (SHA1 signatures, not recommended), |
| .Dq rsa-sha2-256 , |
| and |
| .Dq rsa-sha2-512 |
| (the default). |
| .It Fl U |
| When used in combination with |
| .Fl s , |
| this option indicates that a CA key resides in a |
| .Xr ssh-agent 1 . |
| See the |
| .Sx CERTIFICATES |
| section for more information. |
| .It Fl u |
| Update a KRL. |
| When specified with |
| .Fl k , |
| keys listed via the command line are added to the existing KRL rather than |
| a new KRL being created. |
| .It Fl V Ar validity_interval |
| Specify a validity interval when signing a certificate. |
| A validity interval may consist of a single time, indicating that the |
| certificate is valid beginning now and expiring at that time, or may consist |
| of two times separated by a colon to indicate an explicit time interval. |
| .Pp |
| The start time may be specified as the string |
| .Dq always |
| to indicate the certificate has no specified start time, |
| a date in YYYYMMDD format, a time in YYYYMMDDHHMM[SS] format, |
| a relative time (to the current time) consisting of a minus sign followed by |
| an interval in the format described in the |
| TIME FORMATS section of |
| .Xr sshd_config 5 . |
| .Pp |
| The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMM[SS] time, |
| a relative time starting with a plus character or the string |
| .Dq forever |
| to indicate that the certificate has no expirty date. |
| .Pp |
| For example: |
| .Dq +52w1d |
| (valid from now to 52 weeks and one day from now), |
| .Dq -4w:+4w |
| (valid from four weeks ago to four weeks from now), |
| .Dq 20100101123000:20110101123000 |
| (valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011), |
| .Dq -1d:20110101 |
| (valid from yesterday to midnight, January 1st, 2011). |
| .Dq -1m:forever |
| (valid from one minute ago and never expiring). |
| .It Fl v |
| Verbose mode. |
| Causes |
| .Nm |
| to print debugging messages about its progress. |
| This is helpful for debugging moduli generation. |
| Multiple |
| .Fl v |
| options increase the verbosity. |
| The maximum is 3. |
| .It Fl W Ar generator |
| Specify desired generator when testing candidate moduli for DH-GEX. |
| .It Fl y |
| This option will read a private |
| OpenSSH format file and print an OpenSSH public key to stdout. |
| .It Fl z Ar serial_number |
| Specifies a serial number to be embedded in the certificate to distinguish |
| this certificate from others from the same CA. |
| If the |
| .Ar serial_number |
| is prefixed with a |
| .Sq + |
| character, then the serial number will be incremented for each certificate |
| signed on a single command-line. |
| The default serial number is zero. |
| .Pp |
| When generating a KRL, the |
| .Fl z |
| flag is used to specify a KRL version number. |
| .El |
| .Sh MODULI GENERATION |
| .Nm |
| may be used to generate groups for the Diffie-Hellman Group Exchange |
| (DH-GEX) protocol. |
| Generating these groups is a two-step process: first, candidate |
| primes are generated using a fast, but memory intensive process. |
| These candidate primes are then tested for suitability (a CPU-intensive |
| process). |
| .Pp |
| Generation of primes is performed using the |
| .Fl G |
| option. |
| The desired length of the primes may be specified by the |
| .Fl b |
| option. |
| For example: |
| .Pp |
| .Dl # ssh-keygen -G moduli-2048.candidates -b 2048 |
| .Pp |
| By default, the search for primes begins at a random point in the |
| desired length range. |
| This may be overridden using the |
| .Fl S |
| option, which specifies a different start point (in hex). |
| .Pp |
| Once a set of candidates have been generated, they must be screened for |
| suitability. |
| This may be performed using the |
| .Fl T |
| option. |
| In this mode |
| .Nm |
| will read candidates from standard input (or a file specified using the |
| .Fl f |
| option). |
| For example: |
| .Pp |
| .Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates |
| .Pp |
| By default, each candidate will be subjected to 100 primality tests. |
| This may be overridden using the |
| .Fl a |
| option. |
| The DH generator value will be chosen automatically for the |
| prime under consideration. |
| If a specific generator is desired, it may be requested using the |
| .Fl W |
| option. |
| Valid generator values are 2, 3, and 5. |
| .Pp |
| Screened DH groups may be installed in |
| .Pa /etc/moduli . |
| It is important that this file contains moduli of a range of bit lengths and |
| that both ends of a connection share common moduli. |
| .Sh CERTIFICATES |
| .Nm |
| supports signing of keys to produce certificates that may be used for |
| user or host authentication. |
| Certificates consist of a public key, some identity information, zero or |
| more principal (user or host) names and a set of options that |
| are signed by a Certification Authority (CA) key. |
| Clients or servers may then trust only the CA key and verify its signature |
| on a certificate rather than trusting many user/host keys. |
| Note that OpenSSH certificates are a different, and much simpler, format to |
| the X.509 certificates used in |
| .Xr ssl 8 . |
| .Pp |
| .Nm |
| supports two types of certificates: user and host. |
| User certificates authenticate users to servers, whereas host certificates |
| authenticate server hosts to users. |
| To generate a user certificate: |
| .Pp |
| .Dl $ ssh-keygen -s /path/to/ca_key -I key_id /path/to/user_key.pub |
| .Pp |
| The resultant certificate will be placed in |
| .Pa /path/to/user_key-cert.pub . |
| A host certificate requires the |
| .Fl h |
| option: |
| .Pp |
| .Dl $ ssh-keygen -s /path/to/ca_key -I key_id -h /path/to/host_key.pub |
| .Pp |
| The host certificate will be output to |
| .Pa /path/to/host_key-cert.pub . |
| .Pp |
| It is possible to sign using a CA key stored in a PKCS#11 token by |
| providing the token library using |
| .Fl D |
| and identifying the CA key by providing its public half as an argument |
| to |
| .Fl s : |
| .Pp |
| .Dl $ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id user_key.pub |
| .Pp |
| Similarly, it is possible for the CA key to be hosted in a |
| .Xr ssh-agent 1 . |
| This is indicated by the |
| .Fl U |
| flag and, again, the CA key must be identified by its public half. |
| .Pp |
| .Dl $ ssh-keygen -Us ca_key.pub -I key_id user_key.pub |
| .Pp |
| In all cases, |
| .Ar key_id |
| is a "key identifier" that is logged by the server when the certificate |
| is used for authentication. |
| .Pp |
| Certificates may be limited to be valid for a set of principal (user/host) |
| names. |
| By default, generated certificates are valid for all users or hosts. |
| To generate a certificate for a specified set of principals: |
| .Pp |
| .Dl $ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub |
| .Dl "$ ssh-keygen -s ca_key -I key_id -h -n host.domain host_key.pub" |
| .Pp |
| Additional limitations on the validity and use of user certificates may |
| be specified through certificate options. |
| A certificate option may disable features of the SSH session, may be |
| valid only when presented from particular source addresses or may |
| force the use of a specific command. |
| For a list of valid certificate options, see the documentation for the |
| .Fl O |
| option above. |
| .Pp |
| Finally, certificates may be defined with a validity lifetime. |
| The |
| .Fl V |
| option allows specification of certificate start and end times. |
| A certificate that is presented at a time outside this range will not be |
| considered valid. |
| By default, certificates are valid from |
| .Ux |
| Epoch to the distant future. |
| .Pp |
| For certificates to be used for user or host authentication, the CA |
| public key must be trusted by |
| .Xr sshd 8 |
| or |
| .Xr ssh 1 . |
| Please refer to those manual pages for details. |
| .Sh KEY REVOCATION LISTS |
| .Nm |
| is able to manage OpenSSH format Key Revocation Lists (KRLs). |
| These binary files specify keys or certificates to be revoked using a |
| compact format, taking as little as one bit per certificate if they are being |
| revoked by serial number. |
| .Pp |
| KRLs may be generated using the |
| .Fl k |
| flag. |
| This option reads one or more files from the command line and generates a new |
| KRL. |
| The files may either contain a KRL specification (see below) or public keys, |
| listed one per line. |
| Plain public keys are revoked by listing their hash or contents in the KRL and |
| certificates revoked by serial number or key ID (if the serial is zero or |
| not available). |
| .Pp |
| Revoking keys using a KRL specification offers explicit control over the |
| types of record used to revoke keys and may be used to directly revoke |
| certificates by serial number or key ID without having the complete original |
| certificate on hand. |
| A KRL specification consists of lines containing one of the following directives |
| followed by a colon and some directive-specific information. |
| .Bl -tag -width Ds |
| .It Cm serial : Ar serial_number Ns Op - Ns Ar serial_number |
| Revokes a certificate with the specified serial number. |
| Serial numbers are 64-bit values, not including zero and may be expressed |
| in decimal, hex or octal. |
| If two serial numbers are specified separated by a hyphen, then the range |
| of serial numbers including and between each is revoked. |
| The CA key must have been specified on the |
| .Nm |
| command line using the |
| .Fl s |
| option. |
| .It Cm id : Ar key_id |
| Revokes a certificate with the specified key ID string. |
| The CA key must have been specified on the |
| .Nm |
| command line using the |
| .Fl s |
| option. |
| .It Cm key : Ar public_key |
| Revokes the specified key. |
| If a certificate is listed, then it is revoked as a plain public key. |
| .It Cm sha1 : Ar public_key |
| Revokes the specified key by including its SHA1 hash in the KRL. |
| .It Cm sha256 : Ar public_key |
| Revokes the specified key by including its SHA256 hash in the KRL. |
| KRLs that revoke keys by SHA256 hash are not supported by OpenSSH versions |
| prior to 7.9. |
| .It Cm hash : Ar fingerprint |
| Revokes a key using a fingerprint hash, as obtained from a |
| .Xr sshd 8 |
| authentication log message or the |
| .Nm |
| .Fl l |
| flag. |
| Only SHA256 fingerprints are supported here and resultant KRLs are |
| not supported by OpenSSH versions prior to 7.9. |
| .El |
| .Pp |
| KRLs may be updated using the |
| .Fl u |
| flag in addition to |
| .Fl k . |
| When this option is specified, keys listed via the command line are merged into |
| the KRL, adding to those already there. |
| .Pp |
| It is also possible, given a KRL, to test whether it revokes a particular key |
| (or keys). |
| The |
| .Fl Q |
| flag will query an existing KRL, testing each key specified on the command line. |
| If any key listed on the command line has been revoked (or an error encountered) |
| then |
| .Nm |
| will exit with a non-zero exit status. |
| A zero exit status will only be returned if no key was revoked. |
| .Sh FILES |
| .Bl -tag -width Ds -compact |
| .It Pa ~/.ssh/id_dsa |
| .It Pa ~/.ssh/id_ecdsa |
| .It Pa ~/.ssh/id_ed25519 |
| .It Pa ~/.ssh/id_rsa |
| Contains the DSA, ECDSA, Ed25519 or RSA |
| authentication identity of the user. |
| This file should not be readable by anyone but the user. |
| It is possible to |
| specify a passphrase when generating the key; that passphrase will be |
| used to encrypt the private part of this file using 128-bit AES. |
| This file is not automatically accessed by |
| .Nm |
| but it is offered as the default file for the private key. |
| .Xr ssh 1 |
| will read this file when a login attempt is made. |
| .Pp |
| .It Pa ~/.ssh/id_dsa.pub |
| .It Pa ~/.ssh/id_ecdsa.pub |
| .It Pa ~/.ssh/id_ed25519.pub |
| .It Pa ~/.ssh/id_rsa.pub |
| Contains the DSA, ECDSA, Ed25519 or RSA |
| public key for authentication. |
| The contents of this file should be added to |
| .Pa ~/.ssh/authorized_keys |
| on all machines |
| where the user wishes to log in using public key authentication. |
| There is no need to keep the contents of this file secret. |
| .Pp |
| .It Pa /etc/moduli |
| Contains Diffie-Hellman groups used for DH-GEX. |
| The file format is described in |
| .Xr moduli 5 . |
| .El |
| .Sh SEE ALSO |
| .Xr ssh 1 , |
| .Xr ssh-add 1 , |
| .Xr ssh-agent 1 , |
| .Xr moduli 5 , |
| .Xr sshd 8 |
| .Rs |
| .%R RFC 4716 |
| .%T "The Secure Shell (SSH) Public Key File Format" |
| .%D 2006 |
| .Re |
| .Sh AUTHORS |
| OpenSSH is a derivative of the original and free |
| ssh 1.2.12 release by Tatu Ylonen. |
| Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, |
| Theo de Raadt and Dug Song |
| removed many bugs, re-added newer features and |
| created OpenSSH. |
| Markus Friedl contributed the support for SSH |
| protocol versions 1.5 and 2.0. |