NAME
tls_connect,
tls_connect_fds,
tls_connect_servername,
tls_connect_socket,
tls_connect_cbs —
instruct a TLS client to establish a
connection
SYNOPSIS
#include
<tls.h>
int
tls_connect(struct tls *ctx,
const char *host, const char
*port);
int
tls_connect_fds(struct tls *ctx,
int fd_read, int fd_write,
const char *servername);
int
tls_connect_servername(struct tls
*ctx, const char *host, const
char *port, const char *servername);
int
tls_connect_socket(struct tls
*ctx, int s, const char
*servername);
int
tls_connect_cbs(struct tls *ctx,
ssize_t (*tls_read_cb)(struct tls *ctx, void *buf, size_t
buflen, void *cb_arg), ssize_t (*tls_write_cb)(struct
tls *ctx, const void *buf, size_t buflen, void *cb_arg),
void *cb_arg, const char
*servername);
DESCRIPTION
After creating a TLS client context with
tls_client(3) and configuring it with
tls_configure(3), a client connection is initiated by calling
tls_connect().
This function will create a new socket, connect to the specified
host and port, and then
establish a secure connection. The port may be numeric
or a service name. If it is NULL, then a
host of the format "hostname:port" is
permitted. The name to use for verification is inferred from the
host value.
The
tls_connect_servername()
function has the same behaviour, however the name to use for verification is
explicitly provided, for the case where the TLS server name differs from the
DNS name.
An already existing socket can be upgraded
to a secure connection by calling
tls_connect_socket().
Alternatively, a secure connection can be
established over a pair of existing file descriptors by calling
tls_connect_fds().
Calling
tls_connect_cbs()
allows read and write callback functions to handle data transfers. The
specified cb_arg parameter is passed back to the functions, and can contain
a pointer to any caller-specified data.
RETURN VALUES
These functions return 0 on success or -1 on error.
SEE ALSO
tls_accept_socket(3), tls_client(3), tls_close(3), tls_config_ocsp_require_stapling(3), tls_configure(3), tls_handshake(3), tls_init(3)
HISTORY
tls_connect() and
tls_connect_socket() appeared in
OpenBSD 5.6 and got their final names in
OpenBSD 5.7.
tls_connect_fds() and
tls_connect_servername() appeared in
OpenBSD 5.7 and
tls_connect_cbs() in OpenBSD
6.1.
AUTHORS
Joel Sing
<jsing@openbsd.org>
Reyk Floeter
<reyk@openbsd.org>
tls_connect_cbs() was written by
Tobias Pape
<tobias@netshed.de>.