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