OSSL_CMP_ITAV_NEW_CACERTS(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 OSSL_CMP_ITAV_NEW_CACERTS(3ossl) — the OpenSSL girlie's guide to CMP ITAVs

okay so bestie, this is a page from the OpenSSL manual, section 3ossl, and it's all about the CMP utility functions for handling specific genm and genp messages. trust me, it's more fun than it sounds. 🎀

✨ 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, all of them. the whole squad. one big happy function family.

🌸 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);

copy-paste it exactly, bestie, don't go editing things. 🙈

💖 DESCRIPTION 💖

so first things first: ITAV is short for InfoTypeAndValue. iconic name, honestly. it's giving "I Tell All Values." 💅

🎀 the caCerts girlies

OSSL_CMP_ITAV_new_caCerts() creates an OSSL_CMP_ITAV structure of type caCerts and fills it with a copy of the provided list of certificates. the caCerts argument may be NULL or contain any number of certificates — zero, one, forty, no judgement here. ✨

OSSL_CMP_ITAV_get0_caCerts() requires that itav has type caCerts. it assigns NULL to *out if there are no CA certificates in itav, otherwise the internal pointer of type STACK_OF(X509) with the certificates present. note the internal — you don't own it, you're just visiting. 🫶

👑 the rootCaCert crew

OSSL_CMP_ITAV_new_rootCaCert() creates a new OSSL_CMP_ITAV structure of type rootCaCert that includes the optionally given certificate. optional! lowkey chill of it.

OSSL_CMP_ITAV_get0_rootCaCert() requires that itav has type rootCaCert. it assigns NULL to *out if no certificate is included in itav, otherwise the internal pointer to the certificate contained in the infoValue field. again: internal pointer, hands off the merch. 💅

🦋 the rootCaKeyUpdate situation

OSSL_CMP_ITAV_new_rootCaKeyUpdate() creates a new OSSL_CMP_ITAV structure of type rootCaKeyUpdate that includes an RootCaKeyUpdateContent structure with the optional newWithNew, newWithOld, and oldWithNew certificates. ⭐ and here's the spicy bit: an RootCaKeyUpdateContent structure is included only if newWithNew is not NULL. so like, newWithNew is the main character here, no cap.

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. each of these pointers will be set to NULL if no root CA certificate update is present or the respective sub-field is not included. so basically you get NULLs when things aren't there, and that's correct behaviour, not a bug. 😭

💀 the CRLSTATUS saga

OSSL_CMP_CRLSTATUS_new1() allocates a new OSSL_CMP_CRLSTATUS structure that contains either a copy of the distribution point name dpn or a copy of the certificate issuer issuer — while giving both is an error. pick a lane, bestie. 🚫 and if given, a copy of the CRL issuance time thisUpdate is also included. 💜

OSSL_CMP_CRLSTATUS_create() is a high-level variant of OSSL_CMP_CRLSTATUS_new1(). so like, the glow-up version. 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 found using the crl and/or cert parameters as follows:

  • 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 following sources, as far as present: (in this order, okurrr 💅)
    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
    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. picky, but valid. ✨

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 the choice present, either *dpn or *issuer will be NULL. *thisUpdate can also be NULL if the field is not present. so many NULLs but like, on purpose. 🫶

🍓 the crlStatusList and crls girlies

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. the pointer may be NULL if no CRL status data is included. it is an error if the infoType of itav is not crlStatusList. 💀 wrong type = no vibes.

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. singleton! main character energy for that one CRL. 👑

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. same rule, different type. periodt. 🎀

🧚 the certReqTemplate finale

OSSL_CMP_ITAV_new0_certReqTemplate() creates an OSSL_CMP_ITAV structure of type certReqTemplate. now listen closely bestie, because this one has a rule: if certTemplate is NULL then also keySpec must be NULL. both or neither, that's the deal. 🤝

and then 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 — meaning certTemplate is not NULL — 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 keySpec field are of type algId or rsaKeyLen and assigns to *keySpec a copy of the keySpec field. yes, it's checking your IDs. yes, it cares. 💅

📝 NOTES 📝

CMP is defined in RFC 4210. that's the lore. 📜

⭐ RETURN VALUES ⭐

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. so like, one is yes, zero is no. simple as. ✨

ngl, check these. NULL and 0 are not friends you want showing up uninvited. 🙈

🦋 SEE ALSO 🦋

OSSL_CMP_ITAV_create(3) and OSSL_CMP_ITAV_get0_type(3) — go read those too, iykyk 💖

🌈 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. 🦋

Copyright 2022-2025 The OpenSSL Project Authors. All Rights Reserved.

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>. 🫶

and that's the whole thing, bestie! slay, you read the entire manual page. 💅✨

version 3.5.0 · dated 2026-09-25 · OSSL_CMP_ITAV_NEW_CACERTS(3ossl) — mwah, go forth and not leak your internal pointers 💖🎀🌸

📦 where this page comes from