DragonFly On-Line Manual Pages

TLS_CONN_VERSION(3)   DragonFly Library Functions Manual   TLS_CONN_VERSION(3)

NAME
     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

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_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 nego-
     tiated 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 proto-
     col 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 cer-
     tificate.

     tls_peer_cert_contains_name() checks if the peer of a TLS ctx has pro-
     vided 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 gen-
     erated 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_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.

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

DragonFly 5.5			 May 26, 2018			 DragonFly 5.5