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

AUTHORS

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

Debian                                          November 2, 2019                             TLS_CONN_VERSION(3)