1=pod
2
3=head1 NAME
4
5OSSL_CMP_SRV_process_request,
6OSSL_CMP_CTX_server_perform,
7OSSL_CMP_SRV_CTX_new,
8OSSL_CMP_SRV_CTX_free,
9OSSL_CMP_SRV_cert_request_cb_t,
10OSSL_CMP_SRV_rr_cb_t,
11OSSL_CMP_SRV_certConf_cb_t,
12OSSL_CMP_SRV_genm_cb_t,
13OSSL_CMP_SRV_error_cb_t,
14OSSL_CMP_SRV_pollReq_cb_t,
15OSSL_CMP_SRV_CTX_init,
16OSSL_CMP_SRV_CTX_get0_cmp_ctx,
17OSSL_CMP_SRV_CTX_get0_custom_ctx,
18OSSL_CMP_SRV_CTX_set_send_unprotected_errors,
19OSSL_CMP_SRV_CTX_set_accept_unprotected,
20OSSL_CMP_SRV_CTX_set_accept_raverified,
21OSSL_CMP_SRV_CTX_set_grant_implicit_confirm
22- generic functions to set up and control a CMP server
23
24=head1 SYNOPSIS
25
26 #include <openssl/cmp.h>
27
28 OSSL_CMP_MSG *OSSL_CMP_SRV_process_request(OSSL_CMP_SRV_CTX *srv_ctx,
29                                            const OSSL_CMP_MSG *req);
30 OSSL_CMP_MSG *OSSL_CMP_CTX_server_perform(OSSL_CMP_CTX *client_ctx,
31                                           const OSSL_CMP_MSG *req);
32 OSSL_CMP_SRV_CTX *OSSL_CMP_SRV_CTX_new(OSSL_LIB_CTX *libctx, const char *propq);
33 void OSSL_CMP_SRV_CTX_free(OSSL_CMP_SRV_CTX *srv_ctx);
34
35 typedef OSSL_CMP_PKISI *(*OSSL_CMP_SRV_cert_request_cb_t)(
36                                                 OSSL_CMP_SRV_CTX *srv_ctx,
37                                                 const OSSL_CMP_MSG *req,
38                                                 int certReqId,
39                                                 const OSSL_CRMF_MSG *crm,
40                                                 const X509_REQ *p10cr,
41                                                 X509 **certOut,
42                                                 STACK_OF(X509) **chainOut,
43                                                 STACK_OF(X509) **caPubs);
44 typedef OSSL_CMP_PKISI *(*OSSL_CMP_SRV_rr_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
45                                                 const OSSL_CMP_MSG *req,
46                                                 const X509_NAME *issuer,
47                                                 const ASN1_INTEGER *serial);
48 typedef int (*OSSL_CMP_SRV_genm_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
49                                       const OSSL_CMP_MSG *req,
50                                       STACK_OF(OSSL_CMP_ITAV) *in,
51                                       STACK_OF(OSSL_CMP_ITAV) **out);
52 typedef void (*OSSL_CMP_SRV_error_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
53                                         const OSSL_CMP_MSG *req,
54                                         const OSSL_CMP_PKISI *statusInfo,
55                                         const ASN1_INTEGER *errorCode,
56                                         const OSSL_CMP_PKIFREETEXT *errorDetails);
57 typedef int (*OSSL_CMP_SRV_certConf_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
58                                           const OSSL_CMP_MSG *req,
59                                           int certReqId,
60                                           const ASN1_OCTET_STRING *certHash,
61                                           const OSSL_CMP_PKISI *si);
62 typedef int (*OSSL_CMP_SRV_pollReq_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
63                                          const OSSL_CMP_MSG *req,
64                                          int certReqId,
65                                          OSSL_CMP_MSG **certReq,
66                                          int64_t *check_after);
67 int OSSL_CMP_SRV_CTX_init(OSSL_CMP_SRV_CTX *srv_ctx, void *custom_ctx,
68                           OSSL_CMP_SRV_cert_request_cb_t process_cert_request,
69                           OSSL_CMP_SRV_rr_cb_t process_rr,
70                           OSSL_CMP_SRV_genm_cb_t process_genm,
71                           OSSL_CMP_SRV_error_cb_t process_error,
72                           OSSL_CMP_SRV_certConf_cb_t process_certConf,
73                           OSSL_CMP_SRV_pollReq_cb_t process_pollReq);
74
75 OSSL_CMP_CTX *OSSL_CMP_SRV_CTX_get0_cmp_ctx(const OSSL_CMP_SRV_CTX *srv_ctx);
76 void *OSSL_CMP_SRV_CTX_get0_custom_ctx(const OSSL_CMP_SRV_CTX *srv_ctx);
77
78 int OSSL_CMP_SRV_CTX_set_send_unprotected_errors(OSSL_CMP_SRV_CTX *srv_ctx,
79                                                  int val);
80 int OSSL_CMP_SRV_CTX_set_accept_unprotected(OSSL_CMP_SRV_CTX *srv_ctx, int val);
81 int OSSL_CMP_SRV_CTX_set_accept_raverified(OSSL_CMP_SRV_CTX *srv_ctx, int val);
82 int OSSL_CMP_SRV_CTX_set_grant_implicit_confirm(OSSL_CMP_SRV_CTX *srv_ctx,
83                                                 int val);
84
85=head1 DESCRIPTION
86
87OSSL_CMP_SRV_process_request() implements the generic aspects of a CMP server.
88Its arguments are the B<OSSL_CMP_SRV_CTX> I<srv_ctx> and the CMP request message
89I<req>. It does the typical generic checks on I<req>, calls
90the respective callback function (if present) for more specific processing,
91and then assembles a result message, which may be a CMP error message.
92If after return of the function the expression
93I<OSSL_CMP_CTX_get_status(OSSL_CMP_SRV_CTX_get0_cmp_ctx(srv_ctx))> yields -1
94then the function has closed the current transaction,
95which may be due to normal successful end of the transaction or due to an error.
96
97OSSL_CMP_CTX_server_perform() is an interface to
98OSSL_CMP_SRV_process_request() that can be used by a CMP client
99in the same way as L<OSSL_CMP_MSG_http_perform(3)>.
100The B<OSSL_CMP_SRV_CTX> must be set as I<transfer_cb_arg> of I<client_ctx>.
101
102OSSL_CMP_SRV_CTX_new() creates and initializes an B<OSSL_CMP_SRV_CTX> structure
103associated with the library context I<libctx> and property query string
104I<propq>, both of which may be NULL to select the defaults.
105
106OSSL_CMP_SRV_CTX_free() deletes the given I<srv_ctx>.
107If the argument is NULL, nothing is done.
108
109OSSL_CMP_SRV_CTX_init() sets in the given I<srv_ctx> a custom server context
110pointer as well as callback functions performing the specific processing of CMP
111certificate requests, revocation requests, certificate confirmation requests,
112general messages, error messages, and poll requests.
113All arguments except I<srv_ctx> may be NULL.
114If a callback for some message type is not given this means that the respective
115type of CMP message is not supported by the server.
116
117OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns the B<OSSL_CMP_CTX> from the I<srv_ctx>.
118
119OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context from
120I<srv_ctx> that has been set using OSSL_CMP_SRV_CTX_init().
121
122OSSL_CMP_SRV_CTX_set_send_unprotected_errors() enables sending error messages
123and other forms of negative responses unprotected.
124
125OSSL_CMP_SRV_CTX_set_accept_unprotected() enables acceptance of requests
126without protection of with invalid protection.
127
128OSSL_CMP_SRV_CTX_set_accept_raverified() enables acceptance of ir/cr/kur
129messages with POPO 'RAVerified'.
130
131OSSL_CMP_SRV_CTX_set_grant_implicit_confirm() enables granting implicit
132confirmation of newly enrolled certificates if requested.
133
134=head1 NOTES
135
136CMP is defined in RFC 4210 (and CRMF in RFC 4211).
137
138So far the CMP server implementation is limited to one request per CMP message
139(and consequently to at most one response component per CMP message).
140
141=head1 RETURN VALUES
142
143OSSL_CMP_SRV_CTX_new() returns a B<OSSL_CMP_SRV_CTX> structure on success,
144NULL on error.
145
146OSSL_CMP_SRV_CTX_free() does not return a value.
147
148OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns a B<OSSL_CMP_CTX> structure on success,
149NULL on error.
150
151OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context
152that has been set using OSSL_CMP_SRV_CTX_init().
153
154All other functions return 1 on success, 0 on error.
155
156=head1 HISTORY
157
158The OpenSSL CMP support was added in OpenSSL 3.0.
159
160=head1 COPYRIGHT
161
162Copyright 2007-2024 The OpenSSL Project Authors. All Rights Reserved.
163
164Licensed under the Apache License 2.0 (the "License").  You may not use
165this file except in compliance with the License.  You can obtain a copy
166in the file LICENSE in the source distribution or at
167L<https://www.openssl.org/source/license.html>.
168
169=cut
170