1 files changed, 278 insertions, 173 deletions

diff --git a/ssh-keygen.1 b/ssh-keygen.1
index 957d2f0f0..7af564297 100644
--- a/ssh-keygen.1
+++ b/ssh-keygen.1
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ssh-keygen.1,v 1.171 2019/10/03 17:07:50 jmc Exp $
+.\"     $OpenBSD: ssh-keygen.1,v 1.201 2020/02/07 03:57:31 djm Exp $
 .\"
 .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
 .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
@@ -35,12 +35,12 @@
 .\" (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 3 2019 $
+.Dd $Mdocdate: February 7 2020 $
 .Dt SSH-KEYGEN 1
 .Os
 .Sh NAME
 .Nm ssh-keygen
-.Nd authentication key generation, management and conversion
+.Nd OpenSSH authentication key utility
 .Sh SYNOPSIS
 .Nm ssh-keygen
 .Op Fl q
@@ -48,8 +48,10 @@
 .Op Fl C Ar comment
 .Op Fl f Ar output_keyfile
 .Op Fl m Ar format
+.Op Fl t Cm dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa
 .Op Fl N Ar new_passphrase
-.Op Fl t Cm dsa | ecdsa | ed25519 | rsa
+.Op Fl O Ar option
+.Op Fl w Ar provider
 .Nm ssh-keygen
 .Fl p
 .Op Fl f Ar keyfile
@@ -90,6 +92,9 @@
 .Fl H
 .Op Fl f Ar known_hosts_file
 .Nm ssh-keygen
+.Fl K
+.Op Fl w Ar provider
+.Nm ssh-keygen
 .Fl R Ar hostname
 .Op Fl f Ar known_hosts_file
 .Nm ssh-keygen
@@ -97,20 +102,14 @@
 .Op Fl g
 .Op Fl f Ar input_keyfile
 .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
+.Fl M Cm generate
+.Op Fl O Ar option
+.Ar output_file
 .Nm ssh-keygen
-.Fl f Ar input_file
-.Fl T Ar output_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
+.Fl M Cm screen
+.Op Fl f Ar input_file
+.Op Fl O Ar option
+.Ar output_file
 .Nm ssh-keygen
 .Fl I Ar certificate_identity
 .Fl s Ar ca_key
@@ -139,6 +138,10 @@
 .Fl f Ar krl_file
 .Ar
 .Nm ssh-keygen
+.Fl Y Cm find-principals
+.Fl s Ar signature_file
+.Fl f Ar allowed_signers_file
+.Nm ssh-keygen
 .Fl Y Cm check-novalidate
 .Fl n Ar namespace
 .Fl s Ar signature_file
@@ -188,7 +191,9 @@ 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
+.Pa ~/.ssh/id_ecdsa_sk ,
+.Pa ~/.ssh/id_ed25519 ,
+.Pa ~/.ssh/id_ed25519_sk
 or
 .Pa ~/.ssh/id_rsa .
 Additionally, the system administrator may use this to generate host keys,
@@ -264,11 +269,6 @@ 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
@@ -282,7 +282,7 @@ 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
+ECDSA-SK, Ed25519 and Ed25519-SK keys have a fixed length and the
 .Fl b
 flag will be ignored.
 .It Fl C Ar comment
@@ -329,12 +329,6 @@ used in conjunction with the
 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
@@ -375,24 +369,10 @@ 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
+Download resident keys from a FIDO authenticator.
+Public and private key files will be written to the current directory for
+each downloaded key.
 .It Fl k
 Generate a KRL file.
 In this mode,
@@ -415,9 +395,26 @@ 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 Cm generate
+Generate candidate Diffie-Hellman Group Exchange (DH-GEX) parameters for
+eventual use by the
+.Sq diffie-hellman-group-exchange-*
+key exchange methods.
+The numbers generated by this operation must be further screened before
+use.
+See the
+.Sx MODULI GENERATION
+section for more information.
+.It Fl M Cm screen
+Screen candidate parameters for Diffie-Hellman Group Exchange.
+This will accept a list of candidate numbers and test that they are
+safe (Sophie Germain) primes with acceptable group generators.
+The results of this operation may be added to the
+.Pa /etc/moduli
+file.
+See the
+.Sx MODULI GENERATION
+section for more information.
 .It Fl m Ar key_format
 Specify a key format for key generation, the
 .Fl i
@@ -453,90 +450,67 @@ 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).
+Specify a key/value option.
+These are specific to the operation that
+.Nm
+has been requested to perform.
 .Pp
-.It Ic no-port-forwarding
-Disable port forwarding (permitted by default).
+When signing certificates, one of the options listed in the
+.Sx CERTIFICATES
+section may be specified here.
 .Pp
-.It Ic no-pty
-Disable PTY allocation (permitted by default).
+When performing moduli generation or screening, one of the options
+listed in the
+.Sx MODULI GENERATION
+section may be specified.
 .Pp
-.It Ic no-user-rc
-Disable execution of
-.Pa ~/.ssh/rc
-by
+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:
+.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
-(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.
+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 write-attestation Ns = Ns Ar path
+May be used at key generation time to record the attestation certificate
+returned from FIDO tokens during key generation.
+By default this information is discarded.
+.El
 .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
+.Fl O
+option may be specified multiple times.
 .It Fl P Ar passphrase
 Provides the (old) passphrase.
 .It Fl p
@@ -564,8 +538,6 @@ option above).
 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
@@ -579,16 +551,14 @@ 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
+.It Fl t Cm dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa
 Specifies the type of key to create.
 The possible values are
 .Dq dsa ,
 .Dq ecdsa ,
+.Dq ecdsa-sk ,
 .Dq ed25519 ,
+.Dq ed25519-sk ,
 or
 .Dq rsa .
 .Pp
@@ -656,11 +626,38 @@ 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 w Ar provider
+Specifies a path to a library that will be used when creating
+FIDO authenticator-hosted keys, overriding the default of using
+the internal USB HID support.
+.It Fl Y Cm find-principals
+Find the principal(s) associated with the public key of a signature,
+provided using the
+.Fl s
+flag in an authorized signers file provided using the
+.Fl f
+flag.
+The format of the allowed signers file is documented in the
+.Sx ALLOWED SIGNERS
+section below.
+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
+.Fl Y Cm sign
+has a valid structure.
+This does not validate if a signature comes from an authorized signer.
+When testing a signature,
+.Nm
+accepts a message on standard input and a signature namespace using
+.Fl n .
+A file containing the corresponding signature must also be supplied using the
+.Fl s
+flag.
+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.
 When signing,
@@ -716,22 +713,10 @@ flag.
 The revocation file may be a KRL or a one-per-line list of public keys.
 Successful verification by an authorized signer is signalled by
 .Nm
-.It Fl Y Cm check-novalidate
-Checks that a signature generated using
-.Nm
-.Fl Y Cm sign
-has a valid structure.
-This does not validate if a signature comes from an authorized signer.
-When testing a signature,
-.Nm
-accepts a message on standard input and a signature namespace using
-.Fl n .
-A file containing the corresponding signature must also be supplied using the
-.Fl s
-flag.
-Successful testing of the signature is signalled by
-.Nm
 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 serial_number
 Specifies a serial number to be embedded in the certificate to distinguish
 this certificate from others from the same CA.
@@ -757,25 +742,25 @@ These candidate primes are then tested for suitability (a CPU-intensive
 process).
 .Pp
 Generation of primes is performed using the
-.Fl G
+.Fl M Cm generate
 option.
 The desired length of the primes may be specified by the
-.Fl b
+.Fl O Cm bits
 option.
 For example:
 .Pp
-.Dl # ssh-keygen -G moduli-2048.candidates -b 2048
+.Dl # ssh-keygen -M generate -O bits=2048 moduli-2048.candidates
 .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
+.Fl O Cm start
 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
+.Fl M Cm screen
 option.
 In this mode
 .Nm
@@ -784,16 +769,16 @@ will read candidates from standard input (or a file specified using the
 option).
 For example:
 .Pp
-.Dl # ssh-keygen -T moduli-2048 -f moduli-2048.candidates
+.Dl # ssh-keygen -M screen -f moduli-2048.candidates moduli-2048
 .Pp
 By default, each candidate will be subjected to 100 primality tests.
 This may be overridden using the
-.Fl a
+.Fl O Cm prime-tests
 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
+.Fl O Cm generator
 option.
 Valid generator values are 2, 3, and 5.
 .Pp
@@ -801,6 +786,30 @@ 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.
+.Pp
+A number of options are available for moduli generation and screening via the
+.Fl O
+flag:
+.Bl -tag -width Ds
+.It Ic lines Ns = Ns Ar number
+Exit after screening the specified number of lines while performing DH
+candidate screening.
+.It Ic start-line Ns = Ns Ar line-number
+Start screening at the specified line number while performing DH candidate
+screening.
+.It Ic checkpoint Ns = Ns Ar filename
+Write the last line processed to the specified file while performing DH
+candidate screening.
+This will be used to skip lines in the input file that have already been
+processed if the job is restarted.
+.It Ic memory Ns = Ns Ar mbytes
+Specify the amount of memory to use (in megabytes) when generating
+candidate moduli for DH-GEX.
+.It Ic start Ns = Ns Ar hex-value
+Specify start point (in hex) when generating candidate moduli for DH-GEX.
+.It Ic generator Ns = Ns Ar value
+Specify desired generator (in decimal) when testing candidate moduli for DH-GEX.
+.El
 .Sh CERTIFICATES
 .Nm
 supports signing of keys to produce certificates that may be used for
@@ -868,9 +877,94 @@ 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
+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 no-touch-required
+Do not require signatures made using this key require demonstration
+of user presence (e.g. by having the user touch the authenticator).
+This option only makes sense for the FIDO authenticator algorithms
+.Cm ecdsa-sk
+and
+.Cm ed25519-sk .
+.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
+.Pp
+At present, no standard options are valid for host keys.
 .Pp
 Finally, certificates may be defined with a validity lifetime.
 The
@@ -987,8 +1081,8 @@ The principals field is a pattern-list (See PATTERNS in
 consisting of one or more comma-separated USER@DOMAIN identity patterns
 that are accepted for signing.
 When verifying, the identity presented via the
-.Fl I option
-must match a principals pattern in order for the corresponding key to be
+.Fl I
+option must match a principals pattern in order for the corresponding key to be
 considered acceptable for verification.
 .Pp
 The options (if present) consist of comma-separated option specifications.
@@ -1019,14 +1113,23 @@ user1@example.com,user2@example.com ssh-rsa AAAAX1...
 # A key that is accepted only for file signing.
 user2@example.com namespaces="file" ssh-ed25519 AAA41...
 .Ed
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev SSH_SK_PROVIDER
+Specifies a path to a library that will be used when loading any
+FIDO authenticator-hosted keys, overriding the default of using
+the built-in USB HID support.
+.El
 .Sh FILES
 .Bl -tag -width Ds -compact
 .It Pa ~/.ssh/id_dsa
 .It Pa ~/.ssh/id_ecdsa
+.It Pa ~/.ssh/id_ecdsa_sk
 .It Pa ~/.ssh/id_ed25519
+.It Pa ~/.ssh/id_ed25519_sk
 .It Pa ~/.ssh/id_rsa
-Contains the DSA, ECDSA, Ed25519 or RSA
-authentication identity of the user.
+Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519,
+authenticator-hosted 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
@@ -1039,10 +1142,12 @@ 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_ecdsa_sk.pub
 .It Pa ~/.ssh/id_ed25519.pub
+.It Pa ~/.ssh/id_ed25519_sk.pub
 .It Pa ~/.ssh/id_rsa.pub
-Contains the DSA, ECDSA, Ed25519 or RSA
-public key for authentication.
+Contains the DSA, ECDSA, authenticator-hosted ECDSA, Ed25519,
+authenticator-hosted Ed25519 or RSA public key for authentication.
 The contents of this file should be added to
 .Pa ~/.ssh/authorized_keys
 on all machines