diff options
Diffstat (limited to 'ssh-keygen.1')
| -rw-r--r-- | ssh-keygen.1 | 193 |
1 files changed, 175 insertions, 18 deletions
diff --git a/ssh-keygen.1 b/ssh-keygen.1 index 41da2077..0e0ed989 100644 --- a/ssh-keygen.1 +++ b/ssh-keygen.1 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ssh-keygen.1,v 1.108 2011/10/16 11:02:46 dtucker Exp $ +.\" $OpenBSD: ssh-keygen.1,v 1.119 2013/12/21 07:10:47 tedu Exp $ .\" .\" Author: Tatu Ylonen <ylo@cs.hut.fi> .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland @@ -35,7 +35,7 @@ .\" (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: October 16 2011 $ +.Dd $Mdocdate: December 21 2013 $ .Dt SSH-KEYGEN 1 .Os .Sh NAME @@ -103,7 +103,9 @@ .Fl T Ar output_file .Fl f Ar input_file .Op Fl v -.Op Fl a Ar num_trials +.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 @@ -120,14 +122,25 @@ .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. +can create RSA keys for use by SSH protocol version 1 and +DSA, ECDSA, ED25519 or RSA keys for use by SSH protocol version 2. The type of key to be generated is specified with the .Fl t option. @@ -142,12 +155,21 @@ 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_dsa , .Pa ~/.ssh/id_ecdsa , -.Pa ~/.ssh/id_dsa +.Pa ~/.ssh/id_ed25519 or .Pa ~/.ssh/id_rsa . Additionally, the system administrator may use this to generate host keys, @@ -195,17 +217,27 @@ should be placed to be activated. 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 +For each of the key types (rsa1, 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. This is used by .Pa /etc/rc to generate new host keys. -.It Fl a Ar trials -Specifies the number of primality tests to perform when screening DH-GEX -candidates using the +.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. +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 @@ -219,6 +251,9 @@ 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 @@ -297,6 +332,16 @@ 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 @@ -309,6 +354,17 @@ 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 @@ -405,6 +461,14 @@ 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 @@ -413,6 +477,8 @@ 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 . @@ -436,6 +502,14 @@ 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 @@ -446,10 +520,17 @@ The possible values are .Dq rsa1 for protocol version 1 and .Dq dsa , -.Dq ecdsa +.Dq ecdsa , +.Dq ed25519 , 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 @@ -458,8 +539,7 @@ 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 -.Sx TIME FORMATS -section of +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. @@ -492,6 +572,10 @@ OpenSSH format file and print an OpenSSH public key to stdout. 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 @@ -518,7 +602,7 @@ 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 tested for +Once a set of candidates have been generated, they must be screened for suitability. This may be performed using the .Fl T @@ -616,7 +700,9 @@ The 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 have a maximum validity interval. +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 @@ -624,6 +710,73 @@ public key must be trusted by 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 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 @@ -648,8 +801,10 @@ 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_ed25519 .It Pa ~/.ssh/id_rsa -Contains the protocol version 2 DSA, ECDSA or RSA authentication identity of the user. +Contains the protocol version 2 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 @@ -662,8 +817,10 @@ 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 protocol version 2 DSA, ECDSA or RSA public key for authentication. +Contains the protocol version 2 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 |