1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryOSSL_CMP_validate_msg, 6b077aed3SPierre ProncheryOSSL_CMP_validate_cert_path 7b077aed3SPierre Pronchery- functions for verifying CMP message protection 8b077aed3SPierre Pronchery 9b077aed3SPierre Pronchery=head1 SYNOPSIS 10b077aed3SPierre Pronchery 11b077aed3SPierre Pronchery #include <openssl/cmp.h> 12b077aed3SPierre Pronchery int OSSL_CMP_validate_msg(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg); 13b077aed3SPierre Pronchery int OSSL_CMP_validate_cert_path(const OSSL_CMP_CTX *ctx, 14b077aed3SPierre Pronchery X509_STORE *trusted_store, X509 *cert); 15b077aed3SPierre Pronchery 16b077aed3SPierre Pronchery=head1 DESCRIPTION 17b077aed3SPierre Pronchery 18b077aed3SPierre ProncheryThis is the API for validating the protection of CMP messages, 19b077aed3SPierre Proncherywhich includes validating CMP message sender certificates and their paths 20b077aed3SPierre Proncherywhile optionally checking the revocation status of the certificates(s). 21b077aed3SPierre Pronchery 22b077aed3SPierre ProncheryOSSL_CMP_validate_msg() validates the protection of the given I<msg>, 23b077aed3SPierre Proncherywhich must be signature-based or using password-based MAC (PBM). 24b077aed3SPierre ProncheryIn the former case a suitable trust anchor must be given in the CMP context 25b077aed3SPierre ProncheryI<ctx>, and in the latter case the matching secret must have been set there 26b077aed3SPierre Proncheryusing L<OSSL_CMP_CTX_set1_secretValue(3)>. 27b077aed3SPierre Pronchery 28b077aed3SPierre ProncheryIn case of signature algorithm, the certificate to use for the signature check 29b077aed3SPierre Proncheryis preferably the one provided by a call to L<OSSL_CMP_CTX_set1_srvCert(3)>. 30b077aed3SPierre ProncheryIf no such sender cert has been pinned then candidate sender certificates are 31b077aed3SPierre Proncherytaken from the list of certificates received in the I<msg> extraCerts, then any 32b077aed3SPierre Proncherycertificates provided before via L<OSSL_CMP_CTX_set1_untrusted(3)>, and 33b077aed3SPierre Proncherythen all trusted certificates provided via L<OSSL_CMP_CTX_set0_trustedStore(3)>, 34b077aed3SPierre Proncherywhere a candidate is acceptable only if has not expired, its subject DN matches 35b077aed3SPierre Proncherythe I<msg> sender DN (as far as present), and its subject key identifier 36b077aed3SPierre Proncheryis present and matches the senderKID (as far as the latter present). 37b077aed3SPierre ProncheryEach acceptable cert is tried in the given order to see if the message 38b077aed3SPierre Proncherysignature check succeeds and the cert and its path can be verified 39b077aed3SPierre Proncheryusing any trust store set via L<OSSL_CMP_CTX_set0_trustedStore(3)>. 40b077aed3SPierre Pronchery 41b077aed3SPierre ProncheryIf the option OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR was set by calling 42b077aed3SPierre ProncheryL<OSSL_CMP_CTX_set_option(3)>, for an Initialization Response (IP) message 43*a7148ab3SEnji Cooperany self-issued certificate from the I<msg> extraCerts field may be used 44*a7148ab3SEnji Cooperas a trust anchor for the path verification of an 'acceptable' cert if it can be 45b077aed3SPierre Proncheryused also to validate the issued certificate returned in the IP message. This is 46b077aed3SPierre Proncheryaccording to TS 33.310 [Network Domain Security (NDS); Authentication Framework 47b077aed3SPierre Pronchery(AF)] document specified by the The 3rd Generation Partnership Project (3GPP). 48*a7148ab3SEnji CooperNote that using this option is dangerous as the certificate obtained this way 49*a7148ab3SEnji Cooperhas not been authenticated (at least not at CMP level). 50*a7148ab3SEnji CooperTaking it over as a trust anchor implements trust-on-first-use (TOFU). 51b077aed3SPierre Pronchery 52b077aed3SPierre ProncheryAny cert that has been found as described above is cached and tried first when 53b077aed3SPierre Proncheryvalidating the signatures of subsequent messages in the same transaction. 54b077aed3SPierre Pronchery 55b077aed3SPierre ProncheryOSSL_CMP_validate_cert_path() attempts to validate the given certificate and its 56b077aed3SPierre Proncherypath using the given store of trusted certs (possibly including CRLs and a cert 57b077aed3SPierre Proncheryverification callback) and non-trusted intermediate certs from the I<ctx>. 58b077aed3SPierre Pronchery 59b077aed3SPierre Pronchery=head1 NOTES 60b077aed3SPierre Pronchery 61b077aed3SPierre ProncheryCMP is defined in RFC 4210 (and CRMF in RFC 4211). 62b077aed3SPierre Pronchery 63b077aed3SPierre Pronchery=head1 RETURN VALUES 64b077aed3SPierre Pronchery 65b077aed3SPierre ProncheryOSSL_CMP_validate_msg() and OSSL_CMP_validate_cert_path() 66b077aed3SPierre Proncheryreturn 1 on success, 0 on error or validation failed. 67b077aed3SPierre Pronchery 68b077aed3SPierre Pronchery=head1 SEE ALSO 69b077aed3SPierre Pronchery 70b077aed3SPierre ProncheryL<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_exec_certreq(3)>, 71b077aed3SPierre ProncheryL<OSSL_CMP_CTX_set1_secretValue(3)>, L<OSSL_CMP_CTX_set1_srvCert(3)>, 72b077aed3SPierre ProncheryL<OSSL_CMP_CTX_set1_untrusted(3)>, L<OSSL_CMP_CTX_set0_trustedStore(3)> 73b077aed3SPierre Pronchery 74b077aed3SPierre Pronchery=head1 HISTORY 75b077aed3SPierre Pronchery 76b077aed3SPierre ProncheryThe OpenSSL CMP support was added in OpenSSL 3.0. 77b077aed3SPierre Pronchery 78b077aed3SPierre Pronchery=head1 COPYRIGHT 79b077aed3SPierre Pronchery 80*a7148ab3SEnji CooperCopyright 2007-2024 The OpenSSL Project Authors. All Rights Reserved. 81b077aed3SPierre Pronchery 82b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 83b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 84b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 85b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 86b077aed3SPierre Pronchery 87b077aed3SPierre Pronchery=cut 88