Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
TLS_CONN_VERSION(3)	 BSD Library Functions Manual	   TLS_CONN_VERSION(3)

     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

     #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 ap-
     plies 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 ne-
     gotiated 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 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 re-
     sumed during the handshake	with the server	connected to ctx (client

     tls_peer_cert_provided() checks if	the peer of ctx	has provided a cer-

     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	fu-
     ture.  The	hash string for	a certificate in file mycert.crt can be	gener-
     ated 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.

     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.

     tls_configure(3), tls_handshake(3), tls_init(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 <>
     Joel Sing <>

BSD			       November	2, 2019				   BSD


Want to link to this manual page? Use this URL:

home | help