| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | OSSL_CMP_SRV_process_request,
|
|---|
| 6 | OSSL_CMP_CTX_server_perform,
|
|---|
| 7 | OSSL_CMP_SRV_CTX_new,
|
|---|
| 8 | OSSL_CMP_SRV_CTX_free,
|
|---|
| 9 | OSSL_CMP_SRV_cert_request_cb_t,
|
|---|
| 10 | OSSL_CMP_SRV_rr_cb_t,
|
|---|
| 11 | OSSL_CMP_SRV_certConf_cb_t,
|
|---|
| 12 | OSSL_CMP_SRV_genm_cb_t,
|
|---|
| 13 | OSSL_CMP_SRV_error_cb_t,
|
|---|
| 14 | OSSL_CMP_SRV_pollReq_cb_t,
|
|---|
| 15 | OSSL_CMP_SRV_CTX_init,
|
|---|
| 16 | OSSL_CMP_SRV_delayed_delivery_cb_t,
|
|---|
| 17 | OSSL_CMP_SRV_clean_transaction_cb_t,
|
|---|
| 18 | OSSL_CMP_SRV_CTX_init_trans,
|
|---|
| 19 | OSSL_CMP_SRV_CTX_get0_cmp_ctx,
|
|---|
| 20 | OSSL_CMP_SRV_CTX_get0_custom_ctx,
|
|---|
| 21 | OSSL_CMP_SRV_CTX_set_send_unprotected_errors,
|
|---|
| 22 | OSSL_CMP_SRV_CTX_set_accept_unprotected,
|
|---|
| 23 | OSSL_CMP_SRV_CTX_set_accept_raverified,
|
|---|
| 24 | OSSL_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 |
|
|---|
| 97 | OSSL_CMP_SRV_process_request() implements the generic aspects of a CMP server.
|
|---|
| 98 | Its arguments are the B<OSSL_CMP_SRV_CTX> I<srv_ctx> and the CMP request message
|
|---|
| 99 | I<req>. It does the typical generic checks on I<req>, calls
|
|---|
| 100 | the respective callback function (if present) for more specific processing,
|
|---|
| 101 | and then assembles a result message, which may be a CMP error message.
|
|---|
| 102 | If after return of the function the expression
|
|---|
| 103 | I<OSSL_CMP_CTX_get_status(OSSL_CMP_SRV_CTX_get0_cmp_ctx(srv_ctx))> yields -1
|
|---|
| 104 | then the function has closed the current transaction,
|
|---|
| 105 | which may be due to normal successful end of the transaction or due to an error.
|
|---|
| 106 |
|
|---|
| 107 | OSSL_CMP_CTX_server_perform() is an interface to
|
|---|
| 108 | OSSL_CMP_SRV_process_request() that can be used by a CMP client
|
|---|
| 109 | in the same way as L<OSSL_CMP_MSG_http_perform(3)>.
|
|---|
| 110 | The B<OSSL_CMP_SRV_CTX> must be set as I<transfer_cb_arg> of I<client_ctx>.
|
|---|
| 111 |
|
|---|
| 112 | OSSL_CMP_SRV_CTX_new() creates and initializes an B<OSSL_CMP_SRV_CTX> structure
|
|---|
| 113 | associated with the library context I<libctx> and property query string
|
|---|
| 114 | I<propq>, both of which may be NULL to select the defaults.
|
|---|
| 115 |
|
|---|
| 116 | OSSL_CMP_SRV_CTX_free() deletes the given I<srv_ctx>.
|
|---|
| 117 | If the argument is NULL, nothing is done.
|
|---|
| 118 |
|
|---|
| 119 | OSSL_CMP_SRV_CTX_init() sets in the given I<srv_ctx> a custom server context
|
|---|
| 120 | pointer as well as callback functions performing the specific processing of CMP
|
|---|
| 121 | certificate requests, revocation requests, certificate confirmation requests,
|
|---|
| 122 | general messages, error messages, and poll requests.
|
|---|
| 123 | All arguments except I<srv_ctx> may be NULL.
|
|---|
| 124 | If a callback for some message type is not given this means that the respective
|
|---|
| 125 | type of CMP message is not supported by the server.
|
|---|
| 126 |
|
|---|
| 127 | OSSL_CMP_SRV_CTX_init_trans() sets in I<srv_ctx> the optional callback
|
|---|
| 128 | functions for initiating delayed delivery and cleaning up a transaction.
|
|---|
| 129 | If the <delay> function is NULL then delivery of responses is never delayed.
|
|---|
| 130 | Otherwise I<delay> takes a custom server context and a request message as input.
|
|---|
| 131 | It must return 1 if delivery of the respective response shall be delayed,
|
|---|
| 132 | 0 if not, and -1 on error.
|
|---|
| 133 | If the <clean> function is NULL then no specific cleanup is performed.
|
|---|
| 134 | Otherwise I<clean> takes a custom server context and a transaction ID pointer
|
|---|
| 135 | as input, where the pointer is NULL in case a new transaction is being started
|
|---|
| 136 | and otherwise provides the ID of the transaction being terminated.
|
|---|
| 137 | The <clean> function should reset the respective portions of the state
|
|---|
| 138 | and free related memory.
|
|---|
| 139 | It must return 1 on success and 0 on error.
|
|---|
| 140 |
|
|---|
| 141 | OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns the B<OSSL_CMP_CTX> from the I<srv_ctx>.
|
|---|
| 142 |
|
|---|
| 143 | OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context from
|
|---|
| 144 | I<srv_ctx> that has been set using OSSL_CMP_SRV_CTX_init().
|
|---|
| 145 |
|
|---|
| 146 | OSSL_CMP_SRV_CTX_set_send_unprotected_errors() enables sending error messages
|
|---|
| 147 | and other forms of negative responses unprotected.
|
|---|
| 148 |
|
|---|
| 149 | OSSL_CMP_SRV_CTX_set_accept_unprotected() enables acceptance of requests
|
|---|
| 150 | without protection of with invalid protection.
|
|---|
| 151 |
|
|---|
| 152 | OSSL_CMP_SRV_CTX_set_accept_raverified() enables acceptance of ir/cr/kur
|
|---|
| 153 | messages with POPO 'RAVerified'.
|
|---|
| 154 |
|
|---|
| 155 | OSSL_CMP_SRV_CTX_set_grant_implicit_confirm() enables granting implicit
|
|---|
| 156 | confirmation of newly enrolled certificates if requested.
|
|---|
| 157 |
|
|---|
| 158 | =head1 NOTES
|
|---|
| 159 |
|
|---|
| 160 | CMP is defined in RFC 4210 (and CRMF in RFC 4211).
|
|---|
| 161 |
|
|---|
| 162 | So 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 |
|
|---|
| 167 | OSSL_CMP_SRV_CTX_new() returns a B<OSSL_CMP_SRV_CTX> structure on success,
|
|---|
| 168 | NULL on error.
|
|---|
| 169 |
|
|---|
| 170 | OSSL_CMP_SRV_CTX_free() does not return a value.
|
|---|
| 171 |
|
|---|
| 172 | OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns a B<OSSL_CMP_CTX> structure on success,
|
|---|
| 173 | NULL on error.
|
|---|
| 174 |
|
|---|
| 175 | OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context
|
|---|
| 176 | that has been set using OSSL_CMP_SRV_CTX_init().
|
|---|
| 177 |
|
|---|
| 178 | All other functions return 1 on success, 0 on error.
|
|---|
| 179 |
|
|---|
| 180 | =head1 HISTORY
|
|---|
| 181 |
|
|---|
| 182 | The OpenSSL CMP support was added in OpenSSL 3.0.
|
|---|
| 183 |
|
|---|
| 184 | OSSL_CMP_SRV_CTX_init_trans()
|
|---|
| 185 | supporting delayed delivery of all types of response messages
|
|---|
| 186 | was added in OpenSSL 3.3.
|
|---|
| 187 |
|
|---|
| 188 | =head1 COPYRIGHT
|
|---|
| 189 |
|
|---|
| 190 | Copyright 2007-2024 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 191 |
|
|---|
| 192 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 193 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 194 | in the file LICENSE in the source distribution or at
|
|---|
| 195 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 196 |
|
|---|
| 197 | =cut
|
|---|
