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)

1 files changed, 24 insertions, 3 deletions

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