1=pod
2
3=head1 NAME
4
5OSSL_CMP_validate_msg,
6OSSL_CMP_validate_cert_path
7- functions for verifying CMP message protection
8
9=head1 SYNOPSIS
10
11 #include <openssl/cmp.h>
12 int OSSL_CMP_validate_msg(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
13 int OSSL_CMP_validate_cert_path(const OSSL_CMP_CTX *ctx,
14                                 X509_STORE *trusted_store, X509 *cert);
15
16=head1 DESCRIPTION
17
18This is the API for validating the protection of CMP messages,
19which includes validating CMP message sender certificates and their paths
20while optionally checking the revocation status of the certificates(s).
21
22OSSL_CMP_validate_msg() validates the protection of the given I<msg>
23using either password-based mac (PBM) or a signature algorithm.
24
25In case of signature algorithm, the certificate to use for the signature check
26is preferably the one provided by a call to L<OSSL_CMP_CTX_set1_srvCert(3)>.
27If no such sender cert has been pinned then candidate sender certificates are
28taken from the list of certificates received in the I<msg> extraCerts, then any
29certificates provided before via L<OSSL_CMP_CTX_set1_untrusted(3)>, and
30then all trusted certificates provided via L<OSSL_CMP_CTX_set0_trusted(3)>,
31where a candidate is acceptable only if has not expired, its subject DN matches
32the I<msg> sender DN (as far as present), and its subject key identifier
33is present and matches the senderKID (as far as the latter present).
34Each acceptable cert is tried in the given order to see if the message
35signature check succeeds and the cert and its path can be verified
36using any trust store set via L<OSSL_CMP_CTX_set0_trusted(3)>.
37
38If the option OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR was set by calling
39L<OSSL_CMP_CTX_set_option(3)>, for an Initialization Response (IP) message
40any self-issued certificate from the I<msg> extraCerts field may also be used
41as trust anchor for the path verification of an acceptable cert if it can be
42used also to validate the issued certificate returned in the IP message. This is
43according to TS 33.310 [Network Domain Security (NDS); Authentication Framework
44(AF)] document specified by the The 3rd Generation Partnership Project (3GPP).
45
46Any cert that has been found as described above is cached and tried first when
47validating the signatures of subsequent messages in the same transaction.
48
49OSSL_CMP_validate_cert_path() attempts to validate the given certificate and its
50path using the given store of trusted certs (possibly including CRLs and a cert
51verification callback) and non-trusted intermediate certs from the I<ctx>.
52
53=head1 NOTES
54
55CMP is defined in RFC 4210 (and CRMF in RFC 4211).
56
57=head1 RETURN VALUES
58
59OSSL_CMP_validate_msg() and OSSL_CMP_validate_cert_path()
60return 1 on success, 0 on error or validation failed.
61
62=head1 SEE ALSO
63
64L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_exec_certreq(3)>
65
66=head1 HISTORY
67
68The OpenSSL CMP support was added in OpenSSL 3.0.
69
70=head1 COPYRIGHT
71
72Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved.
73
74Licensed under the Apache License 2.0 (the "License").  You may not use
75this file except in compliance with the License.  You can obtain a copy
76in the file LICENSE in the source distribution or at
77L<https://www.openssl.org/source/license.html>.
78
79=cut
80