doc/internal/man3/ossl_cmp_certreq_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ossl_cmp_certreq_new,
   6 ossl_cmp_certrep_new,
   7 ossl_cmp_rr_new,
   8 ossl_cmp_rp_new,
   9 ossl_cmp_certConf_new,
  10 ossl_cmp_pkiconf_new,
  11 ossl_cmp_pollReq_new,
  12 ossl_cmp_pollRep_new,
  13 ossl_cmp_genm_new,
  14 ossl_cmp_genp_new,
  15 ossl_cmp_error_new
  16 - functions for generating CMP messages
  17
  18 =head1 SYNOPSIS
  19
  20  #include "cmp_local.h"
  21
  22  OSSL_ossl_cmp_MSG *ossl_cmp_certreq_new(OSSL_CMP_CTX *ctx, int bodytype,
  23                                          const OSSL_CRMF_MSG *crm);
  24  OSSL_CMP_MSG *ossl_cmp_certrep_new(OSSL_CMP_CTX *ctx, int bodytype,
  25                                     int certReqId, const OSSL_CMP_PKISI *si,
  26                                     X509 *cert, const X509 *encryption_recip,
  27                                     STACK_OF(X509) *chain, STACK_OF(X509) *caPubs,
  28                                     int unprotectedErrors);
  29  OSSL_CMP_MSG *ossl_cmp_rr_new(OSSL_CMP_CTX *ctx);
  30  OSSL_CMP_MSG *ossl_cmp_rp_new(OSSL_CMP_CTX *ctx, const OSSL_CMP_PKISI *si,
  31                                const OSSL_CRMF_CERTID *cid,
  32                                int unprotectedErrors);
  33  OSSL_CMP_MSG *ossl_cmp_certConf_new(OSSL_CMP_CTX *ctx, int certReqId,
  34                                      int fail_info, const char *text);
  35  OSSL_CMP_MSG *ossl_cmp_pkiconf_new(OSSL_CMP_CTX *ctx);
  36  OSSL_CMP_MSG *ossl_cmp_pollReq_new(OSSL_CMP_CTX *ctx, int crid);
  37  OSSL_CMP_MSG *ossl_cmp_pollRep_new(OSSL_CMP_CTX *ctx, int crid, int poll_after);
  38  OSSL_CMP_MSG *ossl_cmp_genm_new(OSSL_CMP_CTX *ctx);
  39  OSSL_CMP_MSG *ossl_cmp_genp_new(OSSL_CMP_CTX *ctx);
  40  OSSL_CMP_MSG *ossl_cmp_error_new(OSSL_CMP_CTX *ctx, const OSSL_CMP_PKISI *si,
  41                                   int64_t errorCode, const char *details,
  42                                   int unprotected);
  43
  44 =head1 DESCRIPTION
  45
  46 This is the internal API for creating various CMP PKIMESSAGES.
  47 All functions are based on L<ossl_cmp_msg_create(3)>.
  48 The allocate a new message, fill it with the relevant data derived from
  49 the given B<OSSL_CMP_CTX>, and create the applicable protection.
  50
  51 ossl_cmp_certreq_new() creates a PKIMessage for requesting a certificate,
  52 which can be either of IR/CR/KUR/P10CR, depending on the given I<bodytype>.
  53 The CRMF message to use may be given explicitly via a non-NULL I<crm> argument,
  54 otherwise it is created from the information in the I<ctx>.
  55
  56 Available CMP certificate request PKIMessage I<bodytype>s are:
  57
  58 =over 4
  59
  60 =item * B<OSSL_CMP_PKIBODY_IR>    - Initialization Request
  61
  62 =item * B<OSSL_CMP_PKIBODY_CR>    - Certification Request
  63
  64 =item * B<OSSL_CMP_PKIBODY_P10CR> - PKCS#10 Certification Request
  65
  66 =item * B<OSSL_CMP_PKIBODY_KUR>   - Key Update Request
  67
  68 =back
  69
  70 ossl_cmp_certrep_new() creates a PKIMessage for certificate response,
  71 which can be either of IP/CP/KUP, depending on the given I<bodytype>,
  72 with the given I<certReqId> and I<si> values and optionally with I<cert>,
  73 I<chain>, and I<caPubs>. The I<cert>, I<chain>, and I<caPubs> arguments
  74 are not consumed if present but their internal reference counter is increased.
  75 The I<encryption_recip> is currently unsupported.
  76 The function does not protect the message if the B<status> value in I<si>
  77 is B<rejected> and I<unprotectedErrors> is nonzero.
  78
  79 Available CMP certificate response PKIMessage I<bodytype>s are:
  80
  81 =over 4
  82
  83 =item * B<OSSL_CMP_PKIBODY_IP>    - Initialization Response
  84
  85 =item * B<OSSL_CMP_PKIBODY_CP>    - Certification Response
  86
  87 =item * B<OSSL_CMP_PKIBODY_KUP>   - Key Update Response
  88
  89 =back
  90
  91 The list of all CMP PKIMessage I<bodytype>s is:
  92
  93  #define OSSL_CMP_PKIBODY_IR        0
  94  #define OSSL_CMP_PKIBODY_IP        1
  95  #define OSSL_CMP_PKIBODY_CR        2
  96  #define OSSL_CMP_PKIBODY_CP        3
  97  #define OSSL_CMP_PKIBODY_P10CR     4
  98  #define OSSL_CMP_PKIBODY_POPDECC   5
  99  #define OSSL_CMP_PKIBODY_POPDECR   6
 100  #define OSSL_CMP_PKIBODY_KRR       9
 101  #define OSSL_CMP_PKIBODY_KRP      10
 102  #define OSSL_CMP_PKIBODY_RR       11
 103  #define OSSL_CMP_PKIBODY_RP       12
 104  #define OSSL_CMP_PKIBODY_CCR      13
 105  #define OSSL_CMP_PKIBODY_CCP      14
 106  #define OSSL_CMP_PKIBODY_CKUANN   15
 107  #define OSSL_CMP_PKIBODY_CANN     16
 108  #define OSSL_CMP_PKIBODY_RANN     17
 109  #define OSSL_CMP_PKIBODY_CRLANN   18
 110  #define OSSL_CMP_PKIBODY_PKICONF  19
 111  #define OSSL_CMP_PKIBODY_NESTED   20
 112  #define OSSL_CMP_PKIBODY_GENM     21
 113  #define OSSL_CMP_PKIBODY_GENP     22
 114  #define OSSL_CMP_PKIBODY_ERROR    23
 115  #define OSSL_CMP_PKIBODY_CERTCONF 24
 116  #define OSSL_CMP_PKIBODY_POLLREQ  25
 117  #define OSSL_CMP_PKIBODY_POLLREP  26
 118
 119 ossl_cmp_rr_new() creates a Revocation Request message from the
 120 information set via OSSL_CMP_CTX_set1_oldClCert().
 121
 122 ossl_cmp_rp_new() creates a Revocation Response message with I<si> and I<cid>.
 123 It does not protect the message if the B<status> value in I<si> is B<rejected>
 124 and I<unprotectedErrors> is nonzero.
 125
 126 ossl_cmp_certConf_new() creates a Certificate Confirmation message for the last
 127 received certificate with the given I<certReqId>.
 128 The PKIStatus defaults to B<accepted> if the I<fail_info> bit field is 0.
 129 Otherwise it is taken as the failInfo of the PKIStatusInfo, PKIStatus is
 130 set to B<rejected>, and I<text> is copied to statusString unless it is NULL.
 131
 132 ossl_cmp_pkiconf_new() creates a PKI Confirmation message.
 133
 134 ossl_cmp_pollReq_new() creates a Polling Request message with certReqId set to
 135 I<crid>.
 136
 137 ossl_cmp_pollRep_new() creates a Polling Response message with certReqId set to
 138 I<crid> and pollAfter to I<poll_after>.
 139
 140 ossl_cmp_genm_new() creates a new General Message with an empty ITAV stack.
 141
 142 ossl_cmp_genp_new() creates a new General Response with an empty ITAV stack.
 143
 144 ossl_cmp_error_new() creates a new Error Message with the given contents
 145 I<si>, I<errorCode>, and optional I<details>.
 146 If I<errorCode> is positive and in the range of an OpenSSL error code,
 147 the library and reason strings are included in the B<errorDetails> field.
 148 If given, the I<details> are added to the contents of the B<errorDetails> field.
 149 The function does not protect the message if I<unprotectedErrors> is nonzero.
 150
 151 =head1 NOTES
 152
 153 CMP is specified in RFC 4210 (and CRMF in RFC 4211).
 154
 155 =head1 RETURN VALUES
 156
 157 All of the functions return a new OSSL_CMP_MSG structure containing
 158 the generated message on success, or NULL on error.
 159
 160 =head1 SEE ALSO
 161
 162 L<ossl_cmp_msg_create(3)>,
 163 L<OSSL_CMP_CTX_new(3)>, L<ERR_load_strings(3)>
 164
 165 =head1 HISTORY
 166
 167 The OpenSSL CMP support was added in OpenSSL 3.0.
 168
 169 =head1 COPYRIGHT
 170
 171 Copyright 2007-2023 The OpenSSL Project Authors. All Rights Reserved.
 172
 173 Licensed under the Apache License 2.0 (the "License").  You may not use
 174 this file except in compliance with the License.  You can obtain a copy
 175 in the file LICENSE in the source distribution or at
 176 L<https://www.openssl.org/source/license.html>.
 177
 178 =cut