summaryrefslogtreecommitdiffstats
path: root/upstream/opensuse-leap-15-6/man1/ssh-keygen.1
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-06-17 10:52:33 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-06-17 10:52:33 +0000
commit2c3307fb903f427be3d021c5780b75cac9af2ce8 (patch)
tree65cf431f40b7481d81ae2dfce9576342686448f7 /upstream/opensuse-leap-15-6/man1/ssh-keygen.1
parentReleasing progress-linux version 4.22.0-1~progress7.99u1. (diff)
downloadmanpages-l10n-2c3307fb903f427be3d021c5780b75cac9af2ce8.tar.xz
manpages-l10n-2c3307fb903f427be3d021c5780b75cac9af2ce8.zip
Merging upstream version 4.23.0.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'upstream/opensuse-leap-15-6/man1/ssh-keygen.1')
-rw-r--r--upstream/opensuse-leap-15-6/man1/ssh-keygen.1307
1 files changed, 222 insertions, 85 deletions
diff --git a/upstream/opensuse-leap-15-6/man1/ssh-keygen.1 b/upstream/opensuse-leap-15-6/man1/ssh-keygen.1
index e8f2aaca..0b87958d 100644
--- a/upstream/opensuse-leap-15-6/man1/ssh-keygen.1
+++ b/upstream/opensuse-leap-15-6/man1/ssh-keygen.1
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ssh-keygen.1,v 1.209 2020/09/09 03:08:01 djm Exp $
+.\" $OpenBSD: ssh-keygen.1,v 1.230 2023/09/04 10:29:58 job 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: September 9 2020 $
+.Dd $Mdocdate: September 4 2023 $
.Dt SSH-KEYGEN 1
.Os
.Sh NAME
@@ -53,6 +53,7 @@
.Op Fl O Ar option
.Op Fl t Cm dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa
.Op Fl w Ar provider
+.Op Fl Z Ar cipher
.Nm ssh-keygen
.Fl p
.Op Fl a Ar rounds
@@ -60,6 +61,7 @@
.Op Fl m Ar format
.Op Fl N Ar new_passphrase
.Op Fl P Ar old_passphrase
+.Op Fl Z Ar cipher
.Nm ssh-keygen
.Fl i
.Op Fl f Ar input_keyfile
@@ -145,19 +147,27 @@
.Ar
.Nm ssh-keygen
.Fl Y Cm find-principals
+.Op Fl O Ar option
.Fl s Ar signature_file
.Fl f Ar allowed_signers_file
.Nm ssh-keygen
+.Fl Y Cm match-principals
+.Fl I Ar signer_identity
+.Fl f Ar allowed_signers_file
+.Nm ssh-keygen
.Fl Y Cm check-novalidate
+.Op Fl O Ar option
.Fl n Ar namespace
.Fl s Ar signature_file
.Nm ssh-keygen
.Fl Y Cm sign
+.Op Fl O Ar option
.Fl f Ar key_file
.Fl n Ar namespace
.Ar
.Nm ssh-keygen
.Fl Y Cm verify
+.Op Fl O Ar option
.Fl f Ar allowed_signers_file
.Fl I Ar signer_identity
.Fl n Ar namespace
@@ -175,7 +185,7 @@ The type of key to be generated is specified with the
option.
If invoked without any arguments,
.Nm
-will generate an RSA key.
+will generate an Ed25519 key.
.Pp
.Nm
is also used to generate groups for use in Diffie-Hellman group
@@ -261,9 +271,9 @@ should be placed to be activated.
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,
+Generate host keys of all default key types (rsa, ecdsa, and
+ed25519) if they do not already exist.
+The host keys are generated with the default key file path,
an empty passphrase, default bits for the key type, and default comment.
If
.Fl f
@@ -274,7 +284,9 @@ This is used by
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.
+(key derivation function, currently
+.Xr bcrypt_pbkdf 3 )
+rounds used.
Higher numbers result in slower passphrase verification and increased
resistance to brute-force password cracking (should the keys be stolen).
The default is 16 rounds.
@@ -360,12 +372,12 @@ 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
+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
+See the
.Sx CERTIFICATES
section for details.
.It Fl i
@@ -384,6 +396,9 @@ Public and private key files will be written to the current directory for
each downloaded key.
If multiple FIDO authenticators are attached, keys will be downloaded from
the first touched authenticator.
+See the
+.Sx FIDO AUTHENTICATOR
+section for more information.
.It Fl k
Generate a KRL file.
In this mode,
@@ -457,7 +472,7 @@ Provides the new passphrase.
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
+See the
.Sx CERTIFICATES
section for details.
.It Fl O Ar option
@@ -475,55 +490,47 @@ listed in the
.Sx MODULI GENERATION
section may be specified.
.Pp
-When generating a key that will be hosted on a FIDO authenticator,
-this flag may be used to specify key-specific options.
-Those supported at present are:
+When generating FIDO authenticator-backed keys, the options listed in the
+.Sx FIDO AUTHENTICATOR
+section may be specified.
+.Pp
+When performing signature-related options using the
+.Fl Y
+flag, the following options are accepted:
.Bl -tag -width Ds
-.It Cm application
-Override the default FIDO application/origin string of
-.Dq ssh: .
-This may be useful when generating host or domain-specific resident keys.
-The specified application string must begin with
-.Dq ssh: .
-.It Cm challenge Ns = Ns Ar path
-Specifies a path to a challenge string that will be passed to the
-FIDO token during key generation.
-The challenge string may be used as part of an out-of-band
-protocol for key enrollment
-(a random challenge is used by default).
-.It Cm device
-Explicitly specify a
-.Xr fido 4
-device to use, rather than letting the token middleware select one.
-.It Cm no-touch-required
-Indicate that the generated private key should not require touch
-events (user presence) when making signatures.
-Note that
-.Xr sshd 8
-will refuse such signatures by default, unless overridden via
-an authorized_keys option.
-.It Cm resident
-Indicate that the key should be stored on the FIDO authenticator itself.
-Resident keys may be supported on FIDO2 tokens and typically require that
-a PIN be set on the token prior to generation.
-Resident keys may be loaded off the token using
-.Xr ssh-add 1 .
-.It Cm user
-A username to be associated with a resident key,
-overriding the empty default username.
-Specifying a username may be useful when generating multiple resident keys
-for the same application name.
-.It Cm verify-required
-Indicate that this private key should require user verification for
-each signature.
-Not all FIDO tokens support this option.
-Currently PIN authentication is the only supported verification method,
-but other methods may be supported in the future.
-.It Cm write-attestation Ns = Ns Ar path
-May be used at key generation time to record the attestation data
-returned from FIDO tokens during key generation.
-Please note that this information is potentially sensitive.
-By default, this information is discarded.
+.It Cm hashalg Ns = Ns Ar algorithm
+Selects the hash algorithm to use for hashing the message to be signed.
+Valid algorithms are
+.Dq sha256
+and
+.Dq sha512.
+The default is
+.Dq sha512.
+.It Cm print-pubkey
+Print the full public key to standard output after signature verification.
+.It Cm verify-time Ns = Ns Ar timestamp
+Specifies a time to use when validating signatures instead of the current
+time.
+The time may be specified as a date or time in the YYYYMMDD[Z] or
+in YYYYMMDDHHMM[SS][Z] formats.
+Dates and times will be interpreted in the current system time zone unless
+suffixed with a Z character, which causes them to be interpreted in the
+UTC time zone.
+.El
+.Pp
+When generating SSHFP DNS records from public keys using the
+.Fl r
+flag, the following options are accepted:
+.Bl -tag -width Ds
+.It Cm hashalg Ns = Ns Ar algorithm
+Selects a hash algorithm to use when printing SSHFP records using the
+.Fl D
+flag.
+Valid algorithms are
+.Dq sha1
+and
+.Dq sha256 .
+The default is to print both.
.El
.Pp
The
@@ -561,7 +568,7 @@ Print the SSHFP fingerprint resource record named
for the specified public key file.
.It Fl s Ar ca_key
Certify (sign) a public key using the specified CA key.
-Please see the
+See the
.Sx CERTIFICATES
section for details.
.Pp
@@ -594,7 +601,9 @@ and
(the default).
.It Fl U
When used in combination with
-.Fl s ,
+.Fl s
+or
+.Fl Y Cm sign ,
this option indicates that a CA key resides in a
.Xr ssh-agent 1 .
See the
@@ -612,31 +621,67 @@ 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
+The start time may be specified as:
+.Bl -bullet -compact
+.It
+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
+to indicate the certificate has no specified start time.
+.It
+A date or time in the system time zone formatted as YYYYMMDD or
+YYYYMMDDHHMM[SS].
+.It
+A date or time in the UTC time zone as YYYYMMDDZ or YYYYMMDDHHMM[SS]Z.
+.It
+A relative time before the current system time consisting of a minus sign
+followed by an interval in the format described in the
TIME FORMATS section of
.Xr sshd_config 5 .
+.It
+A raw seconds since epoch (Jan 1 1970 00:00:00 UTC) as a hexadecimal
+number beginning with
+.Dq 0x .
+.El
.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
+The end time may be specified similarly to the start time:
+.Bl -bullet -compact
+.It
+The string
.Dq forever
-to indicate that the certificate has no expiry date.
+to indicate the certificate has no specified end time.
+.It
+A date or time in the system time zone formatted as YYYYMMDD or
+YYYYMMDDHHMM[SS].
+.It
+A date or time in the UTC time zone as YYYYMMDDZ or YYYYMMDDHHMM[SS]Z.
+.It
+A relative time after the current system time consisting of a plus sign
+followed by an interval in the format described in the
+TIME FORMATS section of
+.Xr sshd_config 5 .
+.It
+A raw seconds since epoch (Jan 1 1970 00:00:00 UTC) as a hexadecimal
+number beginning with
+.Dq 0x .
+.El
.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).
+.Bl -tag -width Ds
+.It +52w1d
+Valid from now to 52 weeks and one day from now.
+.It -4w:+4w
+Valid from four weeks ago to four weeks from now.
+.It 20100101123000:20110101123000
+Valid from 12:30 PM, January 1st, 2010 to 12:30 PM, January 1st, 2011.
+.It 20100101123000Z:20110101123000Z
+Similar, but interpreted in the UTC time zone rather than the system time zone.
+.It -1d:20110101
+Valid from yesterday to midnight, January 1st, 2011.
+.It 0x1:0x2000000000
+Valid from roughly early 1970 to May 2033.
+.It -1m:forever
+Valid from one minute ago and never expiring.
+.El
.It Fl v
Verbose mode.
Causes
@@ -663,6 +708,14 @@ The format of the allowed signers file is documented in the
section below.
If one or more matching principals are found, they are returned on
standard output.
+.It Fl Y Cm match-principals
+Find principal matching the principal name provided using the
+.Fl I
+flag in the authorized signers file specified using the
+.Fl f
+flag.
+If one or more matching principals are found, they are returned on
+standard output.
.It Fl Y Cm check-novalidate
Checks that a signature generated using
.Nm
@@ -680,7 +733,7 @@ Successful testing of the signature is signalled by
.Nm
returning a zero exit status.
.It Fl Y Cm sign
-Cryptographically sign a file or some data using a SSH key.
+Cryptographically sign a file or some data using an SSH key.
When signing,
.Nm
accepts zero or more files to sign on the command-line - if no files
@@ -738,6 +791,13 @@ returning a zero exit status.
.It Fl y
This option will read a private
OpenSSH format file and print an OpenSSH public key to stdout.
+.It Fl Z Ar cipher
+Specifies the cipher to use for encryption when writing an OpenSSH-format
+private key file.
+The list of available ciphers may be obtained using
+.Qq ssh -Q cipher .
+The default is
+.Dq aes256-ctr .
.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.
@@ -805,8 +865,7 @@ Valid generator values are 2, 3, and 5.
.Pp
Screened DH groups may be installed in
.Pa /etc/ssh/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.
+It is important that this file contains moduli of a range of bit lengths.
.Pp
A number of options are available for moduli generation and screening via the
.Fl O
@@ -1003,7 +1062,7 @@ 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 are valid from
+By default, certificates are valid from the
.Ux
Epoch to the distant future.
.Pp
@@ -1012,7 +1071,77 @@ public key must be trusted by
.Xr sshd 8
or
.Xr ssh 1 .
-Please refer to those manual pages for details.
+Refer to those manual pages for details.
+.Sh FIDO AUTHENTICATOR
+.Nm
+is able to generate FIDO authenticator-backed keys, after which
+they may be used much like any other key type supported by OpenSSH, so
+long as the hardware authenticator is attached when the keys are used.
+FIDO authenticators generally require the user to explicitly authorise
+operations by touching or tapping them.
+FIDO keys consist of two parts: a key handle part stored in the
+private key file on disk, and a per-device private key that is unique
+to each FIDO authenticator and that cannot be exported from the
+authenticator hardware.
+These are combined by the hardware at authentication time to derive
+the real key that is used to sign authentication challenges.
+Supported key types are
+.Cm ecdsa-sk
+and
+.Cm ed25519-sk .
+.Pp
+The options that are valid for FIDO keys are:
+.Bl -tag -width Ds
+.It Cm application
+Override the default FIDO application/origin string of
+.Dq ssh: .
+This may be useful when generating host or domain-specific resident keys.
+The specified application string must begin with
+.Dq ssh: .
+.It Cm challenge Ns = Ns Ar path
+Specifies a path to a challenge string that will be passed to the
+FIDO authenticator during key generation.
+The challenge string may be used as part of an out-of-band
+protocol for key enrollment
+(a random challenge is used by default).
+.It Cm device
+Explicitly specify a
+.Xr fido 4
+device to use, rather than letting the authenticator middleware select one.
+.It Cm no-touch-required
+Indicate that the generated private key should not require touch
+events (user presence) when making signatures.
+Note that
+.Xr sshd 8
+will refuse such signatures by default, unless overridden via
+an authorized_keys option.
+.It Cm resident
+Indicate that the key handle should be stored on the FIDO
+authenticator itself.
+This makes it easier to use the authenticator on multiple computers.
+Resident keys may be supported on FIDO2 authenticators and typically
+require that a PIN be set on the authenticator prior to generation.
+Resident keys may be loaded off the authenticator using
+.Xr ssh-add 1 .
+Storing both parts of a key on a FIDO authenticator increases the likelihood
+of an attacker being able to use a stolen authenticator device.
+.It Cm user
+A username to be associated with a resident key,
+overriding the empty default username.
+Specifying a username may be useful when generating multiple resident keys
+for the same application name.
+.It Cm verify-required
+Indicate that this private key should require user verification for
+each signature.
+Not all FIDO authenticators support this option.
+Currently PIN authentication is the only supported verification method,
+but other methods may be supported in the future.
+.It Cm write-attestation Ns = Ns Ar path
+May be used at key generation time to record the attestation data
+returned from FIDO authenticators during key generation.
+This information is potentially sensitive.
+By default, this information is discarded.
+.El
.Sh KEY REVOCATION LISTS
.Nm
is able to manage OpenSSH format Key Revocation Lists (KRLs).
@@ -1107,7 +1236,7 @@ Empty lines and lines starting with a
.Ql #
are ignored as comments.
.Pp
-The principals field is a pattern-list (See PATTERNS in
+The principals field is a pattern-list (see PATTERNS in
.Xr ssh_config 5 )
consisting of one or more comma-separated USER@DOMAIN identity patterns
that are accepted for signing.
@@ -1124,11 +1253,19 @@ are case-insensitive):
.It Cm cert-authority
Indicates that this key is accepted as a certificate authority (CA) and
that certificates signed by this CA may be accepted for verification.
-.It Cm namespaces="namespace-list"
+.It Cm namespaces Ns = Ns "namespace-list"
Specifies a pattern-list of namespaces that are accepted for this key.
If this option is present, the signature namespace embedded in the
signature object and presented on the verification command-line must
match the specified list before the key will be considered acceptable.
+.It Cm valid-after Ns = Ns "timestamp"
+Indicates that the key is valid for use at or after the specified timestamp,
+which may be a date or time in the YYYYMMDD[Z] or YYYYMMDDHHMM[SS][Z] formats.
+Dates and times will be interpreted in the current system time zone unless
+suffixed with a Z character, which causes them to be interpreted in the UTC
+time zone.
+.It Cm valid-before Ns = Ns "timestamp"
+Indicates that the key is valid for use at or before the specified timestamp.
.El
.Pp
When verifying signatures made by certificates, the expected principal