From 1f7643e86e7dfdc559092fe4a467bad2ce86f6f2 Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Tue, 22 Dec 2020 08:37:03 +0100 Subject: [PATCH] apps/pkey.c: Re-order help output and option documentation Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/13712) --- apps/pkey.c | 35 +++++---- doc/man1/openssl-pkey.pod.in | 139 ++++++++++++++++++++--------------- 2 files changed, 100 insertions(+), 74 deletions(-) diff --git a/apps/pkey.c b/apps/pkey.c index c6308e2f0a3..50584f298c6 100644 --- a/apps/pkey.c +++ b/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)"}, - {"passin", OPT_PASSIN, 's', "Input file pass phrase source"}, + {"inform", OPT_INFORM, 'f', + "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"), + {"out", OPT_OUT, '>', "Output file"}, {"outform", OPT_OUTFORM, 'F', "Output format (DER or PEM)"}, + {"", OPT_CIPHER, '-', "Any supported cipher to be used for encryption"}, {"passout", OPT_PASSOUT, 's', "Output PEM file pass phrase source"}, - {"out", OPT_OUT, '>', "Output file"}, - {"pubout", OPT_PUBOUT, '-', "Output public key, not private"}, - {"text_pub", OPT_TEXT_PUB, '-', "Only output public key components"}, - {"text", OPT_TEXT, '-', "Output in plaintext as well"}, + {"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; diff --git a/doc/man1/openssl-pkey.pod.in b/doc/man1/openssl-pkey.pod.in index 2900fc24c7e..f48471bc40f 100644 --- a/doc/man1/openssl-pkey.pod.in +++ b/doc/man1/openssl-pkey.pod.in @@ -13,120 +13,147 @@ openssl-pkey - public or private key processing command B B [B<-help>] -[B<-inform> B|B|B|B] -[B<-outform> B|B] +{- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -} +[B<-check>] +[B<-pubcheck>] [B<-in> I|I] +[B<-inform> B|B|B|B] [B<-passin> I] +[B<-pubin>] [B<-out> I] +[B<-outform> B|B] +[B<-I>] [B<-passout> I] [B<-traditional>] -[B<-I>] -[B<-text>] -[B<-text_pub>] -[B<-noout>] -[B<-pubin>] [B<-pubout>] -[B<-check>] -[B<-pubcheck>] +[B<-noout>] +[B<-text_pub>] +[B<-text>] [B<-ec_conv_form> I] [B<-ec_param_enc> I] -{- $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. +{- $OpenSSL::safe::opt_engine_item -} + +{- $OpenSSL::safe::opt_provider_item -} + +=item B<-check> + +This option checks the consistency of a key pair for both public and private +components. + +=item B<-pubcheck> + +This option checks the correctness of either a public key +or the public component of a key pair. + +=back + +=head2 Input options + +=over 4 + +=item B<-in> I|I + +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|B|B|B The key input format; the default is B. The only value with effect is B; all others have become obsolete. See L for details. -=item B<-outform> B|B +=item B<-passin> I -The key output formats; the default is B. -See L for details. +The password source for the key input. -=item B<-in> I|I +For more information about the format of B +see L. -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<-pubin> -=item B<-passin> I, B<-passout> I +By default a private key is read from the input file: with this +option a public key is read instead. -The password source for the input and output file. -The -passout option is not supported for DER output. +=back -For more information about the format of B -see L. +=head2 Output options + +=over 4 =item B<-out> I -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 be the same as the input -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 be the same as the input filename. -=item B<-traditional> +=item B<-outform> B|B -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. +The key output format; the default is B. +See L for details. =item B<-I> These options encrypt the private key with the supplied cipher. Any algorithm -name accepted by EVP_get_cipherbyname() is acceptable such as B. +name accepted by EVP_get_cipherbyname() is acceptable such as B. -=item B<-text> - -Prints out the various public or private key components in -plain text in addition to the encoded version. +=item B<-passout> I -=item B<-text_pub> +The password source for the output file. +The -passout option is not supported for DER output. -Print out only public key components even if a private key is being processed. +For more information about the format of B +see L. -=item B<-noout> +=item B<-traditional> -Do not output the encoded version of the key. +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<-pubin> +=item B<-pubout> -By default a private key is read from the input file: with this -option a public key is read instead. +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<-pubout> +=item B<-noout> -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. +Do not output the encoded version of the key. -=item B<-check> +=item B<-text> -This option checks the consistency of a key pair for both public and private -components. +Output the various public or private key components in +plain text (possibly in addition to the encoded version). -=item B<-pubcheck> +=item B<-text_pub> -This option checks the correctness of either a public key or the public component -of a key pair. +Output in text form the public key components (also for private keys). =item B<-ec_conv_form> I -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 (the default @@ -148,10 +175,6 @@ EC parameters structures). The default value is B. B the B 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 -- 2.47.2