cmp_util.c: Add OPENSSL_CTX parameter to ossl_cmp_build_cert_chain(), improve its doc

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/11808)

2 files changed, 33 insertions, 22 deletions

diff --git a/doc/internal/man3/ossl_cmp_asn1_octet_string_set1.pod b/doc/internal/man3/ossl_cmp_asn1_octet_string_set1.pod
index 3d91f8a073..a154cda1c9 100644
--- a/doc/internal/man3/ossl_cmp_asn1_octet_string_set1.pod
+++ b/doc/internal/man3/ossl_cmp_asn1_octet_string_set1.pod
@@ -3,9 +3,8 @@
 =head1 NAME
 
 ossl_cmp_asn1_octet_string_set1,
-ossl_cmp_asn1_octet_string_set1_bytes,
-ossl_cmp_build_cert_chain
-- misc internal utility functions
+ossl_cmp_asn1_octet_string_set1_bytes
+- ASN.1 octet string utility functions
 
 =head1 SYNOPSIS
 
@@ -16,32 +15,19 @@ ossl_cmp_build_cert_chain
  int ossl_cmp_asn1_octet_string_set1_bytes(ASN1_OCTET_STRING **tgt,
                                            const unsigned char *bytes, int len);
 
- STACK_OF(X509) *ossl_cmp_build_cert_chain(STACK_OF(X509) *certs, X509 *cert);
-
 =head1 DESCRIPTION
 
 ossl_cmp_asn1_octet_string_set1() frees any previous value of the variable
 referenced via the I<tgt> argument and assigns either a copy of
 the ASN1_OCTET_STRING given as the I<src> argument or NULL.
-It returns 1 on success, 0 on error.
 
 ossl_cmp_asn1_octet_string_set1_bytes() frees any previous value of the variable
 referenced via the I<tgt> argument and assigns either a copy of the given byte
-string (with the given length) or NULL. It returns 1 on success, 0 on error.
-
-ossl_cmp_build_cert_chain() builds up the certificate chain of cert as high up
-as possible using the given X509_STORE containing all possible intermediate
-certificates and optionally the (possible) trust anchor(s).
+string (with the given length) or NULL.
 
 =head1 RETURN VALUES
 
-ossl_cmp_build_cert_chain()
-returns NULL on error, else a pointer to a stack of (up_ref'ed) certificates
-containing the EE certificate given in the function arguments (cert)
-and all intermediate certificates up the chain toward the trust anchor.
-The (self-signed) trust anchor is not included.
-
-All other functions return 1 on success, 0 on error.
+All functions return 1 on success, 0 on error.
 
 =head1 HISTORY
 
diff --git a/doc/internal/man3/ossl_cmp_msg_protect.pod b/doc/internal/man3/ossl_cmp_msg_protect.pod
index bf859cdbda..484d76e5c4 100644
--- a/doc/internal/man3/ossl_cmp_msg_protect.pod
+++ b/doc/internal/man3/ossl_cmp_msg_protect.pod
@@ -2,19 +2,38 @@
 
 =head1 NAME
 
+ossl_cmp_build_cert_chain,
 ossl_cmp_msg_protect,
 ossl_cmp_msg_add_extraCerts
 - functions for producing CMP message protection
 
 =head1 SYNOPSIS
 
-  #include "cmp_int.h"
+ #include "cmp_local.h"
 
-  int ossl_cmp_msg_protect(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
-  int ossl_cmp_msg_add_extraCerts(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
+ STACK_OF(X509)
+     *ossl_cmp_build_cert_chain(OPENSSL_CTX *libctx, const char *propq,
+                                STACK_OF(X509) *certs, X509 *cert);
+
+ int ossl_cmp_msg_protect(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
+ int ossl_cmp_msg_add_extraCerts(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
 
 =head1 DESCRIPTION
 
+ossl_cmp_build_cert_chain() builds up the chain of intermediate CA certificates
+starting from of the given certificate B<cert> as high up as possible using
+the given list of candidate certificates, similarly to ssl_add_cert_chain().
+It internally uses a B<X509_STORE_CTX> structure associated with the library
+context I<libctx> and property query string I<propq>, both of which may be NULL.
+Intended use of this function is to find all the certificates above the trust
+anchor needed to verify an EE's own certificate.
+Those are supposed to be included in the ExtraCerts field of every first
+CMP message of a transaction when MSG_SIG_ALG is utilized.
+This allocates a stack and increments the reference count of each cert,
+so when not needed any more the stack and all its elements should be freed.
+In case there is more than one possibility for the chain,
+OpenSSL seems to take the first one; check X509_verify_cert() for details.
+
 ossl_cmp_msg_protect() (re-)protects the given message B<msg> using an algorithm
 depending on the available context information given in the B<ctx>.
 If there is a secretValue it selects PBMAC, else if there is a protection cert
@@ -35,7 +54,13 @@ CMP is defined in RFC 4210 (and CRMF in RFC 4211).
 
 =head1 RETURN VALUES
 
-All functions return 1 on success, 0 on error.
+ossl_cmp_build_cert_chain() returns NULL on error,
+else a pointer to a stack of (up_ref'ed) certificates
+containing the EE certificate given in the function arguments (cert)
+and all intermediate certificates up the chain toward the trust anchor.
+The (self-signed) trust anchor is not included.
+
+All other functions return 1 on success, 0 on error.
 
 =head1 HISTORY