| .\" $OpenBSD: ssh-keygen.1,v 1.117 2013/12/07 08:08:26 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: December 7 2013 $ |
| .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 |
| .Fl t Ar type |
| .Op Fl N Ar new_passphrase |
| .Op Fl C Ar comment |
| .Op Fl f Ar output_keyfile |
| .Nm ssh-keygen |
| .Fl p |
| .Op Fl P Ar old_passphrase |
| .Op Fl N Ar new_passphrase |
| .Op Fl f Ar keyfile |
| .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 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 |
| .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 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 |
| .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 RSA keys for use by SSH protocol version 1 and DSA, ECDSA or RSA |
| keys for use by SSH protocol version 2. |
| 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 for use in SSH protocol 2 connections. |
| .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/identity , |
| .Pa ~/.ssh/id_ecdsa , |
| .Pa ~/.ssh/id_dsa |
| 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 |
| For RSA1 keys, |
| there is also a comment field in the key file that is only for |
| convenience to the user to help identify the key. |
| The comment can tell what the key is for, or whatever is useful. |
| The comment is initialized to |
| .Dq user@host |
| when the key is created, but can be changed using the |
| .Fl c |
| option. |
| .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 (rsa1, rsa, dsa and ecdsa) 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. |
| This is used by |
| .Pa /etc/rc |
| to generate new host keys. |
| .It Fl a Ar rounds |
| When saving a new-format private key (i.e. an ed25519 key or any SSH protocol |
| 2 key when the |
| .Fl o |
| flag is set), 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 768 bits and the default is 2048 bits. |
| Generally, 2048 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. |
| .It Fl C Ar comment |
| Provides a new comment. |
| .It Fl c |
| Requests changing the comment in the private and public key files. |
| This operation is only supported for RSA1 keys. |
| 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 RSA 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 |
| This option will read a private or public OpenSSH key file and |
| print to stdout the 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 |
| Search for the specified |
| .Ar hostname |
| 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. |
| .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. |
| This option allows importing keys from other software, including several |
| commercial SSH implementations. |
| The default import format is |
| .Dq RFC4716 . |
| .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 a certificate. |
| .It Fl l |
| Show fingerprint of specified public key file. |
| Private RSA1 keys are also supported. |
| For RSA and DSA keys |
| .Nm |
| tries to find the matching public key file and prints its fingerprint. |
| If combined with |
| .Fl v , |
| an 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 the |
| .Fl i |
| (import) or |
| .Fl e |
| (export) conversion options. |
| The supported key formats are: |
| .Dq RFC4716 |
| (RFC 4716/SSH2 public or private key), |
| .Dq PKCS8 |
| (PEM PKCS8 public key) |
| or |
| .Dq PEM |
| (PEM public key). |
| The default conversion format is |
| .Dq RFC4716 . |
| .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. |
| Please see the |
| .Sx CERTIFICATES |
| section for details. |
| The options that are valid for user certificates are: |
| .Bl -tag -width Ds |
| .It Ic clear |
| Clear all enabled permissions. |
| This is useful for clearing the default set of permissions so permissions may |
| be added individually. |
| .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. |
| .It Ic no-agent-forwarding |
| Disable |
| .Xr ssh-agent 1 |
| forwarding (permitted by default). |
| .It Ic no-port-forwarding |
| Disable port forwarding (permitted by default). |
| .It Ic no-pty |
| Disable PTY allocation (permitted by default). |
| .It Ic no-user-rc |
| Disable execution of |
| .Pa ~/.ssh/rc |
| by |
| .Xr sshd 8 |
| (permitted by default). |
| .It Ic no-x11-forwarding |
| Disable X11 forwarding (permitted by default). |
| .It Ic permit-agent-forwarding |
| Allows |
| .Xr ssh-agent 1 |
| forwarding. |
| .It Ic permit-port-forwarding |
| Allows port forwarding. |
| .It Ic permit-pty |
| Allows PTY allocation. |
| .It Ic permit-user-rc |
| Allows execution of |
| .Pa ~/.ssh/rc |
| by |
| .Xr sshd 8 . |
| .It Ic permit-x11-forwarding |
| Allows X11 forwarding. |
| .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 |
| .Pp |
| At present, no options are valid for host keys. |
| .It Fl o |
| Causes |
| .Nm |
| to save SSH protocol 2 private keys using the new OpenSSH format rather than |
| the more compatible PEM format. |
| The new format has increased resistance to brute-force password cracking |
| but is not supported by versions of OpenSSH prior to 6.5. |
| Ed25519 keys always use the new private key format. |
| .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 |
| Removes all keys belonging to |
| .Ar hostname |
| 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 Ar type |
| Specifies the type of key to create. |
| The possible values are |
| .Dq rsa1 |
| for protocol version 1 and |
| .Dq dsa , |
| .Dq ecdsa |
| or |
| .Dq rsa |
| for protocol version 2. |
| .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. |
| The start time may be specified as a date in YYYYMMDD format, a time |
| in YYYYMMDDHHMMSS format or a relative time (to the current time) consisting |
| of a minus sign followed by a relative time in the format described in the |
| TIME FORMATS section of |
| .Xr sshd_config 5 . |
| The end time may be specified as a YYYYMMDD date, a YYYYMMDDHHMMSS time or |
| a relative time starting with a plus character. |
| .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). |
| .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. |
| 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 host_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 user_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 a 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 its SHA1 hash. |
| .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 commandline. |
| 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/identity |
| Contains the protocol version 1 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 3DES. |
| 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/identity.pub |
| Contains the protocol version 1 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 RSA authentication. |
| There is no need to keep the contents of this file secret. |
| .Pp |
| .It Pa ~/.ssh/id_dsa |
| .It Pa ~/.ssh/id_ecdsa |
| .It Pa ~/.ssh/id_rsa |
| Contains the protocol version 2 DSA, ECDSA 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_rsa.pub |
| Contains the protocol version 2 DSA, ECDSA 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. |