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_CTX_get0_cmp_ctx,
  17 OSSL_CMP_SRV_CTX_get0_custom_ctx,
  18 OSSL_CMP_SRV_CTX_set_send_unprotected_errors,
  19 OSSL_CMP_SRV_CTX_set_accept_unprotected,
  20 OSSL_CMP_SRV_CTX_set_accept_raverified,
  21 OSSL_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(void);
  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
  87 OSSL_CMP_SRV_process_request() implements the generic aspects of a CMP server.
  88 It does the typical generic checks on the given request message, calls
  89 the respective callback function (if present) for more specific processing,
  90 and then assembles a result message, which may be a CMP error message.
  91
  92 OSSL_CMP_CTX_server_perform() is an interface to
  93 B<OSSL_CMP_SRV_process_request()> that can be used by a CMP client
  94 in the same way as B<OSSL_CMP_MSG_http_perform()>.
  95 The B<OSSL_CMP_SRV_CTX> must be set as B<transfer_cb_arg> of B<client_ctx>.
  96
  97 OSSL_CMP_SRV_CTX_new() creates and initializes an OSSL_CMP_SRV_CTX structure
  98 and returns a pointer to it on success, NULL on error.
  99
 100 OSSL_CMP_SRV_CTX_free() deletes the given B<srv_ctx>.
 101
 102 OSSL_CMP_SRV_CTX_init() sets in the given B<srv_ctx> a custom server context
 103 pointer as well as callback functions performing the specific processing of CMP
 104 certificate requests, revocation requests, certificate confirmation requests,
 105 general messages, error messages, and poll requests.
 106 All arguments except B<srv_ctx> may be NULL.
 107 If a callback for some message type is not given this means that the respective
 108 type of CMP message is not supported by the server.
 109
 110 OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns the B<OSSL_CMP_CTX> from the B<srv_ctx>.
 111
 112 OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context from
 113 B<srv_ctx> that has been set using B<OSSL_CMP_SRV_CTX_init>.
 114
 115 OSSL_CMP_SRV_CTX_set_send_unprotected_errors() enables sending error messages
 116 and other forms of negative responses unprotected.
 117
 118 OSSL_CMP_SRV_CTX_set_accept_unprotected() enables acceptance of requests
 119 without protection of with invalid protection.
 120
 121 OSSL_CMP_SRV_CTX_set_accept_raverified() enables acceptance of ir/cr/kur
 122 messages with POPO 'RAVerified'.
 123
 124 OSSL_CMP_SRV_CTX_set_grant_implicit_confirm() enables granting implicit
 125 confirmation of newly enrolled certificates if requested.
 126
 127 =head1 NOTES
 128
 129 CMP is defined in RFC 4210 (and CRMF in RFC 4211).
 130
 131 =head1 RETURN VALUES
 132
 133 OSSL_CMP_SRV_CTX_new() returns a B<OSSL_CMP_SRV_CTX> structure on success,
 134 NULL on error.
 135
 136 OSSL_CMP_SRV_CTX_free() does not return a value.
 137
 138 OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns a B<OSSL_CMP_CTX> structure on success,
 139 NULL on error.
 140
 141 OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context
 142 that has been set using B<OSSL_CMP_SRV_CTX_init>.
 143
 144 All other functions return 1 on success, 0 on error.
 145
 146 =head1 HISTORY
 147
 148 The OpenSSL CMP support was added in OpenSSL 3.0.
 149
 150 =head1 COPYRIGHT
 151
 152 Copyright 2007-2019 The OpenSSL Project Authors. All Rights Reserved.
 153
 154 Licensed under the Apache License 2.0 (the "License").  You may not use
 155 this file except in compliance with the License.  You can obtain a copy
 156 in the file LICENSE in the source distribution or at
 157 L<https://www.openssl.org/source/license.html>.
 158
 159 =cut