1=pod
2
3=head1 NAME
4
5ossl_cmp_certreq_new,
6ossl_cmp_certrep_new,
7ossl_cmp_rr_new,
8ossl_cmp_rp_new,
9ossl_cmp_certConf_new,
10ossl_cmp_pkiconf_new,
11ossl_cmp_pollReq_new,
12ossl_cmp_pollRep_new,
13ossl_cmp_genm_new,
14ossl_cmp_genp_new,
15ossl_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 fail_info,
34                                     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
46This is the internal API for creating various CMP PKIMESSAGES.
47All functions are based on L<ossl_cmp_msg_create(3)>.
48The allocate a new message, fill it with the relevant data derived from
49the given B<OSSL_CMP_CTX>, and create the applicable protection.
50
51ossl_cmp_certreq_new() creates a PKIMessage for requesting a certificate,
52which can be either of IR/CR/KUR/P10CR, depending on the given I<bodytype>.
53The CRMF message to use may be given explicitly via a non-NULL I<crm> argument,
54otherwise it is created from the information in the I<ctx>.
55
56Available 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
70ossl_cmp_certrep_new() creates a PKIMessage for certificate response,
71which can be either of IP/CP/KUP, depending on the given I<bodytype>,
72with the given I<certReqId> and I<si> values and optionally with I<cert>,
73I<chain>, and I<caPubs>. The I<cert>, I<chain>, and I<caPubs> arguments
74are not consumed if present but their internal reference counter is increased.
75The I<encryption_recip> is currently unsupported.
76The function does not protect the message if the B<status> value in I<si>
77is B<rejected> and I<unprotectedErrors> is nonzero.
78
79Available 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
91The 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
119ossl_cmp_rr_new() creates a Revocation Request message from the
120information set via OSSL_CMP_CTX_set1_oldClCert().
121
122ossl_cmp_rp_new() creates a Revocation Response message with I<si> and I<cid>.
123It does not protect the message if the B<status> value in I<si> is B<rejected>
124and I<unprotectedErrors> is nonzero.
125
126ossl_cmp_certConf_new() creates a Certificate Confirmation message for the last
127received certificate. PKIStatus defaults to B<accepted> if the I<fail_info> bit
128field is 0. Else it is taken as the failInfo of the PKIStatusInfo, PKIStatus is
129set to B<rejected>, and I<text> is copied to statusString unless it is NULL.
130
131ossl_cmp_pkiconf_new() creates a PKI Confirmation message.
132
133ossl_cmp_pollReq_new() creates a Polling Request message with certReqId set to
134I<crid>.
135
136ossl_cmp_pollRep_new() creates a Polling Response message with certReqId set to
137I<crid> and pollAfter to I<poll_after>.
138
139ossl_cmp_genm_new() creates a new General Message with an empty ITAV stack.
140
141ossl_cmp_genp_new() creates a new General Response with an empty ITAV stack.
142
143ossl_cmp_error_new() creates a new Error Message with the given contents
144I<si>, I<errorCode>, and optional I<details>.
145If I<errorCode> is positive and in the range of an OpenSSL error code,
146the library and reason strings are included in the B<errorDetails> field.
147If given, the I<details> are added to the contents of the B<errorDetails> field.
148The function does not protect the message if I<unprotectedErrors> is nonzero.
149
150=head1 NOTES
151
152CMP is specified in RFC 4210 (and CRMF in RFC 4211).
153
154=head1 RETURN VALUES
155
156All of the functions return a new OSSL_CMP_MSG structure containing
157the generated message on success, or NULL on error.
158
159=head1 SEE ALSO
160
161L<ossl_cmp_msg_create(3)>,
162L<OSSL_CMP_CTX_new(3)>, L<ERR_load_strings(3)>
163
164=head1 HISTORY
165
166The OpenSSL CMP support was added in OpenSSL 3.0.
167
168=head1 COPYRIGHT
169
170Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved.
171
172Licensed under the Apache License 2.0 (the "License").  You may not use
173this file except in compliance with the License.  You can obtain a copy
174in the file LICENSE in the source distribution or at
175L<https://www.openssl.org/source/license.html>.
176
177=cut
178