Debian Codegraph @

upstream/debian-unstable/man3/OSSL_CMP_validate_msg.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL_CMP_VALIDATE_MSG 3SSL"
58 .TH OSSL_CMP_VALIDATE_MSG 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OSSL_CMP_validate_msg,
65 OSSL_CMP_validate_cert_path
66 \&\- functions for verifying CMP message protection
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 4
70 \& #include <openssl/cmp.h>
71 \& int OSSL_CMP_validate_msg(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg);
72 \& int OSSL_CMP_validate_cert_path(const OSSL_CMP_CTX *ctx,
73 \& X509_STORE *trusted_store, X509 *cert);
74 .Ve
75 .SH DESCRIPTION
76 .IX Header "DESCRIPTION"
77 This is the API for validating the protection of CMP messages,
78 which includes validating CMP message sender certificates and their paths
79 while optionally checking the revocation status of the certificates(s).
80 .PP
81 \&\fBOSSL_CMP_validate_msg()\fR validates the protection of the given \fImsg\fR,
82 which must be signature-based or using password-based MAC (PBM).
83 In the former case a suitable trust anchor must be given in the CMP context
84 \&\fIctx\fR, and in the latter case the matching secret must have been set there
85 using \fBOSSL_CMP_CTX_set1_secretValue\fR\|(3).
86 .PP
87 In case of signature algorithm, the certificate to use for the signature check
88 is preferably the one provided by a call to \fBOSSL_CMP_CTX_set1_srvCert\fR\|(3).
89 If no such sender cert has been pinned then candidate sender certificates are
90 taken from the list of certificates received in the \fImsg\fR extraCerts, then any
91 certificates provided before via \fBOSSL_CMP_CTX_set1_untrusted\fR\|(3), and
92 then all trusted certificates provided via \fBOSSL_CMP_CTX_set0_trusted\fR\|(3).
93 A candidate certificate is acceptable only if it is currently valid
94 (or the trust store contains a verification callback that overrides the verdict
95 that the certificate is expired or not yet valid), its subject DN matches
96 the \fImsg\fR sender DN (as far as present), and its subject key identifier
97 is present and matches the senderKID (as far as the latter is present).
98 Each acceptable cert is tried in the given order to see if the message
99 signature check succeeds and the cert and its path can be verified
100 using any trust store set via \fBOSSL_CMP_CTX_set0_trusted\fR\|(3).
101 .PP
102 If the option OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR was set by calling
103 \&\fBOSSL_CMP_CTX_set_option\fR\|(3), for an Initialization Response (IP) message
104 any self-issued certificate from the \fImsg\fR extraCerts field may be used
105 as a trust anchor for the path verification of an 'acceptable' cert if it can be
106 used also to validate the issued certificate returned in the IP message. This is
107 according to TS 33.310 [Network Domain Security (NDS); Authentication Framework
108 (AF)] document specified by The 3rd Generation Partnership Project (3GPP).
109 Note that using this option is dangerous as the certificate obtained this way
110 has not been authenticated (at least not at CMP level).
111 Taking it over as a trust anchor implements trust-on-first-use (TOFU).
112 .PP
113 Any cert that has been found as described above is cached and tried first when
114 validating the signatures of subsequent messages in the same transaction.
115 .PP
116 \&\fBOSSL_CMP_validate_cert_path()\fR attempts to validate the given certificate and its
117 path using the given store of trusted certs (possibly including CRLs and a cert
118 verification callback) and non-trusted intermediate certs from the \fIctx\fR.
119 .SH NOTES
120 .IX Header "NOTES"
121 CMP is defined in RFC 9810.
122 .SH "RETURN VALUES"
123 .IX Header "RETURN VALUES"
124 \&\fBOSSL_CMP_validate_msg()\fR and \fBOSSL_CMP_validate_cert_path()\fR
125 return 1 on success, 0 on error or validation failed.
126 .SH "SEE ALSO"
127 .IX Header "SEE ALSO"
128 \&\fBOSSL_CMP_CTX_new\fR\|(3), \fBOSSL_CMP_exec_certreq\fR\|(3),
129 \&\fBOSSL_CMP_CTX_set1_secretValue\fR\|(3), \fBOSSL_CMP_CTX_set1_srvCert\fR\|(3),
130 \&\fBOSSL_CMP_CTX_set1_untrusted\fR\|(3), \fBOSSL_CMP_CTX_set0_trusted\fR\|(3)
131 .SH HISTORY
132 .IX Header "HISTORY"
133 The OpenSSL CMP support was added in OpenSSL 3.0.
134 .SH COPYRIGHT
135 .IX Header "COPYRIGHT"
136 Copyright 2007\-2025 The OpenSSL Project Authors. All Rights Reserved.
137 .PP
138 Licensed under the Apache License 2.0 (the "License"). You may not use
139 this file except in compliance with the License. You can obtain a copy
140 in the file LICENSE in the source distribution or at
141 <https://www.openssl.org/source/license.html>.