Add/harmonize multi-valued RDN support and doc of ca, cmp, req, storeutl, and x509 apps

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

5 files changed, 51 insertions, 36 deletions

diff --git a/doc/man1/openssl-ca.pod.in b/doc/man1/openssl-ca.pod.in
index 7d7f0752f3..d196565422 100644
--- a/doc/man1/openssl-ca.pod.in
+++ b/doc/man1/openssl-ca.pod.in
@@ -285,11 +285,17 @@ used).
 =item B<-subj> I<arg>
 
 Supersedes subject name given in the request.
+
 The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
-Keyword characters may be escaped by C<\> (backslash), and whitespace is
-retained.
+Special characters may be escaped by C<\> (backslash), whitespace is retained.
 Empty values are permitted, but the corresponding type will not be included
 in the resulting certificate.
+Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN).
+Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
+between the AttributeValueAssertions (AVAs) that specify the members of the set.
+Example:
+
+C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
 
 =item B<-utf8>
 
@@ -313,12 +319,7 @@ This overrides any option or configuration to use a serial number file.
 
 =item B<-multivalue-rdn>
 
-This option causes the -subj argument to be interpreted with full
-support for multivalued RDNs. Example:
-
-C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
-
-If B<-multi-rdn> is not used then the UID value is C<123456+CN=John Doe>.
+This option has been deprecated and has no effect.
 
 {- $OpenSSL::safe::opt_r_item -}
 
@@ -791,7 +792,8 @@ retained mainly for compatibility reasons.
 
 The B<-section> option was added in OpenSSL 3.0.0.
 
-The B<-certform> option has become obsolete in OpenSSL 3.0.0 and has no effect.
+The B<-certform> and B<-multivalue-rdn> options
+have become obsolete in OpenSSL 3.0.0 and have no effect.
 
 All B<-keyform> values except B<ENGINE> have become obsolete in OpenSSL 3.0.0
 and have no effect.
diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in
index 9389701893..44f71b8358 100644
--- a/doc/man1/openssl-cmp.pod.in
+++ b/doc/man1/openssl-cmp.pod.in
@@ -268,20 +268,24 @@ For KUR, it defaults to the subject DN of the reference certificate
 (see B<-oldcert>).
 This default is used for IR and CR only if no SANs are set.
 
-The argument must be formatted as I</type0=value0/type1=value1/type2=...>,
-characters may be escaped by C<\>E<nbsp>(backslash), no spaces are skipped.
-
 The subject DN is also used as fallback sender of outgoing CMP messages
 if no B<-cert> and no B<-oldcert> are given.
 
+The argument must be formatted as I</type0=value0/type1=value1/type2=...>.
+Special characters may be escaped by C<\> (backslash), whitespace is retained.
+Empty values are permitted, but the corresponding type will not be included.
+Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN).
+Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
+between the AttributeValueAssertions (AVAs) that specify the members of the set.
+Example:
+
+C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
+
 =item B<-issuer> I<name>
 
 X509 issuer Distinguished Name (DN) of the CA server
 to place in the requested certificate template in IR/CR/KUR.
 
-The argument must be formatted as I</type0=value0/type1=value1/type2=...>,
-characters may be escaped by C<\>E<nbsp>(backslash), no spaces are skipped.
-
 If neither B<-srvcert> nor B<-recipient> is available,
 the name given in this option is also set as the recipient of the CMP message.
 
@@ -519,10 +523,6 @@ and as default value for the expected sender of incoming CMP messages.
 Distinguished Name (DN) to use in the recipient field of CMP request messages,
 i.e., the CMP server (usually the addressed CA).
 
-The argument must be formatted as I</type0=value0/type1=value1/type2=...>,
-characters may be escaped by C<\>E<nbsp>(backslash), no spaces are skipped.
-The empty name (NULL-DN) can be given explicitly as a single slash: 'I</>'.
-
 The recipient field in the header of a CMP message is mandatory.
 If not given explicitly the recipient is determined in the following order:
 the subject of the CMP server certificate given with the B<-srvcert> option,
@@ -536,9 +536,6 @@ as far as any of those is present, else the NULL-DN as last resort.
 Distinguished Name (DN) expected in the sender field of incoming CMP messages.
 Defaults to the subject DN of the pinned B<-srvcert>, if any.
 
-The argument must be formatted as I</type0=value0/type1=value1/type2=...>,
-characters may be escaped by C<\>E<nbsp>(backslash), no spaces are skipped.
-
 This can be used to make sure that only a particular entity is accepted as
 CMP message signer, and attackers are not able to use arbitrary certificates
 of a trusted PKI hierarchy to fraudulently pose as a CMP server.
diff --git a/doc/man1/openssl-req.pod.in b/doc/man1/openssl-req.pod.in
index 1af355b5b3..52b2326d78 100644
--- a/doc/man1/openssl-req.pod.in
+++ b/doc/man1/openssl-req.pod.in
@@ -32,7 +32,6 @@ B<openssl> B<req>
 [B<-I<digest>>]
 [B<-config> I<filename>]
 [B<-section> I<name>]
-[B<-multivalue-rdn>]
 [B<-x509>]
 [B<-days> I<n>]
 [B<-set_serial> I<n>]
@@ -45,6 +44,7 @@ B<openssl> B<req>
 [B<-reqopt>]
 [B<-subject>]
 [B<-subj> I<arg>]
+[B<-multivalue-rdn>]
 [B<-sigopt> I<nm>:I<v>]
 [B<-vfyopt> I<nm>:I<v>]
 [B<-batch>]
@@ -233,19 +233,21 @@ Specifies the name of the section to use; the default is B<req>.
 
 Sets subject name for new request or supersedes the subject name
 when processing a request.
+
 The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
-Keyword characters may be escaped by \ (backslash), and whitespace is retained.
+Special characters may be escaped by C<\> (backslash), whitespace is retained.
 Empty values are permitted, but the corresponding type will not be included
 in the request.
-
-=item B<-multivalue-rdn>
-
-This option causes the -subj argument to be interpreted with full
-support for multivalued RDNs. Example:
+Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN).
+Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
+between the AttributeValueAssertions (AVAs) that specify the members of the set.
+Example:
 
 C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
 
-If -multi-rdn is not used then the UID value is C<123456+CN=John Doe>.
+=item B<-multivalue-rdn>
+
+This option has been deprecated and has no effect.
 
 =item B<-x509>
 
@@ -697,8 +699,8 @@ L<x509v3_config(5)>
 
 The B<-section> option was added in OpenSSL 3.0.0.
 
-All B<-keyform> values except B<ENGINE> have become obsolete in OpenSSL 3.0.0
-and have no effect.
+All B<-keyform> values except B<ENGINE> and the B<-multivalue-rdn> option
+have become obsolete in OpenSSL 3.0.0 and have no effect.
 
 The B<-engine> option was deprecated in OpenSSL 3.0.
 The <-nodes> option was deprecated in OpenSSL 3.0, too; use B<-noenc> instead.
diff --git a/doc/man1/openssl-storeutl.pod.in b/doc/man1/openssl-storeutl.pod.in
index 2c92f825a0..bc2eec17f7 100644
--- a/doc/man1/openssl-storeutl.pod.in
+++ b/doc/man1/openssl-storeutl.pod.in
@@ -80,11 +80,19 @@ returned.
 =item B<-subject> I<arg>
 
 Search for an object having the subject name I<arg>.
+
 The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
-Keyword characters may be escaped by \ (backslash), and whitespace is retained.
+Special characters may be escaped by C<\> (backslash), whitespace is retained.
 Empty values are permitted but are ignored for the search.  That is,
 a search with an empty value will have the same effect as not specifying
 the type at all.
+Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN).
+Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
+between the AttributeValueAssertions (AVAs) that specify the members of the set.
+
+Example:
+
+C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
 
 =item B<-issuer> I<arg>
 
diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in
index 8eb35e537e..fb4be2c264 100644
--- a/doc/man1/openssl-x509.pod.in
+++ b/doc/man1/openssl-x509.pod.in
@@ -517,11 +517,17 @@ generate a certificate containing any desired public key.
 =item B<-subj> I<arg>
 
 When a certificate is created set its subject name to the given value.
+
 The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
-Keyword characters may be escaped by \ (backslash), and whitespace is retained.
+Special characters may be escaped by C<\> (backslash), whitespace is retained.
 Empty values are permitted, but the corresponding type will not be included
-in the certificate. Giving a single C</> will lead to an empty sequence of RDNs
-(a NULL subject DN).
+in the certificate.
+Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN).
+Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
+between the AttributeValueAssertions (AVAs) that specify the members of the set.
+Example:
+
+C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
 
 Unless the B<-CA> option is given the issuer is set to the same value.