OSSL_CMP_EXEC_CERTREQ(3ossl)

📦
version 3.5.9 · 8 versions
, in fedora 43, fedora 44

🎀 OSSL_CMP_EXEC_CERTREQ 🎀

okay so bestie, this is the OpenSSL manual page for OSSL_CMP_EXEC_CERTREQ(3ossl), and it is long, so buckle up. It's the whole squad of CMP client transaction functions, and I'm giving you every single one of them, no skips, no summaries, periodt 💅

✨ NAME ✨

OSSL_CMP_exec_certreq, OSSL_CMP_exec_IR_ses, OSSL_CMP_exec_CR_ses, OSSL_CMP_exec_P10CR_ses, OSSL_CMP_exec_KUR_ses, OSSL_CMP_IR, OSSL_CMP_CR, OSSL_CMP_P10CR, OSSL_CMP_KUR, OSSL_CMP_try_certreq, OSSL_CMP_exec_RR_ses, OSSL_CMP_exec_GENM_ses, OSSL_CMP_get1_caCerts, OSSL_CMP_get1_rootCaKeyUpdate, OSSL_CMP_get1_crlUpdate, OSSL_CMP_get1_certReqTemplate — functions implementing CMP client transactions 🫶

🌈 SYNOPSIS 🌈

#include <openssl/cmp.h>

X509 *OSSL_CMP_exec_certreq(OSSL_CMP_CTX *ctx, int req_type,
                            const OSSL_CRMF_MSG *crm);
X509 *OSSL_CMP_exec_IR_ses(OSSL_CMP_CTX *ctx);
X509 *OSSL_CMP_exec_CR_ses(OSSL_CMP_CTX *ctx);
X509 *OSSL_CMP_exec_P10CR_ses(OSSL_CMP_CTX *ctx);
X509 *OSSL_CMP_exec_KUR_ses(OSSL_CMP_CTX *ctx);
#define OSSL_CMP_IR
#define OSSL_CMP_CR
#define OSSL_CMP_P10CR
#define OSSL_CMP_KUR
int OSSL_CMP_try_certreq(OSSL_CMP_CTX *ctx, int req_type,
                         const OSSL_CRMF_MSG *crm, int *checkAfter);
int OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx);

STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx);
int OSSL_CMP_get1_caCerts(OSSL_CMP_CTX *ctx, STACK_OF(X509) **out);
int OSSL_CMP_get1_rootCaKeyUpdate(OSSL_CMP_CTX *ctx,
                                  const X509 *oldWithOld, X509 **newWithNew,
                                  X509 **newWithOld, X509 **oldWithNew);
int OSSL_CMP_get1_crlUpdate(OSSL_CMP_CTX *ctx, const X509 *crlcert,
                            const X509_CRL *last_crl,
                            X509_CRL **crl);
int OSSL_CMP_get1_certReqTemplate(OSSL_CMP_CTX *ctx,
                                  OSSL_CRMF_CERTTEMPLATE **certTemplate,
                                  OSSL_CMP_ATAVS **keySpec);
=head1 DESCRIPTION
yeah that last line really is in there, the doc just has =head1 DESCRIPTION chillin' inside the code block like it owns the place. we respect it. it stays. 😭

💖 DESCRIPTION 💖

This right here is the OpenSSL main API for Certificate Management Protocol (CMP) clients. Every single one of the OSSL_CMP_exec_*() functions performs a whole CMP transaction, which is literally a sequence of related CMP request messages and response messages. Like a whole conversation, not just one text. 💬

All of these functions take a populated OSSL_CMP_CTX structure as their first argument. Usually you're gonna need to set the server name, port, and path (the "CMP alias"), plus the credentials the client uses to authenticate itself to the server. And to authenticate the server, the client typically needs a trust store. The functions return their respective main results directly, and there are also accessor functions for pulling various results and status information out of the ctx. See OSSL_CMP_CTX_new(3) etc. for the details. 📚

The default conveying protocol is HTTP. Timeout values may be given per request-response pair and per transaction. See OSSL_CMP_MSG_http_perform(3) for details.

  • OSSL_CMP_exec_IR_ses() requests an initial certificate from the given PKI. 🌱
  • OSSL_CMP_exec_CR_ses() requests an additional certificate. ➕
  • OSSL_CMP_exec_P10CR_ses() conveys a legacy PKCS#10 CSR requesting a certificate. 📜
  • OSSL_CMP_exec_KUR_ses() obtains an updated certificate. 🔄

These four types of certificate enrollment are implemented as macros calling OSSL_CMP_exec_certreq(). Sneaky, but iconic.

OSSL_CMP_exec_certreq() performs a certificate request of the type specified by the req_type parameter, which may be IR, CR, P10CR, or KUR. For IR, CR, and KUR, the certificate template to be used in the request may be supplied via the crm parameter pointing to a CRMF structure. Typically crm is NULL, and then the template ingredients are taken from ctx and need to be filled in using OSSL_CMP_CTX_set1_subjectName(3), OSSL_CMP_CTX_set0_newPkey(3), OSSL_CMP_CTX_set1_oldCert(3), etc. For P10CR, OSSL_CMP_CTX_set1_p10CSR(3) needs to be used instead. The enrollment session may be blocked (with polling and sleeping in between) until the server side can fully process and ultimately answer the request. 😴

OSSL_CMP_try_certreq() is an alternative to the above functions that is more flexible regarding what to do after receiving a checkAfter value. Here's the tea:

  • When called for the first time (with no certificate request in progress for the given ctx) it starts a new transaction by sending a certificate request constructed as stated above using the req_type and optional crm parameter.
  • Otherwise (when according to ctx a 'waiting' status has been received before) it continues polling for the pending request unless the req_type argument is < 0, which aborts the request.
  • If the requested certificate is available the function returns 1 and the caller can use OSSL_CMP_CTX_get0_newCert(3) to retrieve the new certificate. 🎉
  • If no error occurred but no certificate is available yet then OSSL_CMP_try_certreq() remembers in the CMP context that it should be retried and returns -1 after assigning the received checkAfter value via the output pointer argument (unless it is NULL).
  • The checkAfter value indicates the number of seconds the caller should let pass before trying again. ⏰
  • The caller is free to sleep for the given number of seconds or for some other time and/or to do anything else before retrying by calling OSSL_CMP_try_certreq() again with the same parameter values as before.
  • OSSL_CMP_try_certreq() then polls to see whether meanwhile the requested certificate is available.
  • If the caller decides to abort the pending certificate request and provides a negative value as the req_type argument then OSSL_CMP_try_certreq() aborts the CMP transaction by sending an error message to the server.

OSSL_CMP_exec_RR_ses() requests the revocation of the certificate specified in the ctx using the issuer DN and serial number set by OSSL_CMP_CTX_set1_issuer(3) and OSSL_CMP_CTX_set1_serialNumber(3), respectively, otherwise the issuer DN and serial number of the certificate set by OSSL_CMP_CTX_set1_oldCert(3), otherwise the subject DN and public key of the certificate signing request set by OSSL_CMP_CTX_set1_p10CSR(3).

RFC 9810 is vague in which PKIStatus should be returned by the server, so here's how we vibe with it:

  • "accepted" and "grantedWithMods" → clear success ✅
  • "revocationWarning" and "revocationNotification" → handled just as warnings, because CAs typically return them as an indication that the certificate was already revoked
  • "rejection" → a clear error
  • "waiting" and "keyUpdateWarning" → make no sense for revocation and thus are treated as an error as well

The revocation session may be blocked (with polling and sleeping in between) until the server can fully process and ultimately answer the request. 😴

OSSL_CMP_exec_GENM_ses() sends a genm general message containing the sequence of infoType and infoValue pairs (InfoTypeAndValue; short: ITAV) optionally provided in the ctx using OSSL_CMP_CTX_push0_genm_ITAV(3). The message exchange may be blocked (with polling and sleeping in between) until the server can fully process and ultimately answer the request.

On success the function records in ctx status OSSL_CMP_PKISTATUS_accepted and returns the list of ITAVs received in a genp response message. This can be used, for instance, with infoType "signKeyPairTypes" to obtain the set of signature algorithm identifiers that the CA will certify for subject public keys. See RFC 9810 section 5.3.19 and appendix D.5 for details. Functions implementing more specific genm/genp exchanges are described next. 👀

OSSL_CMP_get1_caCerts() uses a genm/genp message exchange with infoType caCerts to obtain a list of CA certificates from the CMP server referenced by ctx. On success it assigns to *out the list of certificates received, which must be freed by the caller. NULL output means that no CA certificates were provided by the server.

OSSL_CMP_get1_rootCaKeyUpdate() uses a genm request message with infoType rootCaCert to obtain from the CMP server referenced by ctx in a genp response message with infoType rootCaKeyUpdate any update of the given root CA certificate oldWithOld and verifies it as far as possible. See RFC 9810 section 4.4 for details.

On success it assigns to *newWithNew the root certificate received. When the newWithOld and oldWithNew output parameters are not NULL, it assigns to them the corresponding transition certificates. NULL means that the respective certificate was not provided by the server. All certificates obtained this way must be freed by the caller. 🧚

⚠️ WARNING: The newWithNew certificate is meant to be a certificate that will be trusted. The trust placed in it cannot be stronger than the trust placed in the oldwithold certificate if present, otherwise it cannot be stronger than the weakest trust in any of the certificates in the trust store of ctx. So like... be careful bestie, this is not a vibe you wanna gamble on. 💀

OSSL_CMP_get1_crlUpdate() uses a genm request message with infoType crlStatusList to obtain CRL from the CMP server referenced by ctx in a genp response message with infoType crls. It uses last_crl and crlcert to create a request with a status field as described for OSSL_CMP_CRLSTATUS_create(3). On success it assigns to *crl the CRL received. NULL means that no CRL was provided by the server. The CRL obtained this way must be freed by the caller.

OSSL_CMP_get1_certReqTemplate() uses a genm request message with infoType certReqTemplate to obtain a certificate request template from the CMP server referenced by ctx. On success it assigns to *certTemplate the certificate template received. NULL output means that no certificate request template was provided by the server. The optional keySpec output parameter is assigned the key specification if received, otherwise it set to NULL. Both must be freed by the caller. 🫶

🦋 NOTES 🦋

CMP is defined in RFC 9810 (and CRMF in RFC 4211).

This CMP implementation focuses on the Lightweight CMP Profile (RFC 9483). Among other things, this implies that only commonly used CMP message types are supported and that each CMP message may not contain multiple certificate requests or responses. One thing at a time, bestie. 💅

When a client obtains from a CMP server CA certificates that it is going to trust, for instance via the caPubs field of a certificate response or using functions like OSSL_CMP_get1_caCerts() and OSSL_CMP_get1_rootCaKeyUpdate(), authentication of the CMP server is particularly critical. So special care must be taken setting up server authentication in ctx using functions such as OSSL_CMP_CTX_set0_trusted(3) (for certificate-based authentication) or OSSL_CMP_CTX_set1_secretValue(3) (for MAC-based protection). If authentication is certificate-based, OSSL_CMP_CTX_get0_validatedSrvCert(3) should be used to obtain the server validated certificate and perform an authorization check based on it. 🔐✨

and that's part 1, bestie — the rest is coming, don't you dare leave 🫶

✨ RETURN VALUES ✨

okay bestie this is the part where we find out what you actually get back, and it's giving very important so pay attention 💖

  • OSSL_CMP_exec_certreq(), OSSL_CMP_exec_IR_ses(), OSSL_CMP_exec_CR_ses(), OSSL_CMP_exec_P10CR_ses(), and OSSL_CMP_exec_KUR_ses() — these icons return a pointer to the newly obtained X509 certificate when everything slays, and NULL when it doesn't 😭. and listen: that pointer gets freed implicitly by OSSL_CMP_CTX_free() or CSSL_CMP_CTX_reinit() — so don't you dare free it yourself, that's not your job, the context handles it 💅
  • OSSL_CMP_try_certreq() — this one's got range, she returns three different things:
    • 1 — the requested certificate is available via OSSL_CMP_CTX_get0_newCert(3), or a pending certificate request was successfully aborted 🎀
    • 0 — error, we don't know her 🙈
    • -1 — a 'waiting' status came back and a checkAfter value is available. in that case OSSL_CMP_CTX_get0_newCert(3) gives you NULL, and the output parameter checkAfter has been used to assign the received value — unless checkAfter is NULL, in which case, well, it just doesn't 🤷‍♀️
  • OSSL_CMP_exec_RR_ses(), OSSL_CMP_get1_caCerts(), OSSL_CMP_get1_rootCaKeyUpdate(), OSSL_CMP_get1_crlUpdate() and OSSL_CMP_get1_certReqTemplate() — all of these return 1 on success, 0 on error. simple, clean, consistent, we love a predictable queen 👑
  • OSSL_CMP_exec_GENM_ses() — returns NULL on error, otherwise a pointer to the sequence of ITAV received, which may be empty (yes, empty is still valid bestie, don't panic 🌸). and this pointer? the caller must free it. that one's on you 🫶

🌈 EXAMPLES 🌈

fr fr, just go look at OSSL_CMP_CTX for the examples on how to prepare the context for these functions — that's where the setup lore lives 💜

👑 SEE ALSO 👑

the whole bestie squad, all linked up:

🦋 HISTORY 🦋

a little timeline moment, because the OpenSSL CMP lore is long and we respect the journey ✨

  • the OpenSSL CMP support was added in OpenSSL 3.0 — the origin story 💫
  • OSSL_CMP_get1_caCerts() and OSSL_CMP_get1_rootCaKeyUpdate() were added in OpenSSL 3.2 — glow up era 🎀
  • support for delayed delivery of all types of response messages was added in OpenSSL 3.3 — the era where patience became a feature 😌
  • OSSL_CMP_get1_crlUpdate() and OSSL_CMP_get1_certReqTemplate() were added in OpenSSL 3.4 — newest members of the family, iconic 💅

Copyright 2007-2026 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>.

real talk bestie: that license link is the whole vibe check for legal stuff, don't skip it 🫶

and that's a wrap on this page, pookie 💅 this was version 3.5.9, dated 2026-09-29, filed under OSSL_CMP_EXEC_CERTREQ(3ossl) — go forth and execute those cert requests, you absolute main character 🌟

📦 where this page comes from