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

FreeBSD Manual Pages

  
 
  

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

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 ap-
       plies to	both clients and servers, unless noted otherwise):

       tls_conn_version() returns a string corresponding to a TLS version  ne-
       gotiated	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 symmet-
       ric cipher that is being	used with the peer connected to	ctx.

       tls_conn_alpn_selected()	returns	a string that specifies	the ALPN  pro-
       tocol  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
       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 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() func-
       tions 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>

FreeBSD	Ports 14.quarterly     November	2, 2019		   TLS_CONN_VERSION(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=tls_conn_cipher&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help