]>
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 | ||
22 | OSSL_CMP_validate_msg() validates the protection of the given C<msg> | |
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 | |
28 | taken from the list of certificates received in the C<msg> extraCerts, then any | |
29 | certificates provided before via L<OSSL_CMP_CTX_set1_untrusted_certs(3)>, and | |
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 | |
32 | the C<msg> sender DN (as far as present), and its subject key identifier | |
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 | |
40 | any self-issued certificate from the C<msg> extraCerts field may also be used | |
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 | ||
49 | After successful validation of PBM-based protection of a certificate response | |
50 | the certificates in the caPubs field (if any) are added to the trusted | |
51 | certificates provided via L<OSSL_CMP_CTX_set0_trustedStore(3)>, such that | |
52 | they are available for validating subsequent messages in the same context. | |
53 | Those could apply to any Polling Response (pollRep), error, or PKI Confirmation | |
54 | (PKIConf) messages following in the same or future transactions. | |
55 | ||
56 | OSSL_CMP_validate_cert_path() attempts to validate the given certificate and its | |
57 | path using the given store of trusted certs (possibly including CRLs and a cert | |
58 | verification callback) and non-trusted intermediate certs from the B<ctx>. | |
59 | ||
60 | =head1 NOTES | |
61 | ||
62 | CMP is defined in RFC 4210 (and CRMF in RFC 4211). | |
63 | ||
64 | =head1 RETURN VALUES | |
65 | ||
66 | OSSL_CMP_validate_msg() and OSSL_CMP_validate_cert_path() | |
67 | return 1 on success, 0 on error or validation failed. | |
68 | ||
69 | =head1 SEE ALSO | |
70 | ||
71 | L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_exec_IR_ses(3)> | |
72 | ||
73 | =head1 HISTORY | |
74 | ||
75 | The OpenSSL CMP support was added in OpenSSL 3.0. | |
76 | ||
77 | =head1 COPYRIGHT | |
78 | ||
33388b44 | 79 | Copyright 2007-2020 The OpenSSL Project Authors. All Rights Reserved. |
31b28ad9 DDO |
80 | |
81 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
82 | this file except in compliance with the License. You can obtain a copy | |
83 | in the file LICENSE in the source distribution or at | |
84 | L<https://www.openssl.org/source/license.html>. | |
85 | ||
86 | =cut |