Debian Codegraph @

upstream/debian-unstable/man3/OSSL_CMP_SRV_CTX_new.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_SRV_CTX_NEW 3SSL"
58 .TH OSSL_CMP_SRV_CTX_NEW 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_SRV_process_request,
65 OSSL_CMP_CTX_server_perform,
66 OSSL_CMP_SRV_CTX_new,
67 OSSL_CMP_SRV_CTX_free,
68 OSSL_CMP_SRV_cert_request_cb_t,
69 OSSL_CMP_SRV_rr_cb_t,
70 OSSL_CMP_SRV_certConf_cb_t,
71 OSSL_CMP_SRV_genm_cb_t,
72 OSSL_CMP_SRV_error_cb_t,
73 OSSL_CMP_SRV_pollReq_cb_t,
74 OSSL_CMP_SRV_CTX_init,
75 OSSL_CMP_SRV_delayed_delivery_cb_t,
76 OSSL_CMP_SRV_clean_transaction_cb_t,
77 OSSL_CMP_SRV_CTX_init_trans,
78 OSSL_CMP_SRV_CTX_get0_cmp_ctx,
79 OSSL_CMP_SRV_CTX_get0_custom_ctx,
80 OSSL_CMP_SRV_CTX_set_send_unprotected_errors,
81 OSSL_CMP_SRV_CTX_set_accept_unprotected,
82 OSSL_CMP_SRV_CTX_set_accept_raverified,
83 OSSL_CMP_SRV_CTX_set_grant_implicit_confirm
84 \&\- generic functions to set up and control a CMP server
85 .SH SYNOPSIS
86 .IX Header "SYNOPSIS"
87 .Vb 1
88 \& #include <openssl/cmp.h>
89 \&
90 \& OSSL_CMP_MSG *OSSL_CMP_SRV_process_request(OSSL_CMP_SRV_CTX *srv_ctx,
91 \& const OSSL_CMP_MSG *req);
92 \& OSSL_CMP_MSG *OSSL_CMP_CTX_server_perform(OSSL_CMP_CTX *client_ctx,
93 \& const OSSL_CMP_MSG *req);
94 \& OSSL_CMP_SRV_CTX *OSSL_CMP_SRV_CTX_new(OSSL_LIB_CTX *libctx, const char *propq);
95 \& void OSSL_CMP_SRV_CTX_free(OSSL_CMP_SRV_CTX *srv_ctx);
96 \&
97 \& typedef OSSL_CMP_PKISI *(*OSSL_CMP_SRV_cert_request_cb_t)(
98 \& OSSL_CMP_SRV_CTX *srv_ctx,
99 \& const OSSL_CMP_MSG *req,
100 \& int certReqId,
101 \& const OSSL_CRMF_MSG *crm,
102 \& const X509_REQ *p10cr,
103 \& X509 **certOut,
104 \& STACK_OF(X509) **chainOut,
105 \& STACK_OF(X509) **caPubs);
106 \& typedef OSSL_CMP_PKISI *(*OSSL_CMP_SRV_rr_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
107 \& const OSSL_CMP_MSG *req,
108 \& const X509_NAME *issuer,
109 \& const ASN1_INTEGER *serial);
110 \& typedef int (*OSSL_CMP_SRV_genm_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
111 \& const OSSL_CMP_MSG *req,
112 \& STACK_OF(OSSL_CMP_ITAV) *in,
113 \& STACK_OF(OSSL_CMP_ITAV) **out);
114 \& typedef void (*OSSL_CMP_SRV_error_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
115 \& const OSSL_CMP_MSG *req,
116 \& const OSSL_CMP_PKISI *statusInfo,
117 \& const ASN1_INTEGER *errorCode,
118 \& const OSSL_CMP_PKIFREETEXT *errorDetails);
119 \& typedef int (*OSSL_CMP_SRV_certConf_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
120 \& const OSSL_CMP_MSG *req,
121 \& int certReqId,
122 \& const ASN1_OCTET_STRING *certHash,
123 \& const OSSL_CMP_PKISI *si);
124 \& typedef int (*OSSL_CMP_SRV_pollReq_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
125 \& const OSSL_CMP_MSG *req,
126 \& int certReqId,
127 \& OSSL_CMP_MSG **certReq,
128 \& int64_t *check_after);
129 \& int OSSL_CMP_SRV_CTX_init(OSSL_CMP_SRV_CTX *srv_ctx, void *custom_ctx,
130 \& OSSL_CMP_SRV_cert_request_cb_t process_cert_request,
131 \& OSSL_CMP_SRV_rr_cb_t process_rr,
132 \& OSSL_CMP_SRV_genm_cb_t process_genm,
133 \& OSSL_CMP_SRV_error_cb_t process_error,
134 \& OSSL_CMP_SRV_certConf_cb_t process_certConf,
135 \& OSSL_CMP_SRV_pollReq_cb_t process_pollReq);
136 \& typedef int (*OSSL_CMP_SRV_delayed_delivery_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
137 \& const OSSL_CMP_MSG *req);
138 \& typedef int (*OSSL_CMP_SRV_clean_transaction_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
139 \& const ASN1_OCTET_STRING *id);
140 \& int OSSL_CMP_SRV_CTX_init_trans(OSSL_CMP_SRV_CTX *srv_ctx,
141 \& OSSL_CMP_SRV_delayed_delivery_cb_t delay,
142 \& OSSL_CMP_SRV_clean_transaction_cb_t clean);
143 \&
144 \& OSSL_CMP_CTX *OSSL_CMP_SRV_CTX_get0_cmp_ctx(const OSSL_CMP_SRV_CTX *srv_ctx);
145 \& void *OSSL_CMP_SRV_CTX_get0_custom_ctx(const OSSL_CMP_SRV_CTX *srv_ctx);
146 \&
147 \& int OSSL_CMP_SRV_CTX_set_send_unprotected_errors(OSSL_CMP_SRV_CTX *srv_ctx,
148 \& int val);
149 \& int OSSL_CMP_SRV_CTX_set_accept_unprotected(OSSL_CMP_SRV_CTX *srv_ctx, int val);
150 \& int OSSL_CMP_SRV_CTX_set_accept_raverified(OSSL_CMP_SRV_CTX *srv_ctx, int val);
151 \& int OSSL_CMP_SRV_CTX_set_grant_implicit_confirm(OSSL_CMP_SRV_CTX *srv_ctx,
152 \& int val);
153 .Ve
154 .SH DESCRIPTION
155 .IX Header "DESCRIPTION"
156 \&\fBOSSL_CMP_SRV_process_request()\fR implements the generic aspects of a CMP server.
157 Its arguments are the \fBOSSL_CMP_SRV_CTX\fR \fIsrv_ctx\fR and the CMP request message
158 \&\fIreq\fR. It does the typical generic checks on \fIreq\fR, calls
159 the respective callback function (if present) for more specific processing,
160 and then assembles a result message, which may be a CMP error message.
161 If after return of the function the expression
162 \&\fIOSSL_CMP_CTX_get_status(OSSL_CMP_SRV_CTX_get0_cmp_ctx(srv_ctx))\fR yields \-1
163 then the function has closed the current transaction,
164 which may be due to normal successful end of the transaction or due to an error.
165 .PP
166 \&\fBOSSL_CMP_CTX_server_perform()\fR is an interface to
167 \&\fBOSSL_CMP_SRV_process_request()\fR that can be used by a CMP client
168 in the same way as \fBOSSL_CMP_MSG_http_perform\fR\|(3).
169 In particular, the first parameter \fIclient_ctx\fR is the \fBOSSL_CMP_CTX\fR of the client.
170 The \fBOSSL_CMP_SRV_CTX\fR must be set as \fItransfer_cb_arg\fR of \fIclient_ctx\fR.
171 .PP
172 \&\fBOSSL_CMP_SRV_CTX_new()\fR creates and initializes an \fBOSSL_CMP_SRV_CTX\fR structure
173 associated with the library context \fIlibctx\fR and property query string
174 \&\fIpropq\fR, both of which may be NULL to select the defaults.
175 .PP
176 \&\fBOSSL_CMP_SRV_CTX_free()\fR deletes the given \fIsrv_ctx\fR.
177 If the argument is NULL, nothing is done.
178 .PP
179 \&\fBOSSL_CMP_SRV_CTX_init()\fR sets in the given \fIsrv_ctx\fR a custom server context
180 pointer as well as callback functions performing the specific processing of CMP
181 certificate requests, revocation requests, certificate confirmation requests,
182 general messages, error messages, and poll requests.
183 All arguments except \fIsrv_ctx\fR may be NULL.
184 If a callback for some message type is not given this means that the respective
185 type of CMP message is not supported by the server.
186 .PP
187 \&\fBOSSL_CMP_SRV_CTX_init_trans()\fR sets in \fIsrv_ctx\fR the optional callback
188 functions for initiating delayed delivery and cleaning up a transaction.
189 If the <delay> function is NULL then delivery of responses is never delayed.
190 Otherwise \fIdelay\fR takes a custom server context and a request message as input.
191 It must return 1 if delivery of the respective response shall be delayed,
192 0 if not, and \-1 on error.
193 If the <clean> function is NULL then no specific cleanup is performed.
194 Otherwise \fIclean\fR takes a custom server context and a transaction ID pointer
195 as input, where the pointer is NULL in case a new transaction is being started
196 and otherwise provides the ID of the transaction being terminated.
197 The <clean> function should reset the respective portions of the state
198 and free related memory.
199 It must return 1 on success and 0 on error.
200 .PP
201 \&\fBOSSL_CMP_SRV_CTX_get0_cmp_ctx()\fR returns the \fBOSSL_CMP_CTX\fR from the \fIsrv_ctx\fR.
202 .PP
203 \&\fBOSSL_CMP_SRV_CTX_get0_custom_ctx()\fR returns the custom server context from
204 \&\fIsrv_ctx\fR that has been set using \fBOSSL_CMP_SRV_CTX_init()\fR.
205 .PP
206 \&\fBOSSL_CMP_SRV_CTX_set_send_unprotected_errors()\fR enables sending error messages
207 and other forms of negative responses unprotected.
208 .PP
209 \&\fBOSSL_CMP_SRV_CTX_set_accept_unprotected()\fR enables acceptance of requests
210 without protection of with invalid protection.
211 .PP
212 \&\fBOSSL_CMP_SRV_CTX_set_accept_raverified()\fR enables acceptance of ir/cr/kur
213 messages with POPO 'RAVerified'.
214 .PP
215 \&\fBOSSL_CMP_SRV_CTX_set_grant_implicit_confirm()\fR enables granting implicit
216 confirmation of newly enrolled certificates if requested.
217 .SH NOTES
218 .IX Header "NOTES"
219 CMP is defined in RFC 9810 (and CRMF in RFC 4211).
220 .PP
221 So far the CMP server implementation is limited to one request per CMP message
222 (and consequently to at most one response component per CMP message).
223 .SH "RETURN VALUES"
224 .IX Header "RETURN VALUES"
225 \&\fBOSSL_CMP_SRV_CTX_new()\fR returns a \fBOSSL_CMP_SRV_CTX\fR structure on success,
226 NULL on error.
227 .PP
228 \&\fBOSSL_CMP_SRV_CTX_free()\fR does not return a value.
229 .PP
230 \&\fBOSSL_CMP_SRV_CTX_get0_cmp_ctx()\fR returns a \fBOSSL_CMP_CTX\fR structure on success,
231 NULL on error.
232 .PP
233 \&\fBOSSL_CMP_SRV_CTX_get0_custom_ctx()\fR returns the custom server context
234 that has been set using \fBOSSL_CMP_SRV_CTX_init()\fR.
235 .PP
236 All other functions return 1 on success, 0 on error.
237 .SH HISTORY
238 .IX Header "HISTORY"
239 The OpenSSL CMP support was added in OpenSSL 3.0.
240 .PP
241 \&\fBOSSL_CMP_SRV_CTX_init_trans()\fR
242 supporting delayed delivery of all types of response messages
243 was added in OpenSSL 3.3.
244 .SH COPYRIGHT
245 .IX Header "COPYRIGHT"
246 Copyright 2007\-2024 The OpenSSL Project Authors. All Rights Reserved.
247 .PP
248 Licensed under the Apache License 2.0 (the "License"). You may not use
249 this file except in compliance with the License. You can obtain a copy
250 in the file LICENSE in the source distribution or at
251 <https://www.openssl.org/source/license.html>.