Sortix 1.1dev nightly manual
This manual documents Sortix 1.1dev nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
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 returns the amount of data read.
tls_write
() writes
buflen bytes of data from
buf to the socket. It returns the amount of
data written.
tls_handshake
() explicitly performs the TLS
handshake. It is only necessary to call this function if you need to guarantee
that the handshake 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 descriptors, 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.
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
trying to assemble the string describing the most recent error related to
ctx.
EXAMPLES
The following example demonstrates how to handle TLS writes on a blocking 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; } ...
... 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
() appeared 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 fromBob Beck <beck@openbsd.org>
CAVEATS
The functiontls_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. Consequently, if the application may
need the message at a later time, it has to copy the string before calling the
next libtls function involving
ctx, or a segmentation fault or read access
to unintended data is the likely result.July 9, 2019 | Debian |