Latest update.

doc/man3/OSSL_CMP_validate_msg.pod

@@ -0,0 +1,86 @@
+=pod
+
+=head1 NAME
+
+OSSL_CMP_validate_msg,
+OSSL_CMP_validate_cert_path
+- functions for verifying CMP message protection
+
+=head1 SYNOPSIS
+
+ #include <openssl/cmp.h>
+ int OSSL_CMP_validate_msg(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
+ int OSSL_CMP_validate_cert_path(const OSSL_CMP_CTX *ctx,
+                                 X509_STORE *trusted_store, X509 *cert);
+
+=head1 DESCRIPTION
+
+This is the API for validating the protection of CMP messages,
+which includes validating CMP message sender certificates and their paths
+while optionally checking the revocation status of the certificates(s).
+
+OSSL_CMP_validate_msg() validates the protection of the given C<msg>
+using either password-based mac (PBM) or a signature algorithm.
+
+In case of signature algorithm, the certificate to use for the signature check
+is preferably the one provided by a call to L<OSSL_CMP_CTX_set1_srvCert(3)>.
+If no such sender cert has been pinned then candidate sender certificates are
+taken from the list of certificates received in the C<msg> extraCerts, then any
+certificates provided before via L<OSSL_CMP_CTX_set1_untrusted_certs(3)>, and
+then all trusted certificates provided via L<OSSL_CMP_CTX_set0_trustedStore(3)>,
+where a candidate is acceptable only if has not expired, its subject DN matches
+the C<msg> sender DN (as far as present), and its subject key identifier
+is present and matches the senderKID (as far as the latter present).
+Each acceptable cert is tried in the given order to see if the message
+signature check succeeds and the cert and its path can be verified
+using any trust store set via L<OSSL_CMP_CTX_set0_trustedStore(3)>.
+
+If the option OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR was set by calling
+L<OSSL_CMP_CTX_set_option(3)>, for an Initialization Response (IP) message
+any self-issued certificate from the C<msg> extraCerts field may also be used
+as trust anchor for the path verification of an acceptable cert if it can be
+used also to validate the issued certificate returned in the IP message. This is
+according to TS 33.310 [Network Domain Security (NDS); Authentication Framework
+(AF)] document specified by the The 3rd Generation Partnership Project (3GPP).
+
+Any cert that has been found as described above is cached and tried first when
+validating the signatures of subsequent messages in the same transaction.
+
+After successful validation of PBM-based protection of a certificate response
+the certificates in the caPubs field (if any) are added to the trusted
+certificates provided via L<OSSL_CMP_CTX_set0_trustedStore(3)>, such that
+they are available for validating subsequent messages in the same context.
+Those could apply to any Polling Response (pollRep), error, or PKI Confirmation
+(PKIConf) messages following in the same or future transactions.
+
+OSSL_CMP_validate_cert_path() attempts to validate the given certificate and its
+path using the given store of trusted certs (possibly including CRLs and a cert
+verification callback) and non-trusted intermediate certs from the B<ctx>.
+
+=head1 NOTES
+
+CMP is defined in RFC 4210 (and CRMF in RFC 4211).
+
+=head1 RETURN VALUES
+
+OSSL_CMP_validate_msg() and OSSL_CMP_validate_cert_path()
+return 1 on success, 0 on error or validation failed.
+
+=head1 SEE ALSO
+
+L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_exec_IR_ses(3)>
+
+=head1 HISTORY
+
+The OpenSSL CMP support was added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut