OCSP_REQUEST_ADD1_NONCE(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💅 OCSP_REQUEST_ADD1_NONCE

okay so bestie, this is a page from the 3ossl manual — that's the OpenSSL corner of manpage-land, and today we're learning about nonces for OCSP. Yes, nonces. No, not that kind. Sit down, I got you. 🎀

✨ NAME ✨

OCSP_request_add1_nonce, OCSP_basic_add1_nonce, OCSP_check_nonce, OCSP_copy_nonce — the OCSP nonce functions, aka the four little besties that add, copy, and vibe-check nonces on OCSP requests and responses. 🦋

🌸 SYNOPSIS 🌸

#include <openssl/ocsp.h>

int OCSP_request_add1_nonce(OCSP_REQUEST *req, unsigned char *val, int len);
int OCSP_basic_add1_nonce(OCSP_BASICRESP *resp, unsigned char *val, int len);
int OCSP_copy_nonce(OCSP_BASICRESP *resp, OCSP_REQUEST *req);
int OCSP_check_nonce(OCSP_REQUEST *req, OCSP_BASICRESP *resp);

💖 DESCRIPTION 💖

🫶 OCSP_request_add1_nonce()

Slaps a nonce onto the OCSP request req — the nonce has value val and length len. If val is NULL, it just rolls a random one for you (iconic behaviour, honestly). And if len is zero or negative, a default length kicks in — currently 16 bytes. 🔥

🫶 OCSP_basic_add1_nonce()

Literally identical to OCSP_request_add1_nonce() in every way, except the nonce lands on the OCSP basic response resp instead. Same energy, different target. 💅

🫶 OCSP_check_nonce()

Compares the nonce value sitting in req against the one in resp. Like a vibe check, but for cryptographic nonces. ⭐

🫶 OCSP_copy_nonce()

Takes whatever nonce value is present in req and copies it over to resp. Copy-paste but make it protocol. 🧚

👑 RETURN VALUES 👑

  • OCSP_request_add1_nonce() and OCSP_basic_add1_nonce() — return 1 for success, 0 for failure. Simple. Clean. No notes. ✨
  • OCSP_copy_nonce() — returns 1 if a nonce was successfully copied, 2 if there was no nonce present in req at all, and 0 if an error occurred. Three moods, one function. 💀
  • OCSP_check_nonce() — returns the result of the nonce comparison between req and resp, and the return value is the answer. Let's break it down because this is the part everyone asks about in the group chat:
    • nonces present and equal → 1 💚
    • nonces absent → 2 🌸
    • nonce present in the response only → 3 🦋
    • nonces present and unequal → 0 💀
    • nonce present in the request only → -1 😭

🌈 NOTES 🌈

For most purposes, the nonce value in a request is set to a random value — which is exactly why the val parameter in OCSP_request_add1_nonce() is usually NULL. Let the function cook. 🔥

An OCSP nonce is typically added to an OCSP request to thwart replay attacks, by checking that the same nonce value shows up in the response. Matchy-matchy = safe. 🫶

Some responders may include a nonce in all responses, even if one was never supplied. Rude? Generous? Unclear. 🤷

Some responders cache OCSP responses and don't sign each response, purely for performance reasons. As a result, they do not support nonces. So if that's your responder, don't come for the nonces. 🙈

The return values of OCSP_check_nonce() can be checked to cover each case:

  • A positive return value effectively indicates success: nonces are both present and match, both absent, or present in the response only. ✅
  • A nonzero return additionally covers the case where the nonce is present in the request only — which will happen if the responder doesn't support nonces. 🤝
  • A zero return value indicates present and mismatched nonces, and this should be treated as an error condition. Not a vibe. Treat it as an error. Periodt. 🚨

🔍 SEE ALSO 🔍

crypto(7), OCSP_cert_to_id(3), OCSP_REQUEST_new(3), OCSP_resp_find_status(3), OCSP_response_status(3), OCSP_sendreq_new(3)

Copyright 2015-2020 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>.

bestie, real talk: that license line means you actually have to follow the license. don't just skim it. 💜

and that's the whole page, bestie 🎀 — brought to you by OpenSSL 3.5.6, dated 2026-04-07, filed under OCSP_REQUEST_ADD1_NONCE(3ossl). go forth and nonce responsibly 💅✨

📦 where this page comes from