doc/man3/OSSL_CMP_SRV_CTX_new.pod

   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
 118 OSSL_CMP_SRV_CTX_init() sets in the given I<srv_ctx> a custom server context
 119 pointer as well as callback functions performing the specific processing of CMP
 120 certificate requests, revocation requests, certificate confirmation requests,
 121 general messages, error messages, and poll requests.
 122 All arguments except I<srv_ctx> may be NULL.
 123 If a callback for some message type is not given this means that the respective
 124 type of CMP message is not supported by the server.
 125
 126 OSSL_CMP_SRV_CTX_init_trans() sets in I<srv_ctx> the optional callback
 127 functions for initiating delayed delivery and cleaning up a transaction.
 128 If the <delay> function is NULL then delivery of responses is never delayed.
 129 Otherwise I<delay> takes a custom server context and a request message as input.
 130 It must return 1 if delivery of the respective response shall be delayed,
 131 0 if not, and -1 on error.
 132 If the <clean> function is NULL then no specific cleanup is performed.
 133 Otherwise I<clean> takes a custom server context and a transaction ID pointer
 134 as input, where the pointer is NULL in case a new transaction is being started
 135 and otherwise provides the ID of the transaction being terminated.
 136 The <clean> function should reset the respective portions of the state
 137 and free related memory.
 138 It must return 1 on success and 0 on error.
 139
 140 OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns the B<OSSL_CMP_CTX> from the I<srv_ctx>.
 141
 142 OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context from
 143 I<srv_ctx> that has been set using OSSL_CMP_SRV_CTX_init().
 144
 145 OSSL_CMP_SRV_CTX_set_send_unprotected_errors() enables sending error messages
 146 and other forms of negative responses unprotected.
 147
 148 OSSL_CMP_SRV_CTX_set_accept_unprotected() enables acceptance of requests
 149 without protection of with invalid protection.
 150
 151 OSSL_CMP_SRV_CTX_set_accept_raverified() enables acceptance of ir/cr/kur
 152 messages with POPO 'RAVerified'.
 153
 154 OSSL_CMP_SRV_CTX_set_grant_implicit_confirm() enables granting implicit
 155 confirmation of newly enrolled certificates if requested.
 156
 157 =head1 NOTES
 158
 159 CMP is defined in RFC 4210 (and CRMF in RFC 4211).
 160
 161 So far the CMP server implementation is limited to one request per CMP message
 162 (and consequently to at most one response component per CMP message).
 163
 164 =head1 RETURN VALUES
 165
 166 OSSL_CMP_SRV_CTX_new() returns a B<OSSL_CMP_SRV_CTX> structure on success,
 167 NULL on error.
 168
 169 OSSL_CMP_SRV_CTX_free() does not return a value.
 170
 171 OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns a B<OSSL_CMP_CTX> structure on success,
 172 NULL on error.
 173
 174 OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context
 175 that has been set using OSSL_CMP_SRV_CTX_init().
 176
 177 All other functions return 1 on success, 0 on error.
 178
 179 =head1 HISTORY
 180
 181 The OpenSSL CMP support was added in OpenSSL 3.0.
 182
 183 OSSL_CMP_SRV_CTX_init_trans()
 184 supporting delayed delivery of all types of response messages
 185 was added in OpenSSL 3.3.
 186
 187 =head1 COPYRIGHT
 188
 189 Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved.
 190
 191 Licensed under the Apache License 2.0 (the "License").  You may not use
 192 this file except in compliance with the License.  You can obtain a copy
 193 in the file LICENSE in the source distribution or at
 194 L<https://www.openssl.org/source/license.html>.
 195
 196 =cut