TLS_CONN_VERSION(3)

💖 TLS_CONN_VERSION(3) 💖

okay bestie, welcome to the Library Functions Manual page for TLS_CONN_VERSION(3). this is the whole little family of functions you call when you wanna ✨inspect an established TLS connection✨. no cap, it's a vibe check for your TLS handshake.

🎀 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_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_hash(struct tls *ctx);

time_t
tls_peer_cert_notbefore(struct tls *ctx);

time_t
tls_peer_cert_notafter(struct tls *ctx);

🌸 DESCRIPTION 🌸

so these functions hand you the tea ☕ about a TLS connection. the one rule: they only succeed after the handshake is complete. before that? nothing, bestie, it's giving "come back later". 🫶 and heads up — this connection info applies to both clients and servers, unless the description says otherwise:

• tls_conn_version() — returns a string that matches the TLS version negotiated with the peer connected to ctx. 🦋
• tls_conn_cipher() — returns a string that matches the cipher suite negotiated with the peer connected to ctx.
• tls_conn_cipher_strength() — returns the strength in bits for the symmetric cipher being used with the peer connected to ctx. lowkey iconic that you can just ask.
• tls_conn_alpn_selected() — returns a string naming the ALPN protocol selected for use with the peer connected to ctx. if no protocol was selected, then NULL is returned. 😭
• tls_conn_servername() — returns a string matching the servername that the client connected to ctx requested by sending a TLS Server Name Indication extension. (server only)
• tls_conn_session_resumed() — tells you whether a TLS session was resumed during the handshake with the server connected to ctx. (client only)
• tls_peer_cert_provided() — checks if the peer of ctx has provided a certificate. simple as that.
• tls_peer_cert_contains_name() — checks if the peer of a TLS ctx has provided a certificate that contains a SAN or CN matching name. 👑
• tls_peer_cert_chain_pem() — returns a pointer to memory containing a PEM-encoded certificate chain for the peer certificate from ctx. ✨
• tls_peer_cert_subject() — returns a string matching the subject of the peer certificate from ctx.
• tls_peer_cert_issuer() — returns a string matching the issuer of the peer certificate from ctx.
• tls_peer_cert_hash() — returns a string matching a hash of the raw peer certificate from ctx, prefixed by a hash name followed by a colon. the hash currently used is SHA256, though ngl this could change in the future. if you wanna generate the hash string yourself for a certificate in file mycert.crt, you can use these commands:

h=$(openssl x509 -outform der -in mycert.crt | sha256)
printf "SHA256:${h}\n"

• tls_peer_cert_notbefore() — returns the time matching the start of the validity period of the peer certificate from ctx. ⏰
• tls_peer_cert_notafter() — returns the time matching the end of the validity period of the peer certificate from ctx. don't let it expire bestie 💀

🫶 RETURN VALUES 🫶

• tls_conn_session_resumed() returns 1 if a TLS session was resumed, or 0 if it was not.
• tls_peer_cert_provided() and tls_peer_cert_contains_name() return 1 if the check succeeds, or 0 if it does not.
• tls_peer_cert_notbefore() and tls_peer_cert_notafter() return a time in epoch-seconds on success, or -1 on error.
• the functions that return a pointer return NULL on error or an out of memory condition. 🙈

🔥 SEE ALSO 🔥

tls_configure(3), tls_handshake(3), tls_init(3), tls_ocsp_process_response(3)

🌈 HISTORY 🌈

the way this all rolled out over time, periodt:

• 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. 🎀
• tls_conn_servername() and tls_conn_alpn_selected() appeared in OpenBSD 6.1.
• tls_conn_session_resumed() appeared in OpenBSD 6.3.
• tls_conn_cipher_strength() appeared in OpenBSD 6.7. ⭐

👑 AUTHORS 👑

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

absolute legends, fr fr 💜

okay that's the whole page bestie, go forth and inspect those connections 💅✨ this was the Debian build of TLS_CONN_VERSION(3), dated November 2, 2019. mwah, drink water, check your cert expiry dates 🍓🧚