SSL_GET_PEER_CERT_CHAIN(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💅 SSL_GET_PEER_CERT_CHAIN 💅

okay so bestie, this is a page from OpenSSL (the 3ossl manual, iykyk) and it's literally all about peeking at the certificate chain your peer sent you. two little functions, one big vibe check on who you're talking to. let's get into it 🎀

✨ SYNOPSIS ✨

like, include the header first, obviously:

#include <openssl/ssl.h>

STACK_OF(X509) *SSL_get_peer_cert_chain(const SSL *ssl);
STACK_OF(X509) *SSL_get0_verified_chain(const SSL *ssl);

periodt. that's the whole API surface, two functions, both taking a const SSL *ssl and both handing you back a STACK_OF(X509) *. 💅

🌸 DESCRIPTION 🌸

SSL_get_peer_cert_chain() 🦋

This one returns a pointer to a STACK_OF(X509) — the certificates that make up the certificate chain sent by the peer. Simple as that.

But here's the tea, and it depends on which side you're on:

  • Client side: the stack also contains the peer's certificate. cute, convenient, slay. ✨
  • Server side: nope, the peer's certificate is not in there — you gotta grab it separately with SSL_get_peer_certificate(3). don't @ me, that's just how it is.

And if the peer straight up didn't present a certificate? NULL. nothing. ghosted. 💀

NB (not me being serious for a sec): SSL_get_peer_cert_chain() gives you the peer chain as sent by the peer — it only consists of the certificates the peer has sent, in the order the peer has sent them. it is NOT a verified chain. like, it's giving "trust me bro" energy, not "I checked their ID" energy. 🙈

SSL_get0_verified_chain() 👑

This one's the main character. It returns the verified certificate chain of the peer, including the peer's end entity certificate. the real deal. 🌈

Two things though, bestie, listen up:

  1. It must be called after a session has been successfully established. no session, no chain, no exceptions.
  2. If peer verification was not successful — which you can tell because SSL_get_verify_result() is not returning X509_V_OK — then the chain may be incomplete or invalid. lowkey a red flag, highkey important. 🚩

🧚 NOTES 🧚

Session resumed? Then the peers do not send certificates, so both of these functions return a NULL pointer. yeah. nothing. zip. 😭 If you wanna know whether a session is resumed, call SSL_session_reused() and find out — it's right there for you. 🫶

Reference counts — the important bit, don't skip this: the reference count of each certificate in the returned STACK_OF(X509) object is not incremented. and the returned stack may be invalidated by renegotiation. 💀

So if you wanna hold onto any of those certificates indefinitely? You gotta do the work yourself:

  • bump the reference counts with X509_up_ref(), or
  • get a whole copy of the entire chain with X509_chain_up_ref().

no shortcuts, bestie. 🎀

⭐ RETURN VALUES ⭐

Here's what you can get back:

  • NULL — no certificate was presented by the peer, or no connection was established, or the certificate chain is no longer available when a session is reused. basically the "sorry, nothing for you" answer. 😭
  • Pointer to a STACK_OF(X509) — the return value points to the certificate chain presented by the peer. the good ending. 👑✨

🔥 SEE ALSO 🔥

go read these next, they're all connected, iykyk:

Copyright 2000-2016 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>.

aaaand that's the whole page, bestie 🫶 go forth and verify those chains. this was OpenSSL 3.5.6, dated 2026-04-07 — SSL_GET_PEER_CERT_CHAIN(3ossl), signing off. mwah 💋💅✨

📦 where this page comes from