1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryOSSL_ESS_signing_cert_new_init, 6b077aed3SPierre ProncheryOSSL_ESS_signing_cert_v2_new_init, 7b077aed3SPierre ProncheryOSSL_ESS_check_signing_certs 8b077aed3SPierre Pronchery- Enhanced Security Services (ESS) functions 9b077aed3SPierre Pronchery 10b077aed3SPierre Pronchery=head1 SYNOPSIS 11b077aed3SPierre Pronchery 12b077aed3SPierre Pronchery #include <openssl/ess.h> 13b077aed3SPierre Pronchery 14b077aed3SPierre Pronchery ESS_SIGNING_CERT *OSSL_ESS_signing_cert_new_init(const X509 *signcert, 15b077aed3SPierre Pronchery const STACK_OF(X509) *certs, 16b077aed3SPierre Pronchery int set_issuer_serial); 17b077aed3SPierre Pronchery ESS_SIGNING_CERT_V2 *OSSL_ESS_signing_cert_v2_new_init(const EVP_MD *hash_alg, 18b077aed3SPierre Pronchery const X509 *signcert, 19b077aed3SPierre Pronchery const 20b077aed3SPierre Pronchery STACK_OF(X509) *certs, 21b077aed3SPierre Pronchery int set_issuer_serial); 22b077aed3SPierre Pronchery int OSSL_ESS_check_signing_certs(const ESS_SIGNING_CERT *ss, 23b077aed3SPierre Pronchery const ESS_SIGNING_CERT_V2 *ssv2, 24b077aed3SPierre Pronchery const STACK_OF(X509) *chain, 25b077aed3SPierre Pronchery int require_signing_cert); 26b077aed3SPierre Pronchery 27b077aed3SPierre Pronchery=head1 DESCRIPTION 28b077aed3SPierre Pronchery 29b077aed3SPierre ProncheryOSSL_ESS_signing_cert_new_init() generates a new B<ESS_SIGNING_CERT> structure 30b077aed3SPierre Proncheryreferencing the given I<signcert> and any given further I<certs> 31b077aed3SPierre Proncheryusing their SHA-1 fingerprints. 32b077aed3SPierre ProncheryIf I<set_issuer_serial> is nonzero then also the issuer and serial number 33b077aed3SPierre Proncheryof I<signcert> are included in the B<ESS_CERT_ID> as the B<issuerSerial> field. 34b077aed3SPierre ProncheryFor all members of I<certs> the B<issuerSerial> field is always included. 35b077aed3SPierre Pronchery 36b077aed3SPierre ProncheryOSSL_ESS_signing_cert_v2_new_init() is the same as 37b077aed3SPierre ProncheryOSSL_ESS_signing_cert_new_init() except that it uses the given I<hash_alg> and 38b077aed3SPierre Proncherygenerates a B<ESS_SIGNING_CERT_V2> structure with B<ESS_CERT_ID_V2> elements. 39b077aed3SPierre Pronchery 40b077aed3SPierre ProncheryOSSL_ESS_check_signing_certs() checks if the validation chain I<chain> contains 41b077aed3SPierre Proncherythe certificates required by the identifiers given in I<ss> and/or I<ssv2>. 42b077aed3SPierre ProncheryIf I<require_signing_cert> is nonzero, I<ss> or I<ssv2> must not be NULL. 43b077aed3SPierre ProncheryIf both I<ss> and I<ssv2> are not NULL, they are evaluated independently. 44b077aed3SPierre ProncheryThe list of certificate identifiers in I<ss> is of type B<ESS_CERT_ID>, 45b077aed3SPierre Proncherywhile the list contained in I<ssv2> is of type B<ESS_CERT_ID_V2>. 46b077aed3SPierre ProncheryAs far as these lists are present, they must be nonempty. 47b077aed3SPierre ProncheryThe certificate identified by their first entry must be the first element of 48b077aed3SPierre ProncheryI<chain>, i.e. the signer certificate. 49*aa795734SPierre ProncheryAny further certificates referenced in the list must also be found in I<chain>. 50b077aed3SPierre ProncheryThe matching is done using the given certificate hash algorithm and value. 51b077aed3SPierre ProncheryIn addition to the checks required by RFCs 2624 and 5035, 52b077aed3SPierre Proncheryif the B<issuerSerial> field is included in an B<ESSCertID> or B<ESSCertIDv2> 53b077aed3SPierre Proncheryit must match the certificate issuer and serial number attributes. 54b077aed3SPierre Pronchery 55b077aed3SPierre Pronchery=head1 NOTES 56b077aed3SPierre Pronchery 57b077aed3SPierre ProncheryESS has been defined in RFC 2634, which has been updated in RFC 5035 58b077aed3SPierre Pronchery(ESS version 2) to support hash algorithms other than SHA-1. 59b077aed3SPierre ProncheryThis is used for TSP (RFC 3161) and CAdES-BES (informational RFC 5126). 60b077aed3SPierre Pronchery 61b077aed3SPierre Pronchery=head1 RETURN VALUES 62b077aed3SPierre Pronchery 63b077aed3SPierre ProncheryOSSL_ESS_signing_cert_new_init() and OSSL_ESS_signing_cert_v2_new_init() 64b077aed3SPierre Proncheryreturn a pointer to the new structure or NULL on malloc failure. 65b077aed3SPierre Pronchery 66b077aed3SPierre ProncheryOSSL_ESS_check_signing_certs() returns 1 on success, 67b077aed3SPierre Pronchery0 if a required certificate cannot be found, -1 on other error. 68b077aed3SPierre Pronchery 69b077aed3SPierre Pronchery=head1 SEE ALSO 70b077aed3SPierre Pronchery 71b077aed3SPierre ProncheryL<TS_VERIFY_CTX_set_certs(3)>, 72b077aed3SPierre ProncheryL<CMS_verify(3)> 73b077aed3SPierre Pronchery 74b077aed3SPierre Pronchery=head1 HISTORY 75b077aed3SPierre Pronchery 76b077aed3SPierre ProncheryOSSL_ESS_signing_cert_new_init(), OSSL_ESS_signing_cert_v2_new_init(), and 77b077aed3SPierre ProncheryOSSL_ESS_check_signing_certs() were added in OpenSSL 3.0. 78b077aed3SPierre Pronchery 79b077aed3SPierre Pronchery=head1 COPYRIGHT 80b077aed3SPierre Pronchery 81*aa795734SPierre ProncheryCopyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved. 82b077aed3SPierre Pronchery 83b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 84b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 85b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 86b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 87b077aed3SPierre Pronchery 88b077aed3SPierre Pronchery=cut 89