noble (3) tls_connect.3.gz

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