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 -- in-
     spect 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 negoti-
     ated with the peer connected to ctx.

     tls_conn_cipher() returns a string corresponding to the cipher suite  nego-
     tiated 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 se-
     lected 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  Indica-
     tion 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 certifi-
     cate.

     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-en-
     coded 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 re-
     sumed 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  mem-
     ory condition.

SEE ALSO
     tls_configure(3),	 tls_handshake(3),   tls_init(3),   tls_ocsp_process_re-
     sponse(3)

HISTORY
     tls_conn_version(),      tls_conn_cipher(),       tls_peer_cert_provided(),
     tls_peer_cert_contains_name(),  tls_peer_cert_issuer(),  tls_peer_cert_sub-
     ject(),	  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 15.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_peer_cert_contains_name&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help