TLS_CONNECT(3)

💖 TLS_CONNECT(3) — the libtls client-connection glow-up ✨

okay so this is the Library Functions Manual moment for libtls — the page where you learn how to tell a TLS client to go make a connection. no cap, it's a whole vibe. 🦋

---

🌸 NAME 🌸

tls_connect, tls_connect_fds, tls_connect_servername, tls_connect_socket, tls_connect_cbs — instruct a TLS client to establish a connection

like, all five of these besties do the same general job: get your client connected and secure. 💅

---

✨ SYNOPSIS ✨

library “libtls” libssl libcrypto

#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 🎀

so the whole storyline here is: first you create a TLS client context with tls_client(3), then you configure it with tls_configure(3), and then — the main character moment — you kick off the client connection by calling tls_connect(). 👑

tls_connect() 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's NULL, then a host of the format "hostname:port" is permitted. the name used for verification is inferred from the host value. slay. 💅

tls_connect_servername() has the same behaviour, except the name used for verification is explicitly provided — which is literally perfect for the case where the TLS server name differs from the DNS name. iykyk. 🧚

and if you already have a socket sitting there and you're like "can we make this secure pls"? yes bestie — 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(). two fds, one secure vibe. 🫶

calling tls_connect_cbs() lets read and write callback functions handle data transfers. the specified cb_arg parameter is passed back to the functions, and can contain a pointer to any caller-specified data. very much "bring your own data" energy. 🌈

---

🌟 RETURN VALUES 🌟

these functions return 0 on success or -1 on error. periodt.

---

🦋 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 these too, they're all part of the same little ecosystem bestie 💜

---

🔥 HISTORY 🔥

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

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>

and tls_connect_cbs() was written by Tobias Pape <tobias@netshed.de>. icons, all of them 👑

---

and that's the page, bestie — brought to you by Debian, dated July 7, 2025, filed under TLS_CONNECT(3). mwah 💋✨