SSL_CHECK_CHAIN(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 SSL_CHECK_CHAIN — okay so bestie, let's check this chain

So this is a page from the OpenSSL manual, section 3ossl — yes, the crypto library your whole internet secretly runs on. We're doing SSL_check_chain, and honestly? She's giving "quietly important." 🎀

✨ NAME ✨

SSL_check_chain — check certificate chain suitability. That's it, that's the whole vibe check for your certs. 💅

🦋 SYNOPSIS 🦋

#include <openssl/ssl.h>

int SSL_check_chain(SSL *s, X509 *x, EVP_PKEY *pk, STACK_OF(X509) *chain);

Like, four args, no notes. Copy it exactly, bestie, don't get creative. ✨

🌸 DESCRIPTION 🌸

So SSL_check_chain() literally just checks whether the certificate x, the private key pk, and the certificate chain chain are suitable for use with the current session s. That's the whole thing. She's a "is this outfit okay for this party" function, but for cryptography. 🫶

👑 RETURN VALUES 👑

SSL_check_chain() hands you back a bitmap of flags — a little handful of yes/no stickers telling you whether the chain is valid. Let's go through them one by one, no skips:

  • CERT_PKEY_VALID — the chain can be used with the current session. 🔥 And listen: if this flag is not set, the certificate will never be used, even if your app tries to set it, because it's inconsistent with the peer's preferences. Not negotiable, not up for discussion. Periodt.
  • CERT_PKEY_SIGN — the EE key can be used for signing. 💖
  • CERT_PKEY_EE_SIGNATURE — the signature algorithm of the EE certificate is acceptable. Slay.
  • CERT_PKEY_CA_SIGNATURE — the signature algorithms of all the CA certificates are acceptable. All of them. The whole committee agreed. 👑
  • CERT_PKEY_EE_PARAM — the parameters of the end entity certificate are acceptable (e.g. it's a supported curve). 🌈
  • CERT_PKEY_CA_PARAM — the parameters of all CA certificates are acceptable. 🦋
  • CERT_PKEY_EXPLICIT_SIGN — the end entity certificate algorithm can be used explicitly for signing, i.e. it's mentioned in the signature algorithms extension. iykyk. ✨
  • CERT_PKEY_ISSUER_NAME — the issuer name is acceptable. Heads up though: this one's only meaningful for client authentication. 🙈
  • CERT_PKEY_CERT_TYPE — the certificate type is acceptable. Again, only meaningful for client authentication. 💜
  • CERT_PKEY_SUITEB — the chain is suitable for Suite B use. Fancy. 🎀

💀 NOTES 💀

Okay so timing matters here, bestie:

SSL_check_chain() must be called in servers after a client hello message, or in clients after a certificate request message. Typically you'd call it in the certificate callback. Like, it's a "read the room first" situation. 🫶

If your app wants to support multiple certificate chains, you can call this function on each chain in turn — starting with the one you consider the most secure — and then just use the chain from the first set that returns suitable flags. Iconic, efficient, no cap. ✨

At minimum, CERT_PKEY_VALID must be set for a chain to be usable. That's the bare minimum, that's the entry fee. 💅 If your app supports multiple chains with different CA signature algorithms, you might also wanna check CERT_PKEY_CA_SIGNATURE too. And if no chain is suitable? A server should fall back to the most secure chain which sets CERT_PKEY_VALID. Fallback queen behavior. 👑

How is a chain's validity even determined? By checking if it matches a supported signature algorithm, supported curves, and — in the case of client authentication — certificate types and issuer names. 🌸

⚠️ Real talk: since the supported signature algorithms extension is only used in TLS 1.2, TLS 1.3 and DTLS 1.2, the results for earlier versions of TLS and DTLS may not be very useful. 😭 Applications may wish to specify a different "legacy" chain for earlier versions of TLS or DTLS. Consider this your heads-up.

🧚 SEE ALSO 🧚

Go read those too, bestie, they're part of the lore. 📚

Copyright 2015-2018 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! 🦋 This little gem is from OpenSSL version 3.5.0, dated 2026-09-25, and it lives at SSL_CHECK_CHAIN(3ossl) in the manual. Go forth and validate those chains — responsibly. 💖✨

📦 where this page comes from