TLS_INIT(3)

💖 TLS_INIT(3) — Library Functions Manual 💖

okay bestie, sit down, hydrate, and let me tell you about tls_init(3) and its little config-creation crew from the Library Functions Manual. this is the ✨entry point✨ to the whole tls situation and honestly? she's iconic.

🌸 NAME 🌸

tls_init, tls_config_new, tls_config_free, tls_config_error — initialize the TLS client and server API 🎀

✨ SYNOPSIS ✨

#include <tls.h>

int
tls_init(void);

struct tls_config *
tls_config_new(void);

void
tls_config_free(struct tls_config *config);

const char *
tls_config_error(struct tls_config *config);

like. look at her. four little functions. so much power. 💅

🦋 DESCRIPTION 🦋

the tls family of functions establishes a secure communications channel using the TLS socket protocol. both clients AND servers are supported — equal opportunity secure comms, we love that for us 🫶

so here's the tea on each one:

• tls_init() — initializes global data structures. and here's the gag: it is no longer necessary to call this function directly, because it gets invoked internally when it's needed. she's the friend who shows up to the party uninvited but is genuinely helpful. you may call it more than once, and you may call it concurrently. no drama. 💅
• tls_config_new() — before a connection is created, a configuration must be created. this function allocates, initializes, and returns a brand new default configuration object that you can use for future connections. main character energy fr fr. several functions exist to change the options of the configuration — go check tls_config_set_protocols(3), tls_load_file(3), tls_config_ocsp_require_stapling(3), and tls_config_verify(3) for the full menu 🍓
• tls_config_error() — use this to retrieve a string with more info about the most recent error relating to a configuration. it's giving "bestie, what went wrong" 😭
• tls_config_free() — when no more contexts are to be configured, free the configuration object by calling this. it is safe to call tls_config_free() as soon as the final call to tls_configure() has been made. and if config is NULL? no action occurs. she simply ✨declines✨. periodt.

okay but here's the whole flow, because context is everything:

a TLS connection object is created by tls_client(3) or tls_server(3), and it gets configured with tls_configure(3).

a client connection is initiated after configuration by calling tls_connect(3). a server can accept a new client connection by calling tls_accept_socket(3) on an already established socket connection. 💫

two functions handle input and output: tls_read(3) and tls_write(3). both automatically perform the tls_handshake(3) when needed — they just do it, no asking, no drama, obsessed.

want to inspect the properties of established TLS connections? that's what the functions in tls_conn_version(3) and tls_ocsp_process_response(3) are for 🔍

after use, a TLS connection should be closed with tls_close(3) and then freed by calling tls_free(3). clean up after yourself bestie, we are not leaving a mess 🧚

💜 RETURN VALUES 💜

• tls_init() returns 0 on success or -1 on error.
• tls_config_new() returns NULL on error or an out of memory condition. (yes, even her. she's not perfect, she's just really good.)
• tls_config_error() returns NULL if no error occurred with config at all, or if memory allocation failed while trying to assemble the string describing the most recent error related to config.

🔥 SEE ALSO 🔥

tls_accept_socket(3), tls_client(3), tls_config_ocsp_require_stapling(3), tls_config_set_protocols(3), tls_config_verify(3), tls_conn_version(3), tls_connect(3), tls_load_file(3), tls_ocsp_process_response(3), tls_read(3)

the whole squad. iykyk 💅

🌈 HISTORY 🌈

the tls API first appeared in OpenBSD 5.6 as a response to the unnecessary challenges other APIs present in order to use them safely. yes, she was literally born because the other APIs were doing too much. we stan a problem-solver 👑

all functions were renamed from ressl_*() to tls_*() for OpenBSD 5.7. glow-up of the century.

tls_config_error() appeared in OpenBSD 6.0. late arrival, still ate. 💖

👑 AUTHORS 👑

Joel Sing <jsing@openbsd.org> Ted Unangst <tedu@openbsd.org>

many others contributed to various parts of the library; see the individual manual pages for more information. a whole group project and they all showed up. 🫶

💀 CAVEATS 💀

okay this is the part where we get serious, because this one bites:

the function tls_config_error() returns an internal pointer. it must not be freed by the application, or a double free error will occur.

and it gets worse bestie 😭 the pointer will become invalid when the next error occurs with config. consequently, if the application may need the message at a later time, it has to copy the string before calling the next libtls function involving config — otherwise a segmentation fault or read access to unintended data is the likely result. not a vibe. copy the string. i'm begging. 🙈

and that's the whole page, babes — this one came to you from the Debian packaging, dated July 9, 2018, filed under the Library Functions Manual. stay secure, free your configs, and never ever free that internal pointer. mwah 💋