apps/pkey.c: Re-order help output and option documentation

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13712)

apps/pkey.c

@@ -36,7 +36,7 @@ typedef enum OPTION_choice {
     OPT_ERR = -1, OPT_EOF = 0, OPT_HELP,
     OPT_INFORM, OPT_OUTFORM, OPT_PASSIN, OPT_PASSOUT, OPT_ENGINE,
     OPT_IN, OPT_OUT, OPT_PUBIN, OPT_PUBOUT, OPT_TEXT_PUB,
-    OPT_TEXT, OPT_NOOUT, OPT_MD, OPT_TRADITIONAL, OPT_CHECK, OPT_PUB_CHECK,
+    OPT_TEXT, OPT_NOOUT, OPT_CIPHER, OPT_TRADITIONAL, OPT_CHECK, OPT_PUB_CHECK,
     OPT_EC_PARAM_ENC, OPT_EC_CONV_FORM,
     OPT_PROV_ENUM
 } OPTION_CHOICE;
@@ -47,33 +47,36 @@ const OPTIONS pkey_options[] = {
 #ifndef OPENSSL_NO_ENGINE
     {"engine", OPT_ENGINE, 's', "Use engine, possibly a hardware device"},
 #endif
+    OPT_PROV_OPTIONS,
+
     {"check", OPT_CHECK, '-', "Check key consistency"},
     {"pubcheck", OPT_PUB_CHECK, '-', "Check public key consistency"},
-    {"", OPT_MD, '-', "Any supported cipher"},
-    {"ec_param_enc", OPT_EC_PARAM_ENC, 's',
-     "Specifies the way the ec parameters are encoded"},
-    {"ec_conv_form", OPT_EC_CONV_FORM, 's',
-     "Specifies the point conversion form "},
 
     OPT_SECTION("Input"),
     {"in", OPT_IN, 's', "Input key"},
-    {"inform", OPT_INFORM, 'f', "Input format (DER/PEM/P12/ENGINE)"},
+    {"inform", OPT_INFORM, 'f',
-    {"passin", OPT_PASSIN, 's', "Input file pass phrase source"},
+     "Key input format (ENGINE, other values ignored)"},
+    {"passin", OPT_PASSIN, 's', "Key input pass phrase source"},
     {"pubin", OPT_PUBIN, '-',
      "Read public key from input (default is private key)"},
-    {"traditional", OPT_TRADITIONAL, '-',
-     "Use traditional format for private keys"},
 
     OPT_SECTION("Output"),
-    {"outform", OPT_OUTFORM, 'F', "Output format (DER or PEM)"},
-    {"passout", OPT_PASSOUT, 's', "Output PEM file pass phrase source"},
     {"out", OPT_OUT, '>', "Output file"},
-    {"pubout", OPT_PUBOUT, '-', "Output public key, not private"},
+    {"outform", OPT_OUTFORM, 'F', "Output format (DER or PEM)"},
-    {"text_pub", OPT_TEXT_PUB, '-', "Only output public key components"},
+    {"", OPT_CIPHER, '-', "Any supported cipher to be used for encryption"},
-    {"text", OPT_TEXT, '-', "Output in plaintext as well"},
+    {"passout", OPT_PASSOUT, 's', "Output PEM file pass phrase source"},
+    {"traditional", OPT_TRADITIONAL, '-',
+     "Use traditional format for private key PEM output"},
+    {"pubout", OPT_PUBOUT, '-', "Output public key components only"},
     {"noout", OPT_NOOUT, '-', "Don't output the key"},
+    {"text_pub", OPT_TEXT_PUB, '-',
+     "Output public key components in text form"},
+    {"text", OPT_TEXT, '-', "Output private components in plaintext as well"},
+    {"ec_conv_form", OPT_EC_CONV_FORM, 's',
+     "Specifies the point conversion form "},
+    {"ec_param_enc", OPT_EC_PARAM_ENC, 's',
+     "Specifies the way the ec parameters are encoded"},
 
-    OPT_PROV_OPTIONS,
     {NULL}
 };
 
@@ -156,7 +159,7 @@ int pkey_main(int argc, char **argv)
         case OPT_PUB_CHECK:
             pub_check = 1;
             break;
-        case OPT_MD:
+        case OPT_CIPHER:
             if (!opt_cipher(opt_unknown(), &cipher))
                 goto opthelp;
             break;

doc/man1/openssl-pkey.pod.in

@@ -13,106 +13,45 @@ openssl-pkey - public or private key processing command
 
 B<openssl> B<pkey>
 [B<-help>]
-[B<-inform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
+{- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
-[B<-outform> B<DER>|B<PEM>]
-[B<-in> I<filename>|I<uri>]
-[B<-passin> I<arg>]
-[B<-out> I<filename>]
-[B<-passout> I<arg>]
-[B<-traditional>]
-[B<-I<cipher>>]
-[B<-text>]
-[B<-text_pub>]
-[B<-noout>]
-[B<-pubin>]
-[B<-pubout>]
 [B<-check>]
 [B<-pubcheck>]
+[B<-in> I<filename>|I<uri>]
+[B<-inform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
+[B<-passin> I<arg>]
+[B<-pubin>]
+[B<-out> I<filename>]
+[B<-outform> B<DER>|B<PEM>]
+[B<-I<cipher>>]
+[B<-passout> I<arg>]
+[B<-traditional>]
+[B<-pubout>]
+[B<-noout>]
+[B<-text_pub>]
+[B<-text>]
 [B<-ec_conv_form> I<arg>]
 [B<-ec_param_enc> I<arg>]
-{- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
 
 =for openssl ifdef engine
 
 =head1 DESCRIPTION
 
 This command processes public or private keys. They can be
-converted between various forms and their components printed out.
+converted between various forms and their components printed.
 
 =head1 OPTIONS
 
+=head2 General options
+
 =over 4
 
 =item B<-help>
 
 Print out a usage message.
 
-=item B<-inform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
+{- $OpenSSL::safe::opt_engine_item -}
 
-The key input format; the default is B<PEM>.
+{- $OpenSSL::safe::opt_provider_item -}
-The only value with effect is B<ENGINE>; all others have become obsolete.
-See L<openssl-format-options(1)> for details.
-
-=item B<-outform> B<DER>|B<PEM>
-
-The key output formats; the default is B<PEM>.
-See L<openssl-format-options(1)> for details.
-
-=item B<-in> I<filename>|I<uri>
-
-This specifies the input to read a key from or standard input if this
-option is not specified. If the key is encrypted a pass phrase will be
-prompted for.
-
-=item B<-passin> I<arg>, B<-passout> I<arg>
-
-The password source for the input and output file.
-The -passout option is not supported for DER output.
-
-For more information about the format of B<arg>
-see L<openssl-passphrase-options(1)>.
-
-=item B<-out> I<filename>
-
-This specifies the output filename to write a key to or standard output if this
-option is not specified. If any encryption options are set then a pass phrase
-will be prompted for. The output filename should B<not> be the same as the input
-filename.
-
-=item B<-traditional>
-
-Normally a private key is written using standard format: this is PKCS#8 form
-with the appropriate encryption algorithm (if any). If the B<-traditional>
-option is specified then the older "traditional" format is used instead.
-
-=item B<-I<cipher>>
-
-These options encrypt the private key with the supplied cipher. Any algorithm
-name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
-
-=item B<-text>
-
-Prints out the various public or private key components in
-plain text in addition to the encoded version.
-
-=item B<-text_pub>
-
-Print out only public key components even if a private key is being processed.
-
-=item B<-noout>
-
-Do not output the encoded version of the key.
-
-=item B<-pubin>
-
-By default a private key is read from the input file: with this
-option a public key is read instead.
-
-=item B<-pubout>
-
-By default a private key is output: with this option a public
-key will be output instead. This option is automatically set if
-the input is a public key.
 
 =item B<-check>
 
@@ -121,12 +60,100 @@ components.
 
 =item B<-pubcheck>
 
-This option checks the correctness of either a public key or the public component
+This option checks the correctness of either a public key
-of a key pair.
+or the public component of a key pair.
+
+=back
+
+=head2 Input options
+
+=over 4
+
+=item B<-in> I<filename>|I<uri>
+
+This specifies the input to read a key from
+or standard input if this option is not specified.
+If the key is encrypted and B<-passin> is not given
+a pass phrase will be prompted for.
+
+=item B<-inform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
+
+The key input format; the default is B<PEM>.
+The only value with effect is B<ENGINE>; all others have become obsolete.
+See L<openssl-format-options(1)> for details.
+
+=item B<-passin> I<arg>
+
+The password source for the key input.
+
+For more information about the format of B<arg>
+see L<openssl-passphrase-options(1)>.
+
+=item B<-pubin>
+
+By default a private key is read from the input file: with this
+option a public key is read instead.
+
+=back
+
+=head2 Output options
+
+=over 4
+
+=item B<-out> I<filename>
+
+This specifies the output filename to write a key to
+or standard output if this option is not specified.
+If any encryption option is set but no B<-passout> is given
+then a pass phrase will be prompted for.
+The output filename should B<not> be the same as the input filename.
+
+=item B<-outform> B<DER>|B<PEM>
+
+The key output format; the default is B<PEM>.
+See L<openssl-format-options(1)> for details.
+
+=item B<-I<cipher>>
+
+These options encrypt the private key with the supplied cipher. Any algorithm
+name accepted by EVP_get_cipherbyname() is acceptable such as B<aes128>.
+
+=item B<-passout> I<arg>
+
+The password source for the output file.
+The -passout option is not supported for DER output.
+
+For more information about the format of B<arg>
+see L<openssl-passphrase-options(1)>.
+
+=item B<-traditional>
+
+Normally a private key is written using standard format: this is PKCS#8 form
+with the appropriate encryption algorithm (if any). If the B<-traditional>
+option is specified then the older "traditional" format is used instead.
+
+=item B<-pubout>
+
+By default the encoded private key is output:
+with this option the encoded public key will be output instead.
+This option is automatically set if the input is a public key.
+
+=item B<-noout>
+
+Do not output the encoded version of the key.
+
+=item B<-text>
+
+Output the various public or private key components in
+plain text (possibly in addition to the encoded version).
+
+=item B<-text_pub>
+
+Output in text form the public key components (also for private keys).
 
 =item B<-ec_conv_form> I<arg>
 
-This option only applies to elliptic curve based public and private keys.
+This option only applies to elliptic-curve based keys.
 
 This specifies how the points on the elliptic curve are converted
 into octet strings. Possible values are: B<compressed> (the default
@@ -148,10 +175,6 @@ EC parameters structures). The default value is B<named_curve>.
 B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279,
 is currently not implemented in OpenSSL.
 
-{- $OpenSSL::safe::opt_engine_item -}
-
-{- $OpenSSL::safe::opt_provider_item -}
-
 =back
 
 =head1 EXAMPLES