1=pod
2
3=head1 NAME
4
5OSSL_CMP_ITAV_new_caCerts,
6OSSL_CMP_ITAV_get0_caCerts,
7OSSL_CMP_ITAV_new_rootCaCert,
8OSSL_CMP_ITAV_get0_rootCaCert,
9OSSL_CMP_ITAV_new_rootCaKeyUpdate,
10OSSL_CMP_ITAV_get0_rootCaKeyUpdate,
11OSSL_CMP_CRLSTATUS_new1,
12OSSL_CMP_CRLSTATUS_create,
13OSSL_CMP_CRLSTATUS_get0,
14OSSL_CMP_ITAV_new0_crlStatusList,
15OSSL_CMP_ITAV_get0_crlStatusList,
16OSSL_CMP_ITAV_new_crls,
17OSSL_CMP_ITAV_get0_crls,
18OSSL_CMP_ITAV_new0_certReqTemplate,
19OSSL_CMP_ITAV_get1_certReqTemplate
20- CMP utility functions for handling specific genm and genp messages
21
22=head1 SYNOPSIS
23
24 #include <openssl/cmp.h>
25
26 OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_caCerts(const STACK_OF(X509) *caCerts);
27 int OSSL_CMP_ITAV_get0_caCerts(const OSSL_CMP_ITAV *itav, STACK_OF(X509) **out);
28
29 OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_rootCaCert(const X509 *rootCaCert);
30 int OSSL_CMP_ITAV_get0_rootCaCert(const OSSL_CMP_ITAV *itav, X509 **out);
31 OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_rootCaKeyUpdate(const X509 *newWithNew,
32                                                  const X509 *newWithOld,
33                                                  const X509 *oldWithNew);
34 int OSSL_CMP_ITAV_get0_rootCaKeyUpdate(const OSSL_CMP_ITAV *itav,
35                                        X509 **newWithNew,
36                                        X509 **newWithOld,
37                                        X509 **oldWithNew);
38
39 OSSL_CMP_CRLSTATUS *OSSL_CMP_CRLSTATUS_new1(const DIST_POINT_NAME *dpn,
40                                             const GENERAL_NAMES *issuer,
41                                             const ASN1_TIME *thisUpdate);
42 OSSL_CMP_CRLSTATUS *OSSL_CMP_CRLSTATUS_create(const X509_CRL *crl,
43                                               const X509 *cert, int only_DN);
44 int OSSL_CMP_CRLSTATUS_get0(const OSSL_CMP_CRLSTATUS *crlstatus,
45                             DIST_POINT_NAME **dpn, GENERAL_NAMES **issuer,
46                             ASN1_TIME **thisUpdate);
47 OSSL_CMP_ITAV
48 *OSSL_CMP_ITAV_new0_crlStatusList(STACK_OF(OSSL_CMP_CRLSTATUS) *crlStatusList);
49 int OSSL_CMP_ITAV_get0_crlStatusList(const OSSL_CMP_ITAV *itav,
50                                      STACK_OF(OSSL_CMP_CRLSTATUS) **out);
51 OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_crls(const X509_CRL *crl);
52 int OSSL_CMP_ITAV_get0_crls(const OSSL_CMP_ITAV *itav, STACK_OF(X509_CRL) **out);
53 OSSL_CMP_ITAV
54 *OSSL_CMP_ITAV_new0_certReqTemplate(OSSL_CRMF_CERTTEMPLATE *certTemplate,
55                                     OSSL_CMP_ATAVS *keySpec);
56 int OSSL_CMP_ITAV_get1_certReqTemplate(const OSSL_CMP_ITAV *itav,
57                                        OSSL_CRMF_CERTTEMPLATE **certTemplate,
58                                        OSSL_CMP_ATAVS **keySpec);
59
60=head1 DESCRIPTION
61
62ITAV is short for InfoTypeAndValue.
63
64OSSL_CMP_ITAV_new_caCerts() creates an B<OSSL_CMP_ITAV> structure of type
65B<caCerts> and fills it with a copy of the provided list of certificates.
66The I<caCerts> argument may be NULL or contain any number of certificates.
67
68OSSL_CMP_ITAV_get0_caCerts() requires that I<itav> has type B<caCerts>.
69It assigns NULL to I<*out> if there are no CA certificates in I<itav>, otherwise
70the internal pointer of type B<STACK_OF(X509)> with the certificates present.
71
72OSSL_CMP_ITAV_new_rootCaCert() creates a new B<OSSL_CMP_ITAV> structure
73of type B<rootCaCert> that includes the optionally given certificate.
74
75OSSL_CMP_ITAV_get0_rootCaCert() requires that I<itav> has type B<rootCaCert>.
76It assigns NULL to I<*out> if no certificate is included in I<itav>, otherwise
77the internal pointer to the certificate contained in the infoValue field.
78
79OSSL_CMP_ITAV_new_rootCaKeyUpdate() creates a new B<OSSL_CMP_ITAV> structure
80of type B<rootCaKeyUpdate> that includes an RootCaKeyUpdateContent structure
81with the optional I<newWithNew>, I<newWithOld>, and I<oldWithNew> certificates.
82An RootCaKeyUpdateContent structure is included only if I<newWithNew>
83is not NULL.
84
85OSSL_CMP_ITAV_get0_rootCaKeyUpdate() requires that I<itav> has infoType
86B<rootCaKeyUpdate>.
87If an update of a root CA certificate is included,
88it assigns to I<*newWithNew> the internal pointer
89to the certificate contained in the newWithNew infoValue sub-field of I<itav>.
90If I<newWithOld> is not NULL, it assigns to I<*newWithOld> the internal pointer
91to the certificate contained in the newWithOld infoValue sub-field of I<itav>.
92If I<oldWithNew> is not NULL, it assigns to I<*oldWithNew> the internal pointer
93to the certificate contained in the oldWithNew infoValue sub-field of I<itav>.
94Each of these pointers will be set to NULL if no root CA certificate update
95is present or the respective sub-field is not included.
96
97OSSL_CMP_CRLSTATUS_new1() allocates a new B<OSSL_CMP_CRLSTATUS> structure
98that contains either a copy of the distribution point name I<dpn>
99or a copy of the certificate issuer I<issuer>, while giving both is an error.
100If given, a copy of the CRL issuance time I<thisUpdate> is also included.
101
102OSSL_CMP_CRLSTATUS_create() is a high-level variant of OSSL_CMP_CRLSTATUS_new1().
103It fills the thisUpdate field with a copy of the thisUpdate field of I<crl> if present.
104It fills the CRLSource field with a copy of the first data item found using the I<crl>
105and/or I<cert> parameters as follows.
106Any available distribution point name is preferred over issuer names.
107Data from I<cert>, if present, is preferred over data from I<crl>.
108If no distribution point names are available,
109candidate issuer names are taken from following sources, as far as present:
110
111OSSL_CMP_ITAV_new0_certReqTemplate() creates an B<OSSL_CMP_ITAV> structure
112of type B<certReqTemplate>.
113If I<certTemplate> is NULL then also I<keySpec> must be NULL,
114and the resulting ITAV can be used in a B<genm> message to obtain the
115requirements a PKI has on the certificate template used to request certificates,
116or in a B<genp> message stating that there are no such requirements.
117Otherwise the resulting ITAV includes a CertReqTemplateValue structure
118with I<certTemplate> of type B<OSSL_CRMF_CERTTEMPLATE> and an optional list
119of key specifications I<keySpec>, each being of type B<OSSL_CMP_ATAV>, and
120the resulting ATAV can be used in a B<genp> message to provide requirements.
121
122OSSL_CMP_ITAV_get1_certReqTemplate()
123requires that I<itav> has type B<certReqTemplate>.
124If assigns NULL to I<*certTemplate> if no B<OSSL_CRMF_CERTTEMPLATE> structure
125with a certificate template value is in I<itav>,
126otherwise a copy of the certTemplate field value.
127If I<keySpec> is not NULL, it is assigned NULL
128if the structure is not present in I<itav> or the keySpec field is absent.
129Otherwise, the function checks that all elements of keySpec field are of type
130B<algId> or B<rsaKeyLen> and assigns to I<*keySpec> a copy of the keySpec field.
131
132=over 4
133
134=item the list of distribution points in the first cRLDistributionPoints
135extension of I<cert>,
136
137=item the issuer field of the authority key identifier of I<cert>,
138
139=item the issuer DN of I<cert>,
140
141=item the issuer field of the authority key identifier of I<crl>, and
142
143=item the issuer DN of I<crl>.
144
145=back
146
147If <only_DN> is set, a candidate issuer name of type B<GENERAL_NAMES> is
148accepted only if it contains exactly one general name of type directoryName.
149
150OSSL_CMP_CRLSTATUS_get0() reads the fields of I<crlstatus>
151and assigns them to I<*dpn>, I<*issuer>, and I<*thisUpdate>.
152I<*thisUpdate> is assigned only if the I<thisUpdate> argument is not NULL.
153Depending on the choice present, either I<*dpn> or I<*issuer> will be NULL.
154I<*thisUpdate> can also be NULL if the field is not present.
155
156OSSL_CMP_ITAV_new0_crlStatusList() creates a new B<OSSL_CMP_ITAV> structure of
157type B<crlStatusList> that includes the optionally given list of
158CRL status data, each of which is of type B<OSSL_CMP_CRLSTATUS>.
159
160OSSL_CMP_ITAV_get0_crlStatusList() on success assigns to I<*out> an internal
161pointer to the list of CRL status data in the infoValue field of I<itav>.
162The pointer may be NULL if no CRL status data is included.
163It is an error if the infoType of I<itav> is not B<crlStatusList>.
164
165OSSL_CMP_ITAV_new_crls() creates a new B<OSSL_CMP_ITAV> structure
166of type B<crls> including an empty list of CRLs if the I<crl> argument is NULL
167or including a singleton list a with copy of the provided CRL otherwise.
168
169OSSL_CMP_ITAV_get0_crls() on success assigns to I<*out> an internal pointer to
170the list of CRLs contained in the infoValue field of I<itav>.
171The pointer may be NULL if no CRL is included.
172It is an error if the infoType of I<itav> is not B<crls>.
173
174=head1 NOTES
175
176CMP is defined in RFC 4210.
177
178=head1 RETURN VALUES
179
180OSSL_CMP_ITAV_new_caCerts(), OSSL_CMP_ITAV_new_rootCaCert(),
181OSSL_CMP_ITAV_new_rootCaKeyUpdate(), OSSL_CMP_CRLSTATUS_new1(),
182OSSL_CMP_CRLSTATUS_create(), OSSL_CMP_ITAV_new0_crlStatusList(),
183OSSL_CMP_ITAV_new_crls() and OSSL_CMP_ITAV_new0_certReqTemplate()
184return a pointer to the new ITAV structure on success, or NULL on error.
185
186OSSL_CMP_ITAV_get0_caCerts(), OSSL_CMP_ITAV_get0_rootCaCert(),
187OSSL_CMP_ITAV_get0_rootCaKeyUpdate(), OSSL_CMP_CRLSTATUS_get0(),
188OSSL_CMP_ITAV_get0_crlStatusList(), OSSL_CMP_ITAV_get0_crls()
189and OSSL_CMP_ITAV_get1_certReqTemplate()
190return 1 on success, 0 on error.
191
192=head1 SEE ALSO
193
194L<OSSL_CMP_ITAV_create(3)> and L<OSSL_CMP_ITAV_get0_type(3)>
195
196=head1 HISTORY
197
198OSSL_CMP_ITAV_new_caCerts(), OSSL_CMP_ITAV_get0_caCerts(),
199OSSL_CMP_ITAV_new_rootCaCert(), OSSL_CMP_ITAV_get0_rootCaCert(),
200OSSL_CMP_ITAV_new_rootCaKeyUpdate(), and OSSL_CMP_ITAV_get0_rootCaKeyUpdate()
201were added in OpenSSL 3.2.
202
203OSSL_CMP_CRLSTATUS_new1(), OSSL_CMP_CRLSTATUS_create(),
204OSSL_CMP_CRLSTATUS_get0(), OSSL_CMP_ITAV_new0_crlStatusList(),
205OSSL_CMP_ITAV_get0_crlStatusList(), OSSL_CMP_ITAV_new_crls(),
206OSSL_CMP_ITAV_get0_crls(), OSSL_CMP_ITAV_new0_certReqTemplate()
207and OSSL_CMP_ITAV_get1_certReqTemplate() were added in OpenSSL 3.4.
208
209=head1 COPYRIGHT
210
211Copyright 2022-2024 The OpenSSL Project Authors. All Rights Reserved.
212
213Licensed under the Apache License 2.0 (the "License").  You may not use
214this file except in compliance with the License.  You can obtain a copy
215in the file LICENSE in the source distribution or at
216L<https://www.openssl.org/source/license.html>.
217
218=cut
219