TLS_CONN_VERSION(3) | Library Functions Manual | TLS_CONN_VERSION(3)

# 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

library “libtls” libssl libcrypto
`#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

These functions return information about a TLS connection and will only succeed after the handshake is complete (the connection information applies to both clients and servers, unless noted otherwise):

`tls_conn_version`() returns a string corresponding to a TLS version negotiated with the peer connected to ctx.

`tls_conn_cipher`() returns a string corresponding to the cipher suite negotiated with the peer connected to ctx.

`tls_conn_cipher_strength`() returns the strength in bits for the symmetric cipher that is being used with the peer connected to ctx.

`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 then NULL is returned.

`tls_conn_servername`() returns a string corresponding to the servername that the client connected to ctx requested by sending a TLS Server Name Indication extension (server only).

`tls_conn_session_resumed`() indicates whether a TLS session has been 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.

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

`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 corresponding to the subject of the peer certificate from ctx.

`tls_peer_cert_issuer`() returns a string corresponding to the issuer of the peer certificate from ctx. `tls_peer_cert_common_name`() returns a string corresponding to the common name of the peer certificate from ctx or the empty string if no common name is present.

`tls_peer_cert_hash`() returns a string corresponding to 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 this could change in the future. The hash string for a certificate in file mycert.crt can be generated using the 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.

`tls_peer_cert_notafter`() returns the time corresponding to the end of the validity period of the peer certificate from ctx.

# RETURN VALUES

The `tls_conn_session_resumed`() function returns 1 if a TLS session was resumed or 0 if it was not.

The `tls_peer_cert_provided`() and `tls_peer_cert_contains_name`() functions 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

`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. `tls_peer_cert_common_name`() appeared in OpenBSD 7.7.

# AUTHORS

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

July 7, 2025 | Debian