OCSP_RESPONSE_STATUS(3ossl)

📦
version 15.1 · 3 versions
, in freebsd 15.1

💅 OCSP_RESPONSE_STATUS(3ossl) — the OpenSSL OCSP response glow-up guide

okay bestie, sit down, grab a strawberry drink 🍓 because this is the 3ossl manual page all about OCSP response functions and honestly it's giving "cryptographic paperwork but make it cute." We're talking responses, responder IDs, and signing basic responses. No cap, it's a lot of little functions, but we're gonna get through every single one together. 🫶

✨ NAME ✨

OCSP_response_status, OCSP_response_get1_basic, OCSP_response_create, OCSP_RESPONSE_free, OCSP_RESPID_set_by_name, OCSP_RESPID_set_by_key_ex, OCSP_RESPID_set_by_key, OCSP_RESPID_match_ex, OCSP_RESPID_match, OCSP_basic_sign, OCSP_basic_sign_ctx — these are the OCSP response functions. That's the whole squad. 👑

🌈 SYNOPSIS 🌈

lowkey the whole cast list, in code form, exactly as written:

#include <openssl/ocsp.h>

int OCSP_response_status(OCSP_RESPONSE *resp);
OCSP_BASICRESP *OCSP_response_get1_basic(OCSP_RESPONSE *resp);
OCSP_RESPONSE *OCSP_response_create(int status, OCSP_BASICRESP *bs);
void OCSP_RESPONSE_free(OCSP_RESPONSE *resp);

int OCSP_RESPID_set_by_name(OCSP_RESPID *respid, X509 *cert);
int OCSP_RESPID_set_by_key_ex(OCSP_RESPID *respid, X509 *cert,
                              OSSL_LIB_CTX *libctx, const char *propq);
int OCSP_RESPID_set_by_key(OCSP_RESPID *respid, X509 *cert);
int OCSP_RESPID_match_ex(OCSP_RESPID *respid, X509 *cert, OSSL_LIB_CTX *libctx,
                         const char *propq);
int OCSP_RESPID_match(OCSP_RESPID *respid, X509 *cert);

int OCSP_basic_sign(OCSP_BASICRESP *brsp, X509 *signer, EVP_PKEY *key,
                    const EVP_MD *dgst, STACK_OF(X509) *certs,
                    unsigned long flags);
int OCSP_basic_sign_ctx(OCSP_BASICRESP *brsp, X509 *signer, EVP_MD_CTX *ctx,
                        STACK_OF(X509) *certs, unsigned long flags);

🦋 DESCRIPTION 🦋

okay so here's the tea on every single one of them ☕

OCSP_response_status() returns the OCSP response status of resp. It gives you back one of these values, and yes, I'm listing all six because we don't skip:

  • OCSP_RESPONSE_STATUS_SUCCESSFUL
  • OCSP_RESPONSE_STATUS_MALFORMEDREQUEST
  • OCSP_RESPONSE_STATUS_INTERNALERROR
  • OCSP_RESPONSE_STATUS_TRYLATER
  • OCSP_RESPONSE_STATUS_SIGREQUIRED
  • OCSP_RESPONSE_STATUS_UNAUTHORIZED

OCSP_response_get1_basic() decodes and returns the OCSP_BASICRESP structure that's contained in resp. It's like opening the envelope and pulling out the actual letter 💌

OCSP_response_create() creates and returns an OCSP_RESPONSE structure for status, and it can optionally include the basic response bs. Build-a-response workshop, literally.

OCSP_RESPONSE_free() frees up the OCSP response resp. And if the argument is NULL, nothing is done — it just minds its business, iconic behaviour honestly.

OCSP_RESPID_set_by_name() sets the name of the OCSP_RESPID to be the same as the subject name in the supplied X509 certificate cert for the OCSP responder. name match, slay.

OCSP_RESPID_set_by_key_ex() sets the key of the OCSP_RESPID to be the same as the key in the supplied X509 certificate cert for the OCSP responder. Important detail: the key is stored as a SHA1 hash. To calculate that hash, the SHA1 algorithm is fetched using the library ctx libctx and the property query string propq — see "ALGORITHM FETCHING" in crypto(7) for further information. iykyk 🧚

OCSP_RESPID_set_by_key() does the same as OCSP_RESPID_set_by_key_ex() except that the default library context is used with an empty property query string. Same energy, less configuration.

⚠️ okay this part matters, bestie: an OCSP_RESPID can only have one of the name, or the key set. Calling OCSP_RESPID_set_by_name() or OCSP_RESPID_set_by_key() will clear any existing setting. So it's not "add", it's "replace". No stacking. periodt.

OCSP_RESPID_match_ex() tests whether the OCSP_RESPID given in respid matches with the X509 certificate cert, based on the SHA1 hash. To calculate the hash, the SHA1 algorithm is fetched using the library ctx libctx and the property query string propq — again, see "ALGORITHM FETCHING" in crypto(7) for further information.

OCSP_RESPID_match() does the same as OCSP_RESPID_match_ex() except that the default library context is used with an empty property query string. Twin behaviour, default-vibes edition 💜

OCSP_basic_sign() signs the OCSP response brsp using certificate signer, private key key, digest dgst and additional certificates certs. Two flags to know:

  • If the flags option OCSP_NOCERTS is set, then no certificates will be included in the response.
  • If the flags option OCSP_RESPID_KEY is set, then the responder is identified by key ID rather than by name.

OCSP_basic_sign_ctx() also signs the OCSP response brsp, but it uses the parameters contained in the digest context ctx instead. Same signing mission, different source of parameters ✨

💀 RETURN VALUES 💀

  • OCSP_RESPONSE_status() returns a status value. That's it, that's the vibe.
  • OCSP_response_get1_basic() returns an OCSP_BASICRESP structure pointer, or NULL if an error occurred 😭
  • OCSP_response_create() returns an OCSP_RESPONSE structure pointer, or NULL if an error occurred 😭
  • OCSP_RESPONSE_free() does not return a value. void queen, returns nothing, still essential.
  • OCSP_RESPID_set_by_name(), OCSP_RESPID_set_by_key(), OCSP_basic_sign(), and OCSP_basic_sign_ctx() return 1 on success or 0 on failure.
  • OCSP_RESPID_match() returns 1 if the OCSP_RESPID and the X509 certificate match, or 0 otherwise.

🎀 NOTES 🎀

OCSP_response_get1_basic() is only called if the status of a response is OCSP_RESPONSE_STATUS_SUCCESSFUL. Like, don't try to open the envelope if the mail never arrived, bestie. 🙈

🌸 SEE ALSO 🌸

go read these too, they're all part of the family:

crypto(7) OCSP_cert_to_id(3) OCSP_request_add1_nonce(3) OCSP_REQUEST_new(3) OCSP_resp_find_status(3) OCSP_sendreq_new(3) OCSP_RESPID_new(3) OCSP_RESPID_free(3)

⭐ HISTORY ⭐

lore drop:

  • The OCSP_RESPID_set_by_name(), OCSP_RESPID_set_by_key() and OCSP_RESPID_match() functions were added in OpenSSL 1.1.0a.
  • The OCSP_basic_sign_ctx() function was added in OpenSSL 1.1.1.

Copyright 2015-2024 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 page, bestie — you ate that. This one's from OpenSSL 3.5.6, dated 2026-04-07, and the manual page is OCSP_RESPONSE_STATUS(3ossl). go forth and respond to OCSP requests responsibly 🦋✨
📦 where this page comes from