man.bsd.lv manual page server

Manual Page Search Parameters
TLS_CONN_VERSION(3) Library Functions Manual TLS_CONN_VERSION(3)

tls_conn_version, tls_conn_cipher, 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

#include <tls.h>

const char *
tls_conn_version(struct tls *ctx);

const char *
tls_conn_cipher(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);

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):

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

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

() 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.

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

() indicates whether a TLS session has been resumed during the handshake with the server connected to ctx (client only).

() checks if the peer of ctx has provided a certificate.

() checks if the peer of a TLS ctx has provided a certificate that contains a SAN or CN that matches name.

() returns a pointer to memory containing a PEM-encoded certificate chain for the peer certificate from ctx.

() returns a string corresponding to the subject of the peer certificate from ctx.

() returns a string corresponding to the issuer of the peer certificate from ctx.

() 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"

() returns the time corresponding to the start of the validity period of the peer certificate from ctx.

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

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.

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

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.

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

December 14, 2018 DragonFly-5.6.1