TLS_INIT(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

🎀 TLS_INIT(3) 🎀

okay so welcome to the Library Functions Manual entry for TLS_INIT(3) — the lil’ starting point for the tls crew. bestie, we’re gonna get you comfy with initializing the TLS client and server API, no cap. 💅

🌸 NAME 🌸

tls_init, tls_config_new, tls_config_free, tls_config_error — initialize TLS client and server API. 💖

✨ SYNOPSIS ✨

library “libtls” libssl libcrypto #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);

💫 DESCRIPTION 💫

The tls family is the secure-comms squad: it establishes a secure communications channel using the TLS socket protocol, and both clients and servers are supported. iconic.

tls_init() initializes global data structures. Lowkey you no longer have to call this function directly, because it gets invoked internally when needed. It may be called more than once, and it may be called concurrently. slay. ✨

Before a connection is created, a configuration must be created. tls_config_new() allocates, initializes, and returns a new default configuration object that can be used for future connections. There are several functions to change the options of the configuration — go peek at tls_config_set_protocols(3), tls_load_file(3), tls_config_ocsp_require_stapling(3), and tls_config_verify(3). iykyk. 🫶

tls_config_error() may be used to retrieve a string containing more information about the most recent error relating to a configuration.

A TLS connection object is created by tls_client(3) or tls_server(3) and 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 are provided for input and output: tls_read(3) and tls_write(3). Both automatically perform the tls_handshake(3) when needed. not me having to remember handshakes — they handle it. 💅

The properties of established TLS connections can be inspected with the functions described in tls_conn_version(3) and tls_ocsp_process_response(3).

After use, a TLS connection should be closed with tls_close(3) and then freed by calling tls_free(3). clean-up era. 🧹

When no more contexts are to be configured, the configuration object should be freed by calling tls_config_free(). It is safe to call tls_config_free() as soon as the final call to tls_configure() has been made. If config is NULL, no action occurs. periodt.

💖 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.
  • 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 👀

🕰️ 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. the way it said “not today” to awkward APIs. 💅

All functions were renamed from ressl_*() to tls_*() for OpenBSD 5.7.

tls_config_error() appeared in OpenBSD 6.0. documented glow-up. ✨

👑 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. bestie squad. 🫶

💀 CAVEATS 💀

okay this part is important, so listen up: the function tls_config_error() returns an internal pointer. It must not be freed by the application, or a double free error will occur. 😭 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, or a segmentation fault or read access to unintended data is the likely result. fr fr, do not skip the copy.

with love from Debian on July 7, 2025 — TLS_INIT(3) 💖🫶

📦 where this page comes from