APPS: generated certs bear X.509 V3, unless -x509v1 option of req app is given

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Hugo Landau <hlandau@openssl.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/19271)

6 files changed, 60 insertions, 11 deletions

diff --git a/doc/man1/openssl-ca.pod.in b/doc/man1/openssl-ca.pod.in
index 955bac8fd3..3474e12c79 100644
--- a/doc/man1/openssl-ca.pod.in
+++ b/doc/man1/openssl-ca.pod.in
@@ -71,6 +71,11 @@ B<openssl> B<ca>
 
 This command emulates a CA application.
 See the B<WARNINGS> especially when considering to use it productively.
+
+It generates certificates bearing X.509 version 3.
+Unless specified otherwise,
+key identifier extensions are included as described in L<x509v3_config(5)>.
+
 It can be used to sign certificate requests (CSRs) in a variety of forms
 and generate certificate revocation lists (CRLs).
 It also maintains a text database of issued certificates and their status.
@@ -287,8 +292,7 @@ and all certificates will be certified automatically.
 The section of the configuration file containing certificate extensions
 to be added when a certificate is issued (defaults to B<x509_extensions>
 unless the B<-extfile> option is used).
-If no X.509 extensions are specified then a V1 certificate is created,
-else a V3 certificate is created.
+
 See the L<x509v3_config(5)> manual page for details of the
 extension section format.
 
@@ -833,6 +837,9 @@ has no effect.
 
 The B<-engine> option was deprecated in OpenSSL 3.0.
 
+Since OpenSSL 3.2, generated certificates bear X.509 version 3,
+and key identifier extensions are included by default.
+
 =head1 SEE ALSO
 
 L<openssl(1)>,
diff --git a/doc/man1/openssl-req.pod.in b/doc/man1/openssl-req.pod.in
index b677160f6b..099582fa72 100644
--- a/doc/man1/openssl-req.pod.in
+++ b/doc/man1/openssl-req.pod.in
@@ -33,6 +33,7 @@ B<openssl> B<req>
 [B<-config> I<filename>]
 [B<-section> I<name>]
 [B<-x509>]
+[B<-x509v1>]
 [B<-CA> I<filename>|I<uri>]
 [B<-CAkey> I<filename>|I<uri>]
 [B<-days> I<n>]
@@ -299,6 +300,16 @@ X.509 extensions to be added can be specified in the configuration file,
 possibly using the B<-config> and B<-extensions> options,
 and/or using the B<-addext> option.
 
+Unless B<-x509v1> is given, generated certificates bear X.509 version 3.
+Unless specified otherwise,
+key identifier extensions are included as described in L<x509v3_config(5)>.
+
+=item B<-x509v1>
+
+Request generation of certificates with X.509 version 1.
+This implies B<-x509>.
+If X.509 extensions are given, anyway X.509 version 3 is set.
+
 =item B<-CA> I<filename>|I<uri>
 
 Specifies the "CA" certificate to be used for signing a new certificate
@@ -349,7 +360,7 @@ file to specify requests for a variety of purposes.
 
 Add a specific extension to the certificate (if B<-x509> is in use)
 or certificate request.  The argument must have the form of
-a key=value pair as it would appear in a config file.
+a C<key=value> pair as it would appear in a config file.
 
 This option can be given multiple times.
 
@@ -770,6 +781,10 @@ The <-nodes> option was deprecated in OpenSSL 3.0, too; use B<-noenc> instead.
 
 The B<-reqexts> option has been made an alias of B<-extensions> in OpenSSL 3.2.
 
+Since OpenSSL 3.2,
+generated certificates bear X.509 version 3 unless B<-x509v1> is given,
+and key identifier extensions are included by default.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in
index ad9659c565..84110d24f5 100644
--- a/doc/man1/openssl-x509.pod.in
+++ b/doc/man1/openssl-x509.pod.in
@@ -87,6 +87,10 @@ convert certificates to various forms, edit certificate trust settings,
 generate certificates from scratch or from certificating requests
 and then self-signing them or signing them like a "micro CA".
 
+Generated certificates bear X.509 version 3.
+Unless specified otherwise,
+key identifier extensions are included as described in L<x509v3_config(5)>.
+
 Since there are a large number of options they will split up into
 various sections.
 
@@ -303,7 +307,7 @@ as used by OpenSSL before version 1.0.0.
 Prints out the certificate extensions in text form.
 Can also be used to restrict which extensions to copy.
 Extensions are specified
-with a comma separated string, e.g., "subjectAltName,subjectKeyIdentifier".
+with a comma separated string, e.g., "subjectAltName, subjectKeyIdentifier".
 See the L<x509v3_config(5)> manual page for the extension names.
 
 =item B<-ocspid>
@@ -435,9 +439,13 @@ If this option is not
 specified then the extensions should either be contained in the unnamed
 (default) section or the default section should contain a variable called
 "extensions" which contains the section to use.
+
 See the L<x509v3_config(5)> manual page for details of the
 extension section format.
 
+Unless specified otherwise,
+key identifier extensions are included as described in L<x509v3_config(5)>.
+
 =item B<-sigopt> I<nm>:I<v>
 
 Pass options to the signature algorithm during sign operations.
@@ -782,6 +790,9 @@ The B<-engine> option was deprecated in OpenSSL 3.0.
 
 The B<-C> option was removed in OpenSSL 3.0.
 
+Since OpenSSL 3.2, generated certificates bear X.509 version 3,
+and key identifier extensions are included by default.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/X509_get_version.pod b/doc/man3/X509_get_version.pod
index 082859e4f4..5d377c91d3 100644
--- a/doc/man3/X509_get_version.pod
+++ b/doc/man3/X509_get_version.pod
@@ -22,13 +22,13 @@ certificate request or CRL version
 =head1 DESCRIPTION
 
 X509_get_version() returns the numerical value of the version field of
-certificate B<x>. These correspond to the constants B<X509_VERSION_1>,
+certificate I<x>. These correspond to the constants B<X509_VERSION_1>,
 B<X509_VERSION_2>, and B<X509_VERSION_3>. Note: the values of these constants
 are defined by standards (X.509 et al) to be one less than the certificate
 version. So B<X509_VERSION_3> has value 2 and B<X509_VERSION_1> has value 0.
 
 X509_set_version() sets the numerical value of the version field of certificate
-B<x> to B<version>.
+I<x> to I<version>.
 
 Similarly X509_REQ_get_version(), X509_REQ_set_version(),
 X509_CRL_get_version() and X509_CRL_set_version() get and set the version
diff --git a/doc/man3/X509_sign.pod b/doc/man3/X509_sign.pod
index df66e3e5b7..af21148f67 100644
--- a/doc/man3/X509_sign.pod
+++ b/doc/man3/X509_sign.pod
@@ -25,6 +25,8 @@ sign certificate, certificate request, or CRL signature
 X509_sign() signs certificate I<x> using private key I<pkey> and message
 digest I<md> and sets the signature in I<x>. X509_sign_ctx() also signs
 certificate I<x> but uses the parameters contained in digest context I<ctx>.
+If the certificate information includes X.509 extensions,
+these two functions make sure that the certificate bears X.509 version 3.
 
 X509_REQ_sign(), X509_REQ_sign_ctx(),
 X509_CRL_sign(), and X509_CRL_sign_ctx()
diff --git a/doc/man5/x509v3_config.pod b/doc/man5/x509v3_config.pod
index e369997b60..cf42e9053a 100644
--- a/doc/man5/x509v3_config.pod
+++ b/doc/man5/x509v3_config.pod
@@ -173,14 +173,27 @@ Examples:
 =head2 Subject Key Identifier
 
 The SKID extension specification has a value with three choices.
-If the value is the word B<none> then no SKID extension will be included.
-If the value is the word B<hash>, or by default for the B<x509>, B<req>, and
-B<ca> apps, the process specified in RFC 5280 section 4.2.1.2. (1) is followed:
+
+=over 4
+
+=item B<none>
+
+No SKID extension will be included.
+
+=item B<hash>
+
+The process specified in RFC 5280 section 4.2.1.2. (1) is followed:
 The keyIdentifier is composed of the 160-bit SHA-1 hash of the value of the BIT
 STRING subjectPublicKey (excluding the tag, length, and number of unused bits).
 
-Otherwise, the value must be a hex string (possibly with C<:> separating bytes)
-to output directly, however, this is strongly discouraged.
+=item A hex string (possibly with C<:> separating bytes)
+
+The provided value is output directly.
+This choice is strongly discouraged.
+
+=back
+
+By default the B<x509>, B<req>, and B<ca> apps behave as if B<hash> was given.
 
 Example:
 
@@ -195,6 +208,7 @@ or both of them, separated by C<,>.
 Either or both can have the option B<always>,
 indicated by putting a colon C<:> between the value and this option.
 For self-signed certificates the AKID is suppressed unless B<always> is present.
+
 By default the B<x509>, B<req>, and B<ca> apps behave as if B<none> was given
 for self-signed certificates and B<keyid>C<,> B<issuer> otherwise.