SSL_CTX_SET_CERT_CB(3ossl)

💖 SSL_CTX_set_cert_cb — handle certificate callback function 💖

okay bestie, welcome to SSL_CTX_SET_CERT_CB(3ossl), the manpage that's literally about handing OpenSSL a lil function of your own so you get to decide which certs go out into the world. it's giving "i got this, trust me" energy. let's get into it 🦋

---

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

---

🌸 DESCRIPTION 🌸

so SSL_CTX_set_cert_cb() and SSL_set_cert_cb() are the two girlies that set the cert_cb callback. and the arg value? that's just a pointer, and it gets passed straight to your application callback. cute, right? 💅

when cert_cb is NULL, no callback function is used. simple as. no callback, no drama.

now the main character: cert_cb is your application defined callback. she gets called before a certificate will be used by a client or server. once she's up, she can inspect the passed ssl structure and set or clear any appropriate certificates. iconic behaviour honestly 👑

and here's the part where you gotta pay attention, bestie, because the return value is not vibes-based, it's rules-based:

• if the callback is successful it MUST return 1 — even if no certificates have been set. yes, even then. 1 is non-negotiable.
• a 0 is returned on error, which will abort the handshake with a fatal internal error alert. 💀 not the vibe.
• a negative return 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. and the next call to the handshake function will again lead to the call of cert_cb.
• it is the job of the cert_cb to store information about the state of the last call, if required to continue. that's on you, boo — she won't remember for you 🙈

---

🎀 NOTES 🎀

an application will typically call SSL_use_certificate() and SSL_use_PrivateKey() to set the end entity certificate and private key. she can add intermediate and optionally the root CA certificates using SSL_add1_chain_cert().

she might also call SSL_certs_clear() to delete any certificates associated with the SSL object. spring cleaning era ✨

now, tea time ☕ — the certificate callback functionality supersedes the (largely broken) functionality provided by the old client certificate callback interface. and the way that it is always called even if a certificate is already set, so the callback can modify or delete the existing certificate? obsessed. no skipping, no shortcuts.

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

and the safety net? 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 server said "not today" and honestly, valid.

---

⭐ RETURN VALUES ⭐

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

that's it. that's the section. they just don't. no notes 💅

---

🌈 SEE ALSO 🌈

• ssl(7)
• SSL_use_certificate(3)
• SSL_add1_chain_cert(3)
• SSL_get_client_CA_list(3)
• SSL_clear(3)
• SSL_free(3)

---

👑 COPYRIGHT 👑

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

---

okay that's the whole page, bestie, no cap. go set your cert callback and slay 💖

mwah 💋 this was OpenSSL 3.5.9, dated 2026-09-29, page SSL_CTX_SET_CERT_CB(3ossl) — take care of her fr fr 🫶