xref: /freebsd/secure/lib/libcrypto/man/man3/OSSL_CMP_validate_msg.3 (revision 5ca8e32633c4ffbbcd6762e5888b6a4ba0708c6c)
Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)

Standard preamble:
========================================================================
..
..
.. Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.

If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.

Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================

Title "OSSL_CMP_VALIDATE_MSG 3ossl"
OSSL_CMP_VALIDATE_MSG 3ossl "2023-09-19" "3.0.11" "OpenSSL"
For nroff, turn off justification. Always turn off hyphenation; it makes
way too many mistakes in technical documents.
"NAME"
OSSL_CMP_validate_msg, OSSL_CMP_validate_cert_path \- functions for verifying CMP message protection
"SYNOPSIS"
Header "SYNOPSIS" .Vb 4 #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); .Ve
"DESCRIPTION"
Header "DESCRIPTION" This is the \s-1API\s0 for validating the protection of \s-1CMP\s0 messages, which includes validating \s-1CMP\s0 message sender certificates and their paths while optionally checking the revocation status of the certificates(s).

\fBOSSL_CMP_validate_msg() validates the protection of the given msg, which must be signature-based or using password-based \s-1MAC\s0 (\s-1PBM\s0). In the former case a suitable trust anchor must be given in the \s-1CMP\s0 context \fIctx, and in the latter case the matching secret must have been set there using OSSL_CMP_CTX_set1_secretValue\|(3).

In case of signature algorithm, the certificate to use for the signature check is preferably the one provided by a call to 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 msg extraCerts, then any certificates provided before via OSSL_CMP_CTX_set1_untrusted\|(3), and then all trusted certificates provided via OSSL_CMP_CTX_set0_trustedStore\|(3), where a candidate is acceptable only if has not expired, its subject \s-1DN\s0 matches the msg sender \s-1DN\s0 (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 OSSL_CMP_CTX_set0_trustedStore\|(3).

If the option \s-1OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR\s0 was set by calling \fBOSSL_CMP_CTX_set_option\|(3), for an Initialization Response (\s-1IP\s0) message any self-issued certificate from the 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 \s-1IP\s0 message. This is according to \s-1TS 33.310\s0 [Network Domain Security (\s-1NDS\s0); Authentication Framework (\s-1AF\s0)] 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.

\fBOSSL_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 ctx.

"NOTES"
Header "NOTES" \s-1CMP\s0 is defined in \s-1RFC 4210\s0 (and \s-1CRMF\s0 in \s-1RFC 4211\s0).
"RETURN VALUES"
Header "RETURN VALUES" \fBOSSL_CMP_validate_msg() and OSSL_CMP_validate_cert_path() return 1 on success, 0 on error or validation failed.
"SEE ALSO"
Header "SEE ALSO" \fBOSSL_CMP_CTX_new\|(3), OSSL_CMP_exec_certreq\|(3), \fBOSSL_CMP_CTX_set1_secretValue\|(3), OSSL_CMP_CTX_set1_srvCert\|(3), \fBOSSL_CMP_CTX_set1_untrusted\|(3), OSSL_CMP_CTX_set0_trustedStore\|(3)
"HISTORY"
Header "HISTORY" The OpenSSL \s-1CMP\s0 support was added in OpenSSL 3.0.
"COPYRIGHT"
Header "COPYRIGHT" Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.