TLS_CONNECT(3)

✨ TLS_CONNECT(3) — the tls_connect girlies 💖

ok so this is from the Library Functions Manual, and it's literally the whole tls_connect family. bestie, we're about to make your TLS client go get a connection. slay.

🌸 NAME 🌸

tls_connect, tls_connect_fds, tls_connect_servername, tls_connect_socket, tls_connect_cbs — telling a TLS client to go establish a connection, fr fr

🎀 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);

like. look at all those little functions. one of them is your moment, you just gotta pick. 💅

🦋 DESCRIPTION 🦋

okay so picture this: you already made a TLS client context with tls_client(3) and you already configured it with tls_configure(3). iconic. now it's time to actually connect, and that's what tls_connect() is for.

Here's the whole vibe: tls_connect() will create a new socket, connect to the specified host and port, and then establish a secure connection. the port can be numeric or a service name — flexible queen. and if it's NULL? then a host of the format "hostname:port" is permitted. cute. the name to use for verification is inferred from the host value.

Then we have tls_connect_servername() — same behaviour, same energy, but the name to use for verification is explicitly provided. this is for the case where the TLS server name differs from the DNS name. iykyk, sometimes the vibe check name and the address name are just not the same person. 🙈

Got an already existing socket and you want to glow it up? tls_connect_socket() upgrades it to a secure connection. instant main character energy. ✨

Alternatively — and this is lowkey the cool one — a secure connection can be established over a pair of existing file descriptors by calling tls_connect_fds().

And then there's tls_connect_cbs(), which lets read and write callback functions handle data transfers. the specified cb_arg parameter is passed back to the functions, and it can contain a pointer to any caller-specified data. so you can just... put your little stuff in there. obsessed. 🫶

💖 RETURN VALUES 💖

these functions return 0 on success or -1 on error. that's it, that's the whole story. zero means we ate, negative one means we did not. 😭

🌈 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)

go read the friends, they're all part of the same friend group. 👑

⭐ HISTORY ⭐

tls_connect() and tls_connect_socket() appeared in OpenBSD 5.6 and got their final names in OpenBSD 5.7. glow-up era. 💅

tls_connect_fds() and tls_connect_servername() appeared in OpenBSD 5.7, and tls_connect_cbs() in OpenBSD 6.1. the family kept growing, as it should. 🦋

👑 AUTHORS 👑

• Joel Sing <jsing@openbsd.org>
• Reyk Floeter <reyk@openbsd.org>

and tls_connect_cbs() was written by Tobias Pape <tobias@netshed.de> — special shoutout, we see you. 🎀

no cap, this whole page came from the Debian build, dated July 9, 2018. love that for us. mwah, take care of your connections bestie 💜🌸