SSL_CTX_SET_CERT_CB(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💖 SSL_CTX_SET_CERT_CB(3SSL) — the OpenSSL glow-up 💖

okay bestie, sit down, hydrate, because we're talking about certificate callbacks and honestly? it's giving "control freak but make it secure". this is a page from the OpenSSL manual, and it's all about the moment right before a cert gets used, and how you can slide in and ✨curate✨ it yourself.

✨ NAME ✨

SSL_CTX_set_cert_cb, SSL_set_cert_cb — the functions that let you handle the certificate callback situation. 🎀

🌸 SYNOPSIS 🌸

#include <openssl/ssl.h>

void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg),
                         void *arg);
void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg);

there they are. two little functions. iconic behavior only. 💅

🦋 DESCRIPTION 🦋

so SSL_CTX_set_cert_cb() and SSL_set_cert_cb() are the ones that set the cert_cb callback, and the arg value is a pointer that gets passed straight through to your application callback. like a lil gift you hand over. 🎁

when cert_cb is NULL, no callback function is used. simple. clean. nothing happens. we love a no-op era.

now, cert_cb is the application defined callback, and here's the tea: it gets called before a certificate will be used by a client or server. so your callback can peek at the passed ssl structure and set or clear any appropriate certificates — your moment to be the main character of the handshake. 👑

and the return values matter, bestie, so pay attention:

  • if the callback is successful it MUST return 1 — even if no certificates have been set. yes, even then. it's non-negotiable fr fr.
  • returning zero is an error, and that will abort the handshake with a fatal internal error alert. dramatic, but deserved. 💀
  • returning a negative value will suspend the handshake, and the handshake function will return immediately. SSL_get_error(3) will return SSL_ERROR_WANT_X509_LOOKUP to indicate that the handshake was suspended. the next call to the handshake function will again lead to the call of cert_cb. and listen — it is the job of the cert_cb to store information about the state of the last call, if required to continue. so if you want it to pick up where it left off, that's on you, girlie. the library is not your assistant. 🙈

👑 NOTES 👑

an application will typically call SSL_use_certificate() and SSL_use_PrivateKey() to set the end entity certificate and private key. that's the standard combo, the starter pack, the it-girl setup. ✨

it can add intermediate and optionally the root CA certificates using SSL_add1_chain_cert(). chain it up, stack it up, build that lineage. 🌈

it might also call SSL_certs_clear() to delete any certificates associated with the SSL object. sometimes you gotta clear the timeline. no hard feelings. 🧹

now, the certificate callback functionality supersedes the (largely broken) functionality provided by the old client certificate callback interface. largely broken is the original's words, not mine — I'm just the messenger. and here's the key part: it is always called even is a certificate is already set so the callback can modify or delete the existing certificate. yes, that's the original's exact phrasing (typo and all, keeping it real) — always called, even when a cert already exists. so no "oops already set, guess I'll sit this one out" behavior. nope. you get your turn every time. 💅

a more advanced callback might examine the handshake parameters and set whatever chain is appropriate. for example, a legacy client supporting only TLSv1.0 might receive a certificate chain signed using SHA1, whereas a TLSv1.2 or later client which advertises support for SHA256 could receive a chain using SHA256. bespoke service, tailoring the chain to the audience. that's called range. 🎀

normal server sanity checks are performed on any certificates set by the callback. so if an EC chain is set for a curve the client does not support, it will not be used. the vibe check happens whether you like it or not. 🫶

⭐ RETURN VALUES ⭐

SSL_CTX_set_cert_cb() and SSL_set_cert_cb() do not return values.

yeah. nothing. void. they set it and they dip. 🦋

🔥 SEE ALSO 🔥

go read them, bestie, iykyk. 📚

Copyright 2014-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>.

and that's the whole page, periodt. 💅 this was OpenSSL 4.0.3, dated 2026-09-29, and yes you read that right — a date from the future. slay. go set your callbacks, return your 1s, and stay iconic. 💖🫶✨

📦 where this page comes from