diff options
author | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2021-03-15 20:24:40 +0100 |
---|---|---|
committer | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2021-04-28 14:10:45 +0200 |
commit | 1751768cd191c3541dc89a2bb24da1e506385c37 (patch) | |
tree | 8921c0c143160551591d5d2e3f9b3a62ee419a6a /doc/man3 | |
parent | 624359374b9af4f99ce1bfaf89e28b7306987777 (diff) |
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)
Diffstat (limited to 'doc/man3')
-rw-r--r-- | doc/man3/CMS_verify.pod | 1 | ||||
-rw-r--r-- | doc/man3/OSSL_ESS_check_signing_certs.pod | 88 | ||||
-rw-r--r-- | doc/man3/TS_VERIFY_CTX_set_certs.pod | 4 |
3 files changed, 93 insertions, 0 deletions
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. |