upstream: remove single-letter flags for moduli options

Move all moduli generation options to live under the -O flag.

Frees up seven single-letter flags.

NB. this change break existing ssh-keygen commandline syntax for moduli-
related operations. Very few people use these fortunately.

feedback and ok markus@

OpenBSD-Commit-ID: d498f3eaf28128484826a4fcb343612764927935

1 files changed, 78 insertions, 64 deletions

diff --git a/ssh-keygen.1 b/ssh-keygen.1
index 67a57b9f7..9afb92943 100644
--- a/ssh-keygen.1
+++ b/ssh-keygen.1
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ssh-keygen.1,v 1.183 2019/12/30 03:28:41 djm Exp $
+.\"     $OpenBSD: ssh-keygen.1,v 1.184 2019/12/30 03:30:09 djm Exp $
 .\"
 .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
 .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
@@ -99,20 +99,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
 .Nm ssh-keygen
+.Fl M Cm screen
 .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
+.Op Fl O Ar option
+.Ar
 .Nm ssh-keygen
 .Fl I Ar certificate_identity
 .Fl s Ar ca_key
@@ -268,11 +262,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
@@ -333,12 +322,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
@@ -379,24 +362,6 @@ 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,
@@ -419,9 +384,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
@@ -457,10 +439,20 @@ Please see the
 .Sx CERTIFICATES
 section for details.
 .It Fl O Ar option
-Specify a certificate option when signing a key.
-See the
+Specify a key/value option.
+These are specific to the operation that
+.Nm
+has been requested to perform.
+.Pp
+When signing certificates, one of the options listed in the
 .Sx CERTIFICATES
-section for a list of available certificate options.
+section may be specified here.
+.Pp
+When performing moduli generation or screening, one of the options
+listed in the
+.Sx MODULI GENERATION
+section may be specified.
+.Pp
 This option may be specified multiple times.
 .It Fl P Ar passphrase
 Provides the (old) passphrase.
@@ -489,8 +481,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
@@ -504,10 +494,6 @@ 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 | ecdsa-sk | ed25519 | ed25519-sk | rsa
 Specifies the type of key to create.
 The possible values are
@@ -583,8 +569,6 @@ 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 w Ar provider
 Specifies a path to a library that will be used when creating
 FIDO authenticator-hosted keys, overriding the default of using
@@ -701,25 +685,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
@@ -728,16 +712,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
@@ -745,6 +729,36 @@ 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 -compact
+.Pp
+.It Ic lines Ns = Ns Ar number
+Exit after screening the specified number of lines while performing DH
+candidate screening.
+.Pp
+.It Ic start-line Ns = Ns Ar line-number
+Start screening at the specified line number while performing DH candidate
+screening.
+.Pp
+.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.
+.Pp
+.It Ic memory Ns = Ns Ar mbytes
+Specify the amount of memory to use (in megabytes) when generating
+candidate moduli for DH-GEX.
+.Pp
+.It Ic start Ns = Ns Ar hex-value
+Specify start point (in hex) when generating candidate moduli for DH-GEX.
+.Pp
+.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