TLS_CONN_VERSION(3) FreeBSD 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
#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 <
[email protected]>
Joel Sing <
[email protected]>
FreeBSD 14.1-RELEASE-p8 December 10, 2024 FreeBSD 14.1-RELEASE-p8