TLS_CONN_VERSION(3)

📦 version 4.1.0, in opensuse-leap 16.0

💖 TLS_CONN_VERSION(3) — Library Functions Manual 💖

Hey bestie! ✨ Welcome to the glow-up guide for your TLS connection. This is the TLS_CONN_VERSION(3) page from the Library Functions Manual, and it's literally all about inspecting an established TLS connection after the handshake is done. No cap, these functions are the main characters when you need to know what's going on under the hood. Let's get into it! 🎀

🌸 NAME 🌸

tls_conn_version, tls_conn_cipher, tls_conn_cipher_strength, tls_conn_alpn_selected, tls_conn_servername, tls_conn_session_resumed, tls_peer_cert_provided, tls_peer_cert_contains_name, tls_peer_cert_chain_pem, tls_peer_cert_issuer, tls_peer_cert_subject, tls_peer_cert_common_name, tls_peer_cert_hash, tls_peer_cert_notbefore, tls_peer_cert_notafter — inspect an established TLS connection 💅

💅 SYNOPSIS 💅

#include <tls.h>

const char *
tls_conn_version(struct tls *ctx);

const char *
tls_conn_cipher(struct tls *ctx);

int
tls_conn_cipher_strength(struct tls *ctx);

const char *
tls_conn_alpn_selected(struct tls *ctx);

const char *
tls_conn_servername(struct tls *ctx);

int
tls_conn_session_resumed(struct tls *ctx);

int
tls_peer_cert_provided(struct tls *ctx);

int
tls_peer_cert_contains_name(struct tls *ctx, const char *name);

const uint8_t *
tls_peer_cert_chain_pem(struct tls *ctx, size_t *size);

const char *
tls_peer_cert_issuer(struct tls *ctx);

const char *
tls_peer_cert_subject(struct tls *ctx);

const char *
tls_peer_cert_common_name(struct tls *ctx);

const char *
tls_peer_cert_hash(struct tls *ctx);

time_t
tls_peer_cert_notbefore(struct tls *ctx);

time_t
tls_peer_cert_notafter(struct tls *ctx);

🦋 DESCRIPTION 🦋

Okay so here's the tea: these functions spill all the info about a TLS connection, but they only succeed after the handshake is complete. The connection info applies to both clients and servers, unless noted otherwise. 💖

  • tls_conn_version() — returns a string that tells you which TLS version you negotiated with the peer connected to ctx. It's giving version reveal. ✨
  • tls_conn_cipher() — returns a string for the cipher suite that got negotiated with the peer connected to ctx. Slay. 💅
  • tls_conn_cipher_strength() — returns the strength in bits for the symmetric cipher being used with the peer connected to ctx. Big brain energy. 🧚
  • tls_conn_alpn_selected() — returns a string that specifies the ALPN protocol selected for use with the peer connected to ctx. If no protocol was selected, you get NULL back. No vibes selected, I guess. 🙈
  • tls_conn_servername() — returns a string for the servername that the client connected to ctx requested by sending a TLS Server Name Indication extension. This one is server only, bestie. 👑
  • tls_conn_session_resumed() — tells you whether a TLS session has been resumed during the handshake with the server connected to ctx. This one is client only. 🔥
  • tls_peer_cert_provided() — checks if the peer of ctx has provided a certificate. Iconic. 💜
  • tls_peer_cert_contains_name() — checks if the peer of a TLS ctx has provided a certificate that contains a SAN or CN that matches name. It's giving "do you know this person?" energy. 🫶
  • tls_peer_cert_chain_pem() — returns a pointer to memory containing a PEM-encoded certificate chain for the peer certificate from ctx. Chain mail but make it crypto. ⭐
  • tls_peer_cert_subject() — returns a string for the subject of the peer certificate from ctx. The who. 🌈
  • tls_peer_cert_issuer() — returns a string for the issuer of the peer certificate from ctx. The who-signed-it. 💀
  • tls_peer_cert_common_name() — returns a string for the common name of the peer certificate from ctx, or the empty string if no common name is present. Sometimes it's just nothing, and that's valid. 🙈
  • tls_peer_cert_hash() — returns a string for a hash of the raw peer certificate from ctx, prefixed by a hash name followed by a colon. Right now the hash used is SHA256, though this could change in the future. The hash string for a certificate in file mycert.crt can be generated using these commands:
h=$(openssl x509 -outform der -in mycert.crt | sha256)
printf "SHA256:${h}\n"
  • tls_peer_cert_notbefore() — returns the time corresponding to the start of the validity period of the peer certificate from ctx. It's giving birthday. 🎂
  • tls_peer_cert_notafter() — returns the time corresponding to the end of the validity period of the peer certificate from ctx. Expiration date, but for your cert. 🍓
💡 Vibe check: All of these only work after the handshake is complete. Don't try to peek before the connection is ready — that's not the move. 💅

✨ RETURN VALUES ✨

Here's what you get back, bestie:

  • tls_conn_session_resumed() returns 1 if a TLS session was resumed, or 0 if it was not. Simple. 🔥
  • tls_peer_cert_provided() and tls_peer_cert_contains_name() return 1 if the check succeeds, or 0 if it does not. Binary realness. 💖
  • tls_peer_cert_notbefore() and tls_peer_cert_notafter() return a time in epoch-seconds on success, or -1 on error. Epoch time is giving time traveler. 🕰️
  • The functions that return a pointer return NULL on error or an out of memory condition. No memory, no pointer. 😭

🌈 SEE ALSO 🌈

🎀 HISTORY 🎀

Let's take a lil walk down memory lane:

  • tls_conn_version(), tls_conn_cipher(), tls_peer_cert_provided(), tls_peer_cert_contains_name(), tls_peer_cert_issuer(), tls_peer_cert_subject(), tls_peer_cert_hash(), tls_peer_cert_notbefore(), and tls_peer_cert_notafter() appeared in OpenBSD 5.9. OG vibes. 👑
  • tls_conn_servername() and tls_conn_alpn_selected() appeared in OpenBSD 6.1. Glow up. ✨
  • tls_conn_session_resumed() appeared in OpenBSD 6.3. Renaissance. 🌸
  • tls_conn_cipher_strength() appeared in OpenBSD 6.7. Strength era. 💪
  • tls_peer_cert_common_name() appeared in OpenBSD 7.7. Fresh off the press. 🦋

💜 AUTHORS 💜

Big shoutout to the icons who wrote this:

  • Bob Beck <beck@openbsd.org>
  • Joel Sing <jsing@openbsd.org>

And that's a wrap! 🎀 This page comes from Debian, dated December 10, 2024. Catch you on the flip side, bestie! 💅✨🫶

📦 where this page comes from