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>.

Debian                                            July 9, 2018                                    TLS_CONNECT(3)