OpenBSD 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_peer_cert_provided, tls_peer_cert_contains_name, tls_peer_cert_issuer, tls_peer_cert_subject, tls_peer_cert_hash, tls_peer_cert_notbefore, tls_peer_cert_notafterinspect 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_peer_cert_provided(struct tls *ctx);

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

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

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

POINTER TO tls_ocsp_process_response(3)

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.

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

January 28, 2017 OpenBSD-6.1