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