ESS: Export three core functions, clean up TS and CMS CAdES-BES usage

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

4 files changed, 99 insertions, 0 deletions

diff --git a/doc/build.info b/doc/build.info
index d9c5d8d4fc..86daf403d7 100644
--- a/doc/build.info
+++ b/doc/build.info
@@ -1602,6 +1602,10 @@ DEPEND[html/man3/OSSL_ENCODER_to_bio.html]=man3/OSSL_ENCODER_to_bio.pod
 GENERATE[html/man3/OSSL_ENCODER_to_bio.html]=man3/OSSL_ENCODER_to_bio.pod
 DEPEND[man/man3/OSSL_ENCODER_to_bio.3]=man3/OSSL_ENCODER_to_bio.pod
 GENERATE[man/man3/OSSL_ENCODER_to_bio.3]=man3/OSSL_ENCODER_to_bio.pod
+DEPEND[html/man3/OSSL_ESS_check_signing_certs.html]=man3/OSSL_ESS_check_signing_certs.pod
+GENERATE[html/man3/OSSL_ESS_check_signing_certs.html]=man3/OSSL_ESS_check_signing_certs.pod
+DEPEND[man/man3/OSSL_ESS_check_signing_certs.3]=man3/OSSL_ESS_check_signing_certs.pod
+GENERATE[man/man3/OSSL_ESS_check_signing_certs.3]=man3/OSSL_ESS_check_signing_certs.pod
 DEPEND[html/man3/OSSL_HTTP_REQ_CTX.html]=man3/OSSL_HTTP_REQ_CTX.pod
 GENERATE[html/man3/OSSL_HTTP_REQ_CTX.html]=man3/OSSL_HTTP_REQ_CTX.pod
 DEPEND[man/man3/OSSL_HTTP_REQ_CTX.3]=man3/OSSL_HTTP_REQ_CTX.pod
@@ -3050,6 +3054,7 @@ html/man3/OSSL_ENCODER.html \
 html/man3/OSSL_ENCODER_CTX.html \
 html/man3/OSSL_ENCODER_CTX_new_for_pkey.html \
 html/man3/OSSL_ENCODER_to_bio.html \
+html/man3/OSSL_ESS_check_signing_certs.html \
 html/man3/OSSL_HTTP_REQ_CTX.html \
 html/man3/OSSL_HTTP_parse_url.html \
 html/man3/OSSL_HTTP_transfer.html \
@@ -3625,6 +3630,7 @@ man/man3/OSSL_ENCODER.3 \
 man/man3/OSSL_ENCODER_CTX.3 \
 man/man3/OSSL_ENCODER_CTX_new_for_pkey.3 \
 man/man3/OSSL_ENCODER_to_bio.3 \
+man/man3/OSSL_ESS_check_signing_certs.3 \
 man/man3/OSSL_HTTP_REQ_CTX.3 \
 man/man3/OSSL_HTTP_parse_url.3 \
 man/man3/OSSL_HTTP_transfer.3 \
diff --git a/doc/man3/CMS_verify.pod b/doc/man3/CMS_verify.pod
index 0331f7cf7e..33130bc9f2 100644
--- a/doc/man3/CMS_verify.pod
+++ b/doc/man3/CMS_verify.pod
@@ -122,6 +122,7 @@ be held in memory if it is not detached.
 
 =head1 SEE ALSO
 
+L<OSSL_ESS_check_signing_certs(3)>,
 L<ERR_get_error(3)>, L<CMS_sign(3)>
 
 =head1 COPYRIGHT
diff --git a/doc/man3/OSSL_ESS_check_signing_certs.pod b/doc/man3/OSSL_ESS_check_signing_certs.pod
new file mode 100644
index 0000000000..bff26193d7
--- /dev/null
+++ b/doc/man3/OSSL_ESS_check_signing_certs.pod
@@ -0,0 +1,88 @@
+=pod
+
+=head1 NAME
+
+OSSL_ESS_signing_cert_new_init,
+OSSL_ESS_signing_cert_v2_new_init,
+OSSL_ESS_check_signing_certs
+- Enhanced Security Services (ESS) functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/ess.h>
+
+ ESS_SIGNING_CERT *OSSL_ESS_signing_cert_new_init(const X509 *signcert,
+                                                  const STACK_OF(X509) *certs,
+                                                  int set_issuer_serial);
+ ESS_SIGNING_CERT_V2 *OSSL_ESS_signing_cert_v2_new_init(const EVP_MD *hash_alg,
+                                                        const X509 *signcert,
+                                                        const
+                                                        STACK_OF(X509) *certs,
+                                                        int set_issuer_serial);
+ int OSSL_ESS_check_signing_certs(const ESS_SIGNING_CERT *ss,
+                                  const ESS_SIGNING_CERT_V2 *ssv2,
+                                  const STACK_OF(X509) *chain,
+                                  int require_signing_cert);
+
+=head1 DESCRIPTION
+
+OSSL_ESS_signing_cert_new_init() generates a new B<ESS_SIGNING_CERT> structure
+referencing the given I<signcert> and any given further I<certs>
+using their SHA-1 fingerprints.
+If I<set_issuer_serial> is nonzero then also the issuer and serial number
+of I<signcert> are included in the B<ESS_CERT_ID> as the B<issuerSerial> field.
+For all members of I<certs> the  B<issuerSerial> field is always included.
+
+OSSL_ESS_signing_cert_v2_new_init() is the same as
+OSSL_ESS_signing_cert_new_init() except that it uses the given I<hash_alg> and
+generates a B<ESS_SIGNING_CERT_V2> structure with B<ESS_CERT_ID_V2> elements.
+
+OSSL_ESS_check_signing_certs() checks if the validation chain I<chain> contains
+the certificates required by the identifiers given in I<ss> and/or I<ssv2>.
+If I<require_signing_cert> is nonzero, I<ss> or I<ssv2> must not be NULL.
+If both I<ss> and I<ssv2> are not NULL, they are evaluated independently.
+The list of certificate identifiers in I<ss> is of type B<ESS_CERT_ID>,
+while the list contained in I<ssv2> is of type B<ESS_CERT_ID_V2>.
+As far as these lists are present, they must be nonempty.
+The certificate identified by their first entry must be the first element of
+I<chain>, i.e. the signer certificate.
+Any further certficates referenced in the list must also be found in I<chain>.
+The matching is done using the given certificate hash algorithm and value.
+In addition to the checks required by RFCs 2624 and 5035,
+if the B<issuerSerial> field is included in an B<ESSCertID> or B<ESSCertIDv2>
+it must match the certificate issuer and serial number attributes.
+
+=head1 NOTES
+
+ESS has been defined in RFC 2634, which has been updated in RFC 5035
+(ESS version 2) to support hash algorithms other than SHA-1.
+This is used for TSP (RFC 3161) and CAdES-BES (informational RFC 5126).
+
+=head1 RETURN VALUES
+
+OSSL_ESS_signing_cert_new_init() and OSSL_ESS_signing_cert_v2_new_init()
+return a pointer to the new structure or NULL on malloc failure.
+
+OSSL_ESS_check_signing_certs() returns 1 on success,
+0 if a required certificate cannot be found, -1 on other error.
+
+=head1 SEE ALSO
+
+L<TS_VERIFY_CTX_set_certs(3)>,
+L<CMS_verify(3)>
+
+=head1 HISTORY
+
+OSSL_ESS_signing_cert_new_init(), OSSL_ESS_signing_cert_v2_new_init(), and
+OSSL_ESS_check_signing_certs() were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man3/TS_VERIFY_CTX_set_certs.pod b/doc/man3/TS_VERIFY_CTX_set_certs.pod
index 26c9a66abc..cf6aee1921 100644
--- a/doc/man3/TS_VERIFY_CTX_set_certs.pod
+++ b/doc/man3/TS_VERIFY_CTX_set_certs.pod
@@ -39,6 +39,10 @@ which takes the same parameters and returns the same result.
 TS_VERIFY_CTX_set_certs() returns the stack of B<X509> certificates the user
 passes in via parameter B<certs>.
 
+=head1 SEE ALSO
+
+L<OSSL_ESS_check_signing_certs(3)>
+
 =head1 HISTORY
 
 The spelling of TS_VERIFY_CTX_set_certs() was corrected in OpenSSL 3.0.0.