Improve ossl_cmp_build_cert_chain(); publish it as X509_build_chain()

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

2 files changed, 24 insertions, 23 deletions

diff --git a/doc/internal/man3/ossl_cmp_msg_protect.pod b/doc/internal/man3/ossl_cmp_msg_protect.pod
index 681d572af5..11a7a02901 100644
--- a/doc/internal/man3/ossl_cmp_msg_protect.pod
+++ b/doc/internal/man3/ossl_cmp_msg_protect.pod
@@ -2,7 +2,6 @@
 
 =head1 NAME
 
-ossl_cmp_build_cert_chain,
 ossl_cmp_calc_protection,
 ossl_cmp_msg_protect,
 ossl_cmp_msg_add_extraCerts
@@ -12,10 +11,6 @@ ossl_cmp_msg_add_extraCerts
 
  #include "cmp_local.h"
 
- STACK_OF(X509)
-     *ossl_cmp_build_cert_chain(OSSL_LIB_CTX *libctx, const char *propq,
-                                X509_STORE *store,
-                                STACK_OF(X509) *certs, X509 *cert);
  ASN1_BIT_STRING *ossl_cmp_calc_protection(const OSSL_CMP_CTX *ctx,
                                            const OSSL_CMP_MSG *msg);
  int ossl_cmp_msg_protect(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
@@ -23,16 +18,6 @@ ossl_cmp_msg_add_extraCerts
 
 =head1 DESCRIPTION
 
-ossl_cmp_build_cert_chain() builds a certificate chain starting from I<cert>
-using the optional list of intermediate CA certificates I<certs>.
-If I<store> is NULL builds the chain as far down as possible, ignoring errors.
-Else the chain must reach a trust anchor contained in I<store>.
-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.
-If a non-NULL stack is returned the caller is responsible for freeing it.
-In case there is more than one possibility for the chain,
-OpenSSL seems to take the first one; check L<X509_verify_cert(3)> for details.
-
 ossl_cmp_calc_protection() calculates the protection for the given I<msg>
 according to the algorithm and parameters in the message header's protectionAlg
 using the credentials, library context, and property criteria in the I<ctx>.
@@ -57,11 +42,6 @@ CMP is defined in RFC 4210 (and CRMF in RFC 4211).
 
 =head1 RETURN VALUES
 
-ossl_cmp_build_cert_chain() returns NULL on error,
-else a pointer to a stack of (up_ref'ed) certificates
-starting with given EE certificate and followed by all available intermediate
-certificates down towards (but excluding) any trusted root certificate.
-
 ossl_cmp_calc_protection() returns the protection on success, else NULL.
 
 All other functions return 1 on success, 0 on error.
diff --git a/doc/man3/X509_verify_cert.pod b/doc/man3/X509_verify_cert.pod
index deb6b15869..a14a0b25c4 100644
--- a/doc/man3/X509_verify_cert.pod
+++ b/doc/man3/X509_verify_cert.pod
@@ -2,18 +2,36 @@
 
 =head1 NAME
 
+X509_build_chain,
 X509_verify_cert,
-X509_STORE_CTX_verify - discover and verify X509 certificate chain
+X509_STORE_CTX_verify - build and verify X509 certificate chain
 
 =head1 SYNOPSIS
 
  #include <openssl/x509_vfy.h>
 
+ STACK_OF(X509) *X509_build_chain(X509 *target, STACK_OF(X509) *certs,
+                                  X509_STORE *store, int with_self_signed,
+                                  OSSL_LIB_CTX *libctx, const char *propq);
  int X509_verify_cert(X509_STORE_CTX *ctx);
  int X509_STORE_CTX_verify(X509_STORE_CTX *ctx);
 
 =head1 DESCRIPTION
 
+X509_build_chain() builds a certificate chain starting from I<target>
+using the optional list of intermediate CA certificates I<certs>.
+If I<store> is NULL it builds the chain as far down as possible, ignoring errors.
+Else the chain must reach a trust anchor contained in I<store>.
+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.
+In case there is more than one possibility for the chain, only one is taken.
+
+On success it returns a pointer to a new stack of (up_ref'ed) certificates
+starting with I<target> and followed by all available intermediate certificates.
+A self-signed trust anchor is included only if I<target> is the trust anchor
+of I<with_self_signed> is 1.
+If a non-NULL stack is returned the caller is responsible for freeing it.
+
 The X509_verify_cert() function attempts to discover and validate a
 certificate chain based on parameters in I<ctx>.
 The verification context, of type B<X509_STORE_CTX>, can be constructed
@@ -45,7 +63,10 @@ in I<ctx> unless a target certificate is set explicitly.
 
 =head1 RETURN VALUES
 
-Both functions return 1 if a complete chain can be built and validated,
+X509_build_chain() returns NULL on error, else a stack of certificates.
+
+Both X509_verify_cert() and X509_STORE_CTX_verify()
+return 1 if a complete chain can be built and validated,
 otherwise they return 0, and in exceptional circumstances (such as malloc
 failure and internal errors) they can also return a negative code.
 
@@ -66,7 +87,7 @@ L<X509_STORE_CTX_get_error(3)>
 
 =head1 HISTORY
 
-X509_STORE_CTX_verify() was added in OpenSSL 3.0.
+X509_build_chain() and X509_STORE_CTX_verify() were added in OpenSSL 3.0.
 
 =head1 COPYRIGHT