SSL_GET_PEER_CERTIFICATE(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 SSL_GET_PEER_CERTIFICATE — get the X509 certificate of the peer 🎀

okay so bestie, welcome to SSL_GET_PEER_CERTIFICATE(3ossl) — yes that's the whole manual name, it's giving long-but-iconic. This is the page where OpenSSL hands you the certificate the other side of your TLS connection showed up with. Let's get into it ✨

✨ SYNOPSIS ✨

#include <openssl/ssl.h>

X509 *SSL_get0_peer_certificate(const SSL *ssl);
X509 *SSL_get1_peer_certificate(const SSL *ssl);

okay so there's also this third one, but heads up: it's been deprecated since OpenSSL 3.0, and you can hide it entirely by defining OPENSSL_API_COMPAT with a suitable version value. check openssl_user_macros(7) for how that works 🫶

X509 *SSL_get_peer_certificate(const SSL *ssl);

🌸 DESCRIPTION 🌸

These functions literally just return a pointer to the X509 certificate the peer presented. That's it. That's the whole vibe.

If the peer didn't present a certificate? You get NULL. no cert, no pointer, no drama 💀

🦋 NOTES 🦋

okay so the protocol definition is doing a lot of heavy lifting here, let me break it down:

  • A TLS/SSL server will always send a certificate, if present. main character energy, always showing up 🌟
  • A client will only send a certificate when the server explicitly requests it — see SSL_CTX_set_verify(3). so polite, waiting to be asked 🙈
  • If an anonymous cipher is used, no certificates are sent at all. periodt.
⚠️ big one, bestie: the fact that a certificate got returned tells you nothing about the verification state. zero. nada. do not pass go. use SSL_get_verify_result(3) to actually check the verification state, iykyk 🔥

now the refcount lore, because this is where people get got 😭

  • SSL_get1_peer_certificate() increments the reference count of the returned X509 object by one. so it will not be destroyed when the session containing the peer certificate is freed — it's yours now, you own it. You must explicitly free it using X509_free().
  • SSL_get0_peer_certificate() does not increment the reference count. so do not free it. like, ever. it's not yours, it's borrowed 💅

and for the collectors: SSL_get_peer_certificate() is an alias of SSL_get1_peer_certificate(). same function, different name, we love a rebrand 👑

⭐ RETURN VALUES ⭐

the following return values can occur:

  • NULL — no certificate was presented by the peer, or no connection was established. sad but valid 🥲
  • Pointer to an X509 certificate — the return value points to the certificate presented by the peer. slay 💖

🌈 SEE ALSO 🌈

go read them, they're all part of the same friend group 🫶

🎀 HISTORY 🎀

  • SSL_get0_peer_certificate() and SSL_get1_peer_certificate() were added in 3.0.0.
  • SSL_get_peer_certificate() was deprecated in 3.0.0. it had a good run, we still love her 💜

Copyright 2000-2024 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 page, bestie! 🧚 this little gift was brought to you by OpenSSL 3.5.0, dated 2026-09-25, living under the manual name SSL_GET_PEER_CERTIFICATE(3ossl) — go forth and ✨free your X509 objects correctly✨ 💖🌸

📦 where this page comes from