| 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 I<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 I<msg> extraCerts, then any
|
|---|
| 29 | certificates provided before via L<OSSL_CMP_CTX_set1_untrusted(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 I<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 I<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 | 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
|
|---|
| 51 | verification callback) and non-trusted intermediate certs from the I<ctx>.
|
|---|
| 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 |
|
|---|
| 64 | L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_exec_certreq(3)>
|
|---|
| 65 |
|
|---|
| 66 | =head1 HISTORY
|
|---|
| 67 |
|
|---|
| 68 | The OpenSSL CMP support was added in OpenSSL 3.0.
|
|---|
| 69 |
|
|---|
| 70 | =head1 COPYRIGHT
|
|---|
| 71 |
|
|---|
| 72 | Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 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
|
|---|
