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