APPS/{x509,req}: Fix description and diagnostics of -key, -in, etc. options

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

2 files changed, 33 insertions, 15 deletions

diff --git a/doc/man1/openssl-req.pod.in b/doc/man1/openssl-req.pod.in
index e78b04c65b..a21c30ba47 100644
--- a/doc/man1/openssl-req.pod.in
+++ b/doc/man1/openssl-req.pod.in
@@ -79,9 +79,10 @@ The data is a PKCS#10 object.
 
 =item B<-in> I<filename>
 
-This specifies the input filename to read a request from or standard input
-if this option is not specified. A request is only read if the creation
-options (B<-new> or B<-newkey>) are not specified.
+This specifies the input filename to read a request from.
+This defaults to standard input unless B<-x509> or B<-CA> is specified.
+A request is only read if the creation options
+(B<-new> or B<-newkey> or B<-precert>) are not specified.
 
 =item B<-sigopt> I<nm>:I<v>
 
@@ -156,8 +157,13 @@ else by default an RSA key with 2048 bits length.
 
 =item B<-newkey> I<arg>
 
-This option creates a new certificate request and a new private
-key. The argument takes one of several forms.
+This option is used to generate a new private key unless B<-key> is given.
+It is subsequently used as if it was given using the B<-key> option.
+
+This option implies the B<-new> flag to create a new certificate request
+or a new certificate in case B<-x509> is given.
+
+The argument takes one of several forms.
 
 [B<rsa:>]I<nbits> generates an RSA key I<nbits> in size.
 If I<nbits> is omitted, i.e., B<-newkey> B<rsa> is specified,
@@ -193,9 +199,14 @@ See L<openssl-genpkey(1)/KEY GENERATION OPTIONS> for more details.
 
 =item B<-key> I<filename>|I<uri>
 
-This specifies the key to include and to use for request self-signature
-and for self-signing certificates produced with the B<-x509> option.
-It also accepts PKCS#8 format private keys for PEM format files.
+This option provides the private key for signing a new certificate or
+certificate request.
+Unless B<-in> is given, the corresponding public key is placed in
+the new certificate or certificate request, resulting in a self-signature.
+
+For certificate signing this option is overridden by the B<-CA> option.
+
+This option also accepts PKCS#8 format private keys for PEM format files.
 
 =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
@@ -268,6 +279,8 @@ This option outputs a certificate instead of a certificate request.
 This is typically used to generate test certificates.
 It is implied by the B<-CA> option.
 
+This option implies the B<-new> flag if B<-in> is not given.
+
 If an existing request is specified with the B<-in> option, it is converted
 to the a certificate; otherwise a request is created from scratch.
 
diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in
index 9c77a216c2..a20f605e03 100644
--- a/doc/man1/openssl-x509.pod.in
+++ b/doc/man1/openssl-x509.pod.in
@@ -102,9 +102,11 @@ Print out a usage message.
 
 =item B<-in> I<filename>|I<uri>
 
-If the B<-req> option is not used this specifies the input
-to read a certificate from or standard input if this option is not specified.
-With the B<-req> option this specifies a certificate request file.
+This specifies the input to read a certificate from
+or the input file for reading a certificate request if the B<-req> flag is used.
+In both cases this defaults to standard input.
+
+This option cannot be combined with the B<-new> flag.
 
 =item B<-passin> I<arg>
 
@@ -163,9 +165,12 @@ Names and values of these options are algorithm-specific.
 
 =item B<-key> I<filename>|I<uri>
 
-This option causes the new certificate or certificate request
-to be self-signed using the supplied private key.
-This cannot be used in conjunction with the B<-CA> option.
+This option provides the private key for signing a new certificate or
+certificate request.
+Unless B<-force_pubkey> is given, the corresponding public key is placed in
+the new certificate or certificate request, resulting in a self-signature.
+
+This option cannot be used in conjunction with the B<-CA> option.
 
 It sets the issuer name to the subject name (i.e., makes it self-issued)
 and changes the public key to the supplied value (unless overridden
@@ -466,7 +471,7 @@ certificate, which is then signed using the "CA" key given as detailed below.
 
 This option cannot be used in conjunction with the B<-key> option.
 This option is normally combined with the B<-req> option referencing a CSR.
-Without the B<-req> option the input must be a self-signed certificate
+Without the B<-req> option the input must be an existing certificate
 unless the B<-new> option is given, which generates a certificate from scratch.
 
 =item B<-CAform> B<DER>|B<PEM>|B<P12>,