Your company here, and a link to your site. Click to find out more.

tls_conn_version - Man Page

inspect an established TLS connection


#include <tls.h>

const char *
tls_conn_version(struct tls *ctx);

const char *
tls_conn_cipher(struct tls *ctx);

tls_conn_cipher_strength(struct tls *ctx);

const char *
tls_conn_alpn_selected(struct tls *ctx);

const char *
tls_conn_servername(struct tls *ctx);

tls_conn_session_resumed(struct tls *ctx);

tls_peer_cert_provided(struct tls *ctx);

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

tls_peer_cert_notbefore(struct tls *ctx);

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

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


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.


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

Referenced By

netcat(1), tls_config_verify(3), tls_init(3), tls_ocsp_process_response(3), tls_read(3).

The man pages tls_conn_alpn_selected(3), tls_conn_cipher(3), tls_conn_cipher_strength(3), tls_conn_servername(3), tls_conn_session_resumed(3), tls_peer_cert_chain_pem(3), tls_peer_cert_contains_name(3), tls_peer_cert_hash(3), tls_peer_cert_issuer(3), tls_peer_cert_notafter(3), tls_peer_cert_notbefore(3), tls_peer_cert_provided(3) and tls_peer_cert_subject(3) are aliases of tls_conn_version(3).

November 2, 2019