SSL_GET_PEER_CERT_CHAIN(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💖 SSL_GET_PEER_CERT_CHAIN 💖

okay bestie so this is a page from the OpenSSL manual, specifically the <purple>SSL_GET_PEER_CERT_CHAIN</purple> section of the <purple>3SSL</purple> manual set. yes the title is literally screaming in all caps, that's just how manpages are, they're dramatic like that 💅

✨ NAME ✨

SSL_get_peer_cert_chain, SSL_get0_verified_chain — get the X509 certificate chain of the peer 🦋

like, you wanna know who you're talking to? which certs they handed over? that's this. iykyk.

🌸 SYNOPSIS 🌸

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

two functions, one vibe: get the chain. slay.

🎀 DESCRIPTION 🎀

SSL_get_peer_cert_chain()

so this one returns a pointer to a STACK_OF(X509) — that's the certificate chain, as in, the literal stack of certs that the peer sent you. and here's the tea on who gets what:

  • if you call it on the client side, the stack also contains the peer's certificate ✨
  • if you call it on the server side, the peer's certificate has to be grabbed separately using SSL_get_peer_certificate(3) 👀
  • if the peer straight up did not present a certificate, you get NULL back. no cert, no chain, no nothing 😭
NB: SSL_get_peer_cert_chain() returns 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 what they said, not what's been proven. periodt.

SSL_get0_verified_chain()

this one returns the verified certificate chain of the peer, including the peer's end entity certificate. iconic behavior honestly.

it must be called after a session has been successfully established. don't be jumping the gun bestie.

and if peer verification wasn't successful — which you can tell because SSL_get_verify_result() is not returning X509_V_OK — then the chain may be incomplete or invalid. so like, handle with care 🫶

🧚 NOTES 🧚

if the session is resumed, peers do not send certificates, so both of these functions return a NULL pointer. that's not a bug, that's just how resumed sessions work. you can call SSL_session_reused() to figure out whether a session is resumed, so you're not out here confused 💀

IMPORTANT — pay attention bestie: 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. if your application wants to use any certificates in the returned chain indefinitely, you must bump the reference counts using X509_up_ref(), or grab a copy of the whole entire chain with X509_chain_up_ref(). do not skip this step. i am begging 🙈

⭐ RETURN VALUES ⭐

here's what can come back at you:

  • 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.
  • Pointer to a STACK_OF(X509) — the return value points to the certificate chain presented by the peer. 🎉

🔥 SEE ALSO 🔥

go read those too, they're all connected, it's giving lore 🌈

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

okay that's the whole page bestie, you're officially certified in peer cert chain retrieval, no cap 💜

OpenSSL 4.0.3 · dated 2026-09-29 · from the SSL_GET_PEER_CERT_CHAIN(3SSL) page — stay verified, stay iconic, mwah 💖✨🎀🦋

📦 where this page comes from