OSSL_CMP_ITAV_NEW_CACERTS(3ossl)

📦

version 3.5.9 · 8 versions

3.5.9 · fedora 43, fedora 44 (latest)
3.5.9 · centos-stream 9
3.5.9 · centos-stream 10
3.5.9 · alpine 3.22
3.5.9 · alpine 3.23, alpine 3.24
3.5.8 · fedora 43
3.5.1 · fedora 43
3.5.5 · fedora 44

💖 OSSL_CMP_ITAV_NEW_CACERTS 💖

okay so bestie, welcome to the OpenSSL 3ossl manual page for all the CMP utility functions that handle specific genm and genp messages. it's giving "niche but essential", it's giving "iykyk", and we're gonna go through every single one of them together. grab a strawberry 🍓, we're doing this.

✨ NAME ✨

OSSL_CMP_ITAV_new_caCerts, OSSL_CMP_ITAV_get0_caCerts, OSSL_CMP_ITAV_new_rootCaCert, OSSL_CMP_ITAV_get0_rootCaCert, OSSL_CMP_ITAV_new_rootCaKeyUpdate, OSSL_CMP_ITAV_get0_rootCaKeyUpdate, OSSL_CMP_CRLSTATUS_new1, OSSL_CMP_CRLSTATUS_create, OSSL_CMP_CRLSTATUS_get0, OSSL_CMP_ITAV_new0_crlStatusList, OSSL_CMP_ITAV_get0_crlStatusList, OSSL_CMP_ITAV_new_crls, OSSL_CMP_ITAV_get0_crls, OSSL_CMP_ITAV_new0_certReqTemplate, OSSL_CMP_ITAV_get1_certReqTemplate — CMP utility functions for handling specific genm and genp messages 🦋

like. that's the whole roster. and yes, we're covering all fifteen. no skipping. periodt. 💅

🌸 SYNOPSIS 🌸

#include <openssl/cmp.h>

OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_caCerts(const STACK_OF(X509) *caCerts);
int OSSL_CMP_ITAV_get0_caCerts(const OSSL_CMP_ITAV *itav, STACK_OF(X509) **out);

OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_rootCaCert(const X509 *rootCaCert);
int OSSL_CMP_ITAV_get0_rootCaCert(const OSSL_CMP_ITAV *itav, X509 **out);
OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_rootCaKeyUpdate(const X509 *newWithNew,
                                                 const X509 *newWithOld,
                                                 const X509 *oldWithNew);
int OSSL_CMP_ITAV_get0_rootCaKeyUpdate(const OSSL_CMP_ITAV *itav,
                                       X509 **newWithNew,
                                       X509 **newWithOld,
                                       X509 **oldWithNew);

OSSL_CMP_CRLSTATUS *OSSL_CMP_CRLSTATUS_new1(const DIST_POINT_NAME *dpn,
                                            const GENERAL_NAMES *issuer,
                                            const ASN1_TIME *thisUpdate);
OSSL_CMP_CRLSTATUS *OSSL_CMP_CRLSTATUS_create(const X509_CRL *crl,
                                              const X509 *cert, int only_DN);
int OSSL_CMP_CRLSTATUS_get0(const OSSL_CMP_CRLSTATUS *crlstatus,
                            DIST_POINT_NAME **dpn, GENERAL_NAMES **issuer,
                            ASN1_TIME **thisUpdate);
OSSL_CMP_ITAV
*OSSL_CMP_ITAV_new0_crlStatusList(STACK_OF(OSSL_CMP_CRLSTATUS) *crlStatusList);
int OSSL_CMP_ITAV_get0_crlStatusList(const OSSL_CMP_ITAV *itav,
                                     STACK_OF(OSSL_CMP_CRLSTATUS) **out);
OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_crls(const X509_CRL *crl);
int OSSL_CMP_ITAV_get0_crls(const OSSL_CMP_ITAV *itav, STACK_OF(X509_CRL) **out);
OSSL_CMP_ITAV
*OSSL_CMP_ITAV_new0_certReqTemplate(OSSL_CRMF_CERTTEMPLATE *certTemplate,
                                    OSSL_CMP_ATAVS *keySpec);
int OSSL_CMP_ITAV_get1_certReqTemplate(const OSSL_CMP_ITAV *itav,
                                       OSSL_CRMF_CERTTEMPLATE **certTemplate,
                                       OSSL_CMP_ATAVS **keySpec);

look at all those signatures, they're literally so organized. 🎀

🌈 DESCRIPTION 🌈

okay first things first, the vocab lesson you didn't ask for but genuinely need:

ITAV is short for InfoTypeAndValue. that's it, that's the tea. ☕

OSSL_CMP_ITAV_new_caCerts() creates an OSSL_CMP_ITAV structure of type caCerts and fills it with a copy of the list of certificates you hand it. the caCerts argument may be NULL, or it may hold literally any number of certificates — zero, one, forty, whatever. no cap.

OSSL_CMP_ITAV_get0_caCerts() requires that itav has type caCerts. if there are no CA certificates in itav, it assigns NULL to *out; otherwise it hands you the internal pointer of type STACK_OF(X509) with the certificates that are present. ⭐

OSSL_CMP_ITAV_new_rootCaCert() creates a new OSSL_CMP_ITAV structure of type rootCaCert that includes the certificate you optionally pass in. optionally! the choice is yours bestie.

OSSL_CMP_ITAV_get0_rootCaCert() requires that itav has type rootCaCert. if no certificate is included in itav, it assigns NULL to *out; otherwise you get the internal pointer to the certificate sitting in the infoValue field. 💜

OSSL_CMP_ITAV_new_rootCaKeyUpdate() creates a new OSSL_CMP_ITAV structure of type rootCaKeyUpdate, and inside it goes an RootCaKeyUpdateContent structure carrying the optional newWithNew, newWithOld, and oldWithNew certificates. 🗝️

heads up: that RootCaKeyUpdateContent structure is included only if newWithNew is not NULL. no newWithNew, no structure. that's the rule.

OSSL_CMP_ITAV_get0_rootCaKeyUpdate() requires that itav has infoType rootCaKeyUpdate. if an update of a root CA certificate is included, it assigns to *newWithNew the internal pointer to the certificate contained in the newWithNew infoValue sub-field of itav. if newWithOld is not NULL, it assigns to *newWithOld the internal pointer to the certificate contained in the newWithOld infoValue sub-field of itav. if oldWithNew is not NULL, it assigns to *oldWithNew the internal pointer to the certificate contained in the oldWithNew infoValue sub-field of itav. and every one of those pointers gets set to NULL if there's no root CA certificate update present, or if the respective sub-field just isn't included. 🙈

OSSL_CMP_CRLSTATUS_new1() allocates a brand new OSSL_CMP_CRLSTATUS structure that contains either a copy of the distribution point name dpn or a copy of the certificate issuer issuer.

🚨 giving both is an error. pick a lane, bestie, you literally cannot have both.

and if you give it, a copy of the CRL issuance time thisUpdate is also included. ✨

OSSL_CMP_CRLSTATUS_create() is the high-level glow-up variant of OSSL_CMP_CRLSTATUS_new1(). it fills the thisUpdate field with a copy of the thisUpdate field of crl — if present. it fills the CRLSource field with a copy of the first data item it finds using the crl and/or cert parameters, like so:

any available distribution point name is preferred over issuer names 👑
data from cert, if present, is preferred over data from crl
if no distribution point names are available, candidate issuer names are taken from the following sources, as far as present:
1. the list of distribution points in the first cRLDistributionPoints extension of cert,
2. the issuer field of the authority key identifier of cert,
3. the issuer DN of cert,
4. the issuer field of the authority key identifier of crl, and
5. the issuer DN of crl.

if only_DN is set, a candidate issuer name of type GENERAL_NAMES is accepted only if it contains exactly one general name of type directoryName. strict queen behaviour fr fr. 💅

OSSL_CMP_CRLSTATUS_get0() reads the fields of crlstatus and assigns them to *dpn, *issuer, and *thisUpdate. *thisUpdate is assigned only if the thisUpdate argument is not NULL. depending on which choice is present, either *dpn or *issuer will be NULL — never both, that's the whole point. and *thisUpdate can also be NULL if the field simply isn't present. 🫶

OSSL_CMP_ITAV_new0_crlStatusList() creates a new OSSL_CMP_ITAV structure of type crlStatusList that includes the optionally given list of CRL status data — each of which is of type OSSL_CMP_CRLSTATUS. 🎀

OSSL_CMP_ITAV_get0_crlStatusList() on success assigns to *out an internal pointer to the list of CRL status data in the infoValue field of itav. that pointer may be NULL if no CRL status data is included.

it is an error if the infoType of itav is not crlStatusList. don't test her.

OSSL_CMP_ITAV_new_crls() creates a new OSSL_CMP_ITAV structure of type crls — including an empty list of CRLs if the crl argument is NULL, or including a singleton list with a copy of the provided CRL otherwise. 🍓

OSSL_CMP_ITAV_get0_crls() on success assigns to *out an internal pointer to the list of CRLs contained in the infoValue field of itav. the pointer may be NULL if no CRL is included.

it is an error if the infoType of itav is not crls. again. don't test her. 😭

OSSL_CMP_ITAV_new0_certReqTemplate() creates an OSSL_CMP_ITAV structure of type certReqTemplate.

if certTemplate is NULL then keySpec must also be NULL, and the resulting ITAV can be used in a genm message to obtain the requirements a PKI has on the certificate template used to request certificates — or in a genp message stating that there are no such requirements. otherwise, the resulting ITAV includes a CertReqTemplateValue structure with certTemplate of type OSSL_CRMF_CERTTEMPLATE and an optional list of key specifications keySpec, each being of type OSSL_CMP_ATAV, and the resulting ATAV can be used in a genp message to provide requirements. ✨

OSSL_CMP_ITAV_get1_certReqTemplate() requires that itav has type certReqTemplate. it assigns NULL to *certTemplate if no OSSL_CRMF_CERTTEMPLATE structure with a certificate template value is in itav, otherwise a copy of the certTemplate field value. if keySpec is not NULL, it is assigned NULL if the structure is not present in itav or the keySpec field is absent. otherwise, the function checks that all elements of the keySpec field are of type algId or rsaKeyLen and assigns to *keySpec a copy of the keySpec field. 🧚

⭐ NOTES ⭐

CMP is defined in RFC 9810. that's the source of truth, go read it if you're feeling academic. 📚

👑 RETURN VALUES 👑

so here's the vibe check on what you get back:

OSSL_CMP_ITAV_new_caCerts(), OSSL_CMP_ITAV_new_rootCaCert(), OSSL_CMP_ITAV_new_rootCaKeyUpdate(), OSSL_CMP_CRLSTATUS_new1(), OSSL_CMP_CRLSTATUS_create(), OSSL_CMP_ITAV_new0_crlStatusList(), OSSL_CMP_ITAV_new_crls() and OSSL_CMP_ITAV_new0_certReqTemplate() return a pointer to the new ITAV structure on success, or NULL on error. 🎉
OSSL_CMP_ITAV_get0_caCerts(), OSSL_CMP_ITAV_get0_rootCaCert(), OSSL_CMP_ITAV_get0_rootCaKeyUpdate(), OSSL_CMP_CRLSTATUS_get0(), OSSL_CMP_ITAV_get0_crlStatusList(), OSSL_CMP_ITAV_get0_crls() and OSSL_CMP_ITAV_get1_certReqTemplate() return 1 on success, 0 on error.

1 or 0. binary. iconic. 💅

go read those too, they're the supporting cast and they ate. 🔥

🌸 HISTORY 🌸

OSSL_CMP_ITAV_new_caCerts(), OSSL_CMP_ITAV_get0_caCerts(), OSSL_CMP_ITAV_new_rootCaCert(), OSSL_CMP_ITAV_get0_rootCaCert(), OSSL_CMP_ITAV_new_rootCaKeyUpdate(), and OSSL_CMP_ITAV_get0_rootCaKeyUpdate() were added in OpenSSL 3.2.
OSSL_CMP_CRLSTATUS_new1(), OSSL_CMP_CRLSTATUS_create(), OSSL_CMP_CRLSTATUS_get0(), OSSL_CMP_ITAV_new0_crlStatusList(), OSSL_CMP_ITAV_get0_crlStatusList(), OSSL_CMP_ITAV_new_crls(), OSSL_CMP_ITAV_get0_crls(), OSSL_CMP_ITAV_new0_certReqTemplate() and OSSL_CMP_ITAV_get1_certReqTemplate() were added in OpenSSL 3.4.

so the first batch is the OG squad and the second batch is the newer drop. both valid. both slay. 💜

💖 COPYRIGHT 💖

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

okay that's the whole page bestie, you understood it, you're literally a CMP main character now 👑

signing off from version 3.5.9, dated 2026-09-29 — this was OSSL_CMP_ITAV_NEW_CACERTS(3ossl), and yes, she served. mwah. 💋

📦 where this page comes from

fedora 43: openssl-devel 1:3.5.9-1.fc43 · Apache-2.0
fedora 43: openssl-devel 1:3.5.9-1.fc43 · Apache-2.0
fedora 44: openssl-devel 1:3.5.9-1.fc44 · Apache-2.0
fedora 44: openssl-devel 1:3.5.9-1.fc44 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms