OSSL_CMP_CTX_setup_CRM(): Fix handling of defaults from CSR and refcert

Also update and complete related documentation.

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/17726)

4 files changed, 43 insertions, 13 deletions

diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in
index 5a111a39eb..6bbea0b089 100644
--- a/doc/man1/openssl-cmp.pod.in
+++ b/doc/man1/openssl-cmp.pod.in
@@ -252,8 +252,8 @@ e.g., C<1.2.3.4:int:56789>.
 The source of the private or public key for the certificate requested
 in Initialization Request (IR), Certification Request(CR), or
 Key Update Request (KUR).
-Default is the public key in the PKCS#10 CSR given with the B<-csr> option,
-if any, or else the current client key, if given.
+Defaults to the public key in the PKCS#10 CSR given with the B<-csr> option,
+the public key of the reference certificate, or the current client key.
 
 =item B<-newkeypass> I<arg>
 
diff --git a/doc/man3/OSSL_CMP_CTX_new.pod b/doc/man3/OSSL_CMP_CTX_new.pod
index 883bda8b69..f40c9a0f93 100644
--- a/doc/man3/OSSL_CMP_CTX_new.pod
+++ b/doc/man3/OSSL_CMP_CTX_new.pod
@@ -547,7 +547,7 @@ OSSL_CMP_CTX_push1_subjectAltName() adds the given X509 name to the list of
 alternate names on the certificate template request. This cannot be used if
 any Subject Alternative Name extension is set via
 OSSL_CMP_CTX_set0_reqExtensions().
-By default, unless OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT has been set,
+By default, unless B<OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT> has been set,
 the Subject Alternative Names are copied from the reference certificate,
 see OSSL_CMP_CTX_set1_oldCert().
 If set and the subject DN is not set with OSSL_CMP_CTX_set1_subjectName() then
@@ -568,14 +568,16 @@ to the X509_EXTENSIONS of the requested certificate template.
 OSSL_CMP_CTX_set1_oldCert() sets the old certificate to be updated in
 Key Update Requests (KUR) or to be revoked in Revocation Requests (RR).
 It must be given for RR, else it defaults to the CMP signer certificate.
-The reference certificate determined in this way, if any, is also used for
-deriving default subject DN and Subject Alternative Names and the
+The I<reference certificate> determined in this way, if any, is also used for
+deriving default subject DN, public key, Subject Alternative Names, and the
 default issuer entry in the requested certificate template of IR/CR/KUR.
 The subject of the reference certificate is used as the sender field value
 in CMP message headers.
 Its issuer is used as default recipient in CMP message headers.
 
-OSSL_CMP_CTX_set1_p10CSR() sets the PKCS#10 CSR to be used in P10CR.
+OSSL_CMP_CTX_set1_p10CSR() sets the PKCS#10 CSR to use in P10CR messages.
+If such a CSR is provided, its subject, public key, and extension fields are
+also used as fallback values for the certificate template of IR/CR/KUR messages.
 
 OSSL_CMP_CTX_push0_genm_ITAV() adds I<itav> to the stack in the I<ctx> which
 will be the body of a General Message sent with this context.
diff --git a/doc/man3/OSSL_CMP_MSG_get0_header.pod b/doc/man3/OSSL_CMP_MSG_get0_header.pod
index 741349cd6e..1fedde8484 100644
--- a/doc/man3/OSSL_CMP_MSG_get0_header.pod
+++ b/doc/man3/OSSL_CMP_MSG_get0_header.pod
@@ -36,12 +36,40 @@ in the header of the given message according to the CMP_CTX.
 This requires re-protecting the message (if it was protected).
 
 OSSL_CMP_CTX_setup_CRM() creates a CRMF certificate request message
+from various information provided in the CMP context argument I<ctx>
 for inclusion in a CMP request message based on details contained in I<ctx>.
-If the CMP context does not include a subject name set via
-L<OSSL_CMP_CTX_set1_subjectName(3)> but includes a reference certificate
-then it copies the subject DN from there
-if I<for_KUR> is set or the I<ctx> does not include a subjectAltName.
-The I<rid> defines the request identifier to use, which typically is 0.
+The I<rid> argument defines the request identifier to use, which typically is 0.
+
+The subject DN to include in the certificate template is determined as follows.
+If I<ctx> includes a subject name set via L<OSSL_CMP_CTX_set1_subjectName(3)>,
+this name is used.
+Otherwise, if a PKCS#10 CSR is given in I<ctx>, its subject is used.
+Otherwise, if a reference certificate is given in I<ctx>
+(see L<OSSL_CMP_CTX_set1_oldCert(3)>), its subject is used if I<for_KUR>
+is nonzero or the I<ctx> does not include a Subject Alternative Name.
+
+The public key to include is taken from any value set via
+L<OSSL_CMP_CTX_set0_newPkey(3)>,
+otherwise the public key of any PKCS#10 CSR is given in I<ctx>,
+otherwise the public key of any reference certificate given in I<ctx>,
+otherwise it is derived from the client private key if given in I<ctx>.
+
+The set of X.509 extensions to include is computed as follows.
+If a PKCS#10 CSR is present in I<ctx>, default extensions are taken from there,
+otherwise the empty set is taken as the initial value.
+If there is a reference certificate in I<ctx> and contains Subject Alternative
+Names (SANs) and B<OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT> is not set,
+these override any SANs from the PKCS#10 CSR.
+The extensions are further augmented or overridden by any extensions with the
+same OIDs included in the I<ctx> via L<OSSL_CMP_CTX_set0_reqExtensions(3)>.
+The SANs are further overridden by any SANs included in I<ctx> via
+L<OSSL_CMP_CTX_push1_subjectAltName(3)>.
+Finally, policies are overridden by any policies included in I<ctx> via
+L<OSSL_CMP_CTX_push0_policy(3)>.
+
+OSSL_CMP_CTX_setup_CRM() also sets the sets the regToken control B<oldCertID>
+for KUR messages using the issuer name and serial number of the reference
+certificate, if present.
 
 OSSL_CMP_MSG_read() loads a DER-encoded OSSL_CMP_MSG from I<file>.
 
diff --git a/doc/man3/OSSL_CRMF_MSG_set1_regCtrl_regToken.pod b/doc/man3/OSSL_CRMF_MSG_set1_regCtrl_regToken.pod
index 96281b67a8..5f695cf8c5 100644
--- a/doc/man3/OSSL_CRMF_MSG_set1_regCtrl_regToken.pod
+++ b/doc/man3/OSSL_CRMF_MSG_set1_regCtrl_regToken.pod
@@ -89,8 +89,8 @@ section 6.3.
 OSSL_CRMF_MSG_set1_regCtrl_protocolEncrKey() sets the protocolEncrKey control in
 the given I<msg> copying the given I<pubkey> as value. See RFC 4211 section 6.6.
 
-OSSL_CRMF_MSG_set1_regCtrl_oldCertID() sets the oldCertID control in the given
-I<msg> copying the given I<cid> as value. See RFC 4211, section 6.5.
+OSSL_CRMF_MSG_set1_regCtrl_oldCertID() sets the B<oldCertID> regToken control in
+the given I<msg> copying the given I<cid> as value. See RFC 4211, section 6.5.
 
 OSSL_CRMF_CERTID_gen produces an OSSL_CRMF_CERTID_gen structure copying the
 given I<issuer> name and I<serial> number.