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

FreeBSD Manual Pages

  
 
  

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

NAME
       tls_read,  tls_write, tls_handshake, tls_error, tls_close, tls_reset --
       use a TLS connection

SYNOPSIS
       #include	<tls.h>

       ssize_t
       tls_read(struct tls *ctx, void *buf, size_t buflen);

       ssize_t
       tls_write(struct	tls *ctx, const	void *buf, size_t buflen);

       int
       tls_handshake(struct tls	*ctx);

       const char *
       tls_error(struct	tls *ctx);

       int
       tls_close(struct	tls *ctx);

       void
       tls_reset(struct	tls *ctx);

DESCRIPTION
       tls_read() reads	buflen bytes of	data from the socket into buf.	It re-
       turns the amount	of data	read.

       tls_write() writes buflen bytes of data from buf	to the socket.	It re-
       turns the amount	of data	written.

       tls_handshake() explicitly performs the TLS handshake.  It is only nec-
       essary to call this function if you need	to guarantee  that  the	 hand-
       shake  has  completed, as both tls_read() and tls_write() automatically
       perform the TLS handshake when necessary.

       The tls_error() function	may be used to retrieve	 a  string  containing
       more information	about the most recent error relating to	a context.

       tls_close()  closes a connection	after use.  Only the TLS layer will be
       shut down and the caller	is responsible for closing the	file  descrip-
       tors,  unless  the  connection  was established using tls_connect(3) or
       tls_connect_servername(3).  After closing the connection,  ctx  can  be
       passed to tls_free(3).

RETURN VALUES
       tls_read() and tls_write() return a size	on success or -1 on error.

       tls_handshake() and tls_close() return 0	on success or -1 on error.

       The tls_read(), tls_write(), tls_handshake(), and tls_close() functions
       also have two special return values:

	     TLS_WANT_POLLIN   The underlying read file	descriptor needs to be
			       readable	in order to continue.
	     TLS_WANT_POLLOUT  The  underlying	write file descriptor needs to
			       be writeable in order to	continue.

       In the case of blocking file descriptors, the same function call	should
       be repeated immediately.	 In the	case of	non-blocking file descriptors,
       the same	function call should be	repeated when the  required  condition
       has been	met.

       Callers	of  these  functions  cannot  rely  on the value of the	global
       errno.	To  prevent  mishandling  of  error  conditions,   tls_read(),
       tls_write(),  tls_handshake(),  and  tls_close()	 all  explicitly clear
       errno.

       tls_error() returns NULL	if no error occurred with ctx during or	 since
       the last	call to	tls_handshake(), tls_read(), tls_write(), tls_close(),
       or tls_reset() involving	ctx, or	if memory allocation failed while try-
       ing  to assemble	the string describing the most recent error related to
       ctx.

EXAMPLES
       The following example demonstrates how to handle	TLS writes on a	block-
       ing file	descriptor:

	     ...
	     while (len	> 0) {
		     ssize_t ret;

		     ret = tls_write(ctx, buf, len);
		     if	(ret ==	TLS_WANT_POLLIN	|| ret == TLS_WANT_POLLOUT)
			     continue;
		     if	(ret ==	-1)
			     errx(1, "tls_write: %s", tls_error(ctx));
		     buf += ret;
		     len -= ret;
	     }
	     ...

       The following example demonstrates how to handle	TLS writes on  a  non-
       blocking	file descriptor	using poll(2):

	     ...
	     pfd[0].fd = fd;
	     pfd[0].events = POLLIN|POLLOUT;
	     while (len	> 0) {
		     nready = poll(pfd,	1, 0);
		     if	(nready	== -1)
			     err(1, "poll");
		     if	((pfd[0].revents & (POLLERR|POLLNVAL)))
			     errx(1, "bad fd %d", pfd[0].fd);
		     if	((pfd[0].revents & (pfd[0].events|POLLHUP))) {
			     ssize_t ret;

			     ret = tls_write(ctx, buf, len);
			     if	(ret ==	TLS_WANT_POLLIN)
				     pfd[0].events = POLLIN;
			     else if (ret == TLS_WANT_POLLOUT)
				     pfd[0].events = POLLOUT;
			     else if (ret == -1)
				     errx(1, "tls_write: %s", tls_error(ctx));
			     else {
				     buf += ret;
				     len -= ret;
			     }
		     }
	     }
	     ...

SEE ALSO
       tls_accept_socket(3),	   tls_configure(3),	  tls_conn_version(3),
       tls_connect(3), tls_init(3), tls_ocsp_process_response(3)

HISTORY
       tls_read(), tls_write(),	tls_error(), tls_close(), and tls_reset()  ap-
       peared in OpenBSD 5.6 and got their final names in OpenBSD 5.7.

       tls_handshake() appeared	in OpenBSD 5.9.

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

CAVEATS
       The  function  tls_error() returns an internal pointer.	It must	not be
       freed by	the application, or a  double  free  error  will  occur.   The
       pointer	will become invalid when the next error	occurs with ctx.  Con-
       sequently, if the application may need the message at a later time,  it
       has  to copy the	string before calling the next libtls function involv-
       ing ctx,	or a segmentation fault	or read	access to unintended  data  is
       the likely result.

FreeBSD	Ports 14.quarterly	 July 9, 2019			   TLS_READ(3)

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

home | help