NAME
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_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);
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);
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_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_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_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.
POINTER TO tls_ocsp_process_response(3)
RETURN VALUES
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.
AUTHORS
Bob Beck
<beck@openbsd.org>
Joel Sing
<jsing@openbsd.org>