#include "externs.h"
#include "errors.h"
#include "enums.h"
#include <stdint.h>
#include <netinet/in.h>

Macros
#define	ZITI_INVALID_HANDLE ((ziti_handle_t)-1)

Typedefs
typedef uint32_t	ziti_handle_t

typedef int	ziti_socket_t

Functions
void	Ziti_lib_init (void)
	Initialize Ziti library.

int	Ziti_last_error (void)
	return Ziti error code for last failed operation.

int	Ziti_enroll_identity (const char jwt, const char key, const char cert, char id_json, unsigned long id_json_len)
	enroll a new Ziti identity

int	Ziti_enroll_controller (const char url, const char jwt, ziti_enroll_mode mode, char *id_json, unsigned long id_json_len)
	Enroll or authenticate a Ziti identity via a controller URL.

int	Ziti_load_context (ziti_handle_t h, const char identity)
	Load Ziti identity.

int	Ziti_load_context_with_timeout (ziti_handle_t h, const char identity, int timeout_ms)
	Load Ziti identity with timeout control.

const char const	Ziti_get_ext_signers (ziti_handle_t ztx)
	Get the names of external signers available for authentication.

char *	Ziti_login_external (ziti_handle_t ztx, const char *signer_name)
	Start external login process.

int	Ziti_login_totp (ziti_handle_t ztx, const char *code)
	Login with TOTP code.

int	Ziti_wait_for_auth (ziti_handle_t ztx, int timeout_ms)
	Wait for authentication to complete.

ziti_socket_t	Ziti_socket (int type)
	creates a socket handle(Windows) or file descriptor(*nix) suitable for connecting to a Ziti service

int	Ziti_close (ziti_socket_t socket)
	close the given socket handle/file descriptor.

int	Ziti_check_socket (ziti_socket_t socket)
	Check if the given socket handle/fd is attached to a Ziti connection via `Ziti_connect()`/`Ziti_bind()`

int	Ziti_connect (ziti_socket_t socket, ziti_handle_t ztx, const char service, const char terminator)
	Connect socket to a Ziti service.

int	Ziti_connect_addr (ziti_socket_t socket, const char *host, unsigned int port)
	Connect socket to a Ziti service with the given intercept address.

int	Ziti_bind (ziti_socket_t socket, ziti_handle_t ztx, const char service, const char terminator)
	Bind socket to a Ziti service.

int	Ziti_listen (ziti_socket_t socket, int backlog)
	marks the [socket] as a socket able to accept incoming connections

ziti_socket_t	Ziti_accept (ziti_socket_t socket, char *caller, int caller_len)
	accept a client Ziti connection as a socket

void	Ziti_lib_shutdown (void)
	Shutdown Ziti library.

Macro Definition Documentation

◆ ZITI_INVALID_HANDLE

#define ZITI_INVALID_HANDLE ((ziti_handle_t)-1)

Typedef Documentation

◆ ziti_handle_t

typedef uint32_t ziti_handle_t

◆ ziti_socket_t

typedef int ziti_socket_t

Function Documentation

◆ Ziti_accept()

ziti_socket_t Ziti_accept	(	ziti_socket_t	socket,
		char *	caller,
		int	caller_len
	)

accept a client Ziti connection as a socket

Extracts the first [ziti_connection] from pending queue, accepts it, and opens a new socket fd for it.

If no pending connection requests are present, behavior depends on whether [socket] is marked non-blocking.

marked as non-blocking: fails with error code EAGAIN or EWOULDBLOCK.
not marked as non-blocking: blocks until a connection request is present.

Parameters

socket	socket created with [Ziti_socket()], bound to a service with [Ziti_bind()] or [Ziti_bind_addr()], and is listening after [Ziti_listen()]
caller	buffer to store caller ID (dialing identity name)
caller_len	length of the [caller] buffer

Returns: on success returns a file descriptor for the accepted connection. on error -1 is returned, use [Ziti_last_error()] to get actual error code.

◆ Ziti_bind()

int Ziti_bind	(	ziti_socket_t	socket,
		ziti_handle_t	ztx,
		const char *	service,
		const char *	terminator
	)

Bind socket to a Ziti service.

Parameters

socket	socket handle created with [Ziti_socket()]
ztx	Ziti context
service	service name provided by [ztx]
terminator	(optional) create specific terminator

Returns: 0 on success, negative error code on failure

◆ Ziti_check_socket()

int Ziti_check_socket ( ziti_socket_t socket )

Check if the given socket handle/fd is attached to a Ziti connection via Ziti_connect()/Ziti_bind()

Parameters

socket

Returns: 0 - not a ziti socket, 1 - connected ziti socket, 2 - ziti server socket

◆ Ziti_close()

int Ziti_close ( ziti_socket_t socket )

close the given socket handle/file descriptor.

This method facilitates faster cleanup of Ziti socket. Calling standard close()/closesocket() methods still works but may lead to race conditions.

Parameters

socket

◆ Ziti_connect()

int Ziti_connect	(	ziti_socket_t	socket,
		ziti_handle_t	ztx,
		const char *	service,
		const char *	terminator
	)

Connect socket to a Ziti service.

Parameters

socket	socket handle created with [Ziti_socket()]
ztx	Ziti context handle
service	service name provided by [ztx]
terminator	(optional) specific terminator to connect to

Returns: 0 on success, negative error code on failure

◆ Ziti_connect_addr()

int Ziti_connect_addr	(	ziti_socket_t	socket,
		const char *	host,
		unsigned int	port
	)

Connect socket to a Ziti service with the given intercept address.

Parameters

socket	socket handle created with [Ziti_socket()]
host	target hostname
port	target port

Returns

◆ Ziti_enroll_controller()

int Ziti_enroll_controller	(	const char *	url,
		const char *	jwt,
		ziti_enroll_mode	mode,
		char **	id_json,
		unsigned long *	id_json_len
	)

Enroll or authenticate a Ziti identity via a controller URL.

Bootstraps a Ziti identity from a controller URL. Behavior depends on the enrollment mode:

ziti_enroll_none: returns the bootstrap config (CA + controller URL) immediately, no OIDC authentication.
ziti_enroll_token: performs OIDC authentication, auto-creates identity on the controller (no CSR). Returns config without cert/key.
ziti_enroll_cert: performs OIDC authentication, generates a CSR, and exchanges the OIDC token + CSR for a client certificate.

If jwt is NULL, the network JWT is fetched from the controller's /network-jwts endpoint, which requires the controller's TLS certificate to be verifiable by the OS trust store (publicly-trusted CA).

If jwt is provided (obtained out of band), it is used directly to verify the controller, allowing privately-signed controllers.

This is a blocking call.

Parameters

url	controller URL (e.g., "https://ctrl.example.com:1280")
jwt	network JWT string, or NULL to fetch from controller
mode	enrollment mode (ziti_enroll_none, ziti_enroll_cert, ziti_enroll_token)
id_json	(output) identity in JSON format, caller is responsible for freeing it
id_json_len	(output) length of id_json

Returns: ZITI_OK on success, error code on failure

◆ Ziti_enroll_identity()

int Ziti_enroll_identity	(	const char *	jwt,
		const char *	key,
		const char *	cert,
		char **	id_json,
		unsigned long *	id_json_len
	)

enroll a new Ziti identity

Parameters

jwt	enrollment token
key	private key (required for third party CA enrollment, otherwise optional)
cert	identity x.509 certificate (required for third party CA enrollment, otherwise ignored)
id_json	(output) identity in JSON format, caller is responsible for freeing it
id_json_len	(output) length of id_json

Returns: ZITI_OK on success, error code on failures

◆ Ziti_get_ext_signers()

const char *const * Ziti_get_ext_signers ( ziti_handle_t ztx )

Get the names of external signers available for authentication.

Returns: a dynamically allocated array of ziti_jwt_signer pointers, terminated with NULL.

◆ Ziti_last_error()

int Ziti_last_error ( void )

return Ziti error code for last failed operation.

Use [ziti_errorstr] to get error message.

Returns

◆ Ziti_lib_init()

void Ziti_lib_init ( void )

Initialize Ziti library.

Creates a background processing thread for Ziti processing.

◆ Ziti_lib_shutdown()

void Ziti_lib_shutdown ( void )

Shutdown Ziti library.

All loaded contexts are shutdown and background thread is terminated.

◆ Ziti_listen()

int Ziti_listen	(	ziti_socket_t	socket,
		int	backlog
	)

marks the [socket] as a socket able to accept incoming connections

Parameters

socket	a file descriptor created with [Ziti_socket()] and bound to a service with [Ziti_bind] or [Ziti_bind_addr]
backlog	maximum size of the queue of pending connections.

Returns: On success, 0 is returned. On error -1, is returned and [Ziti_last_error()] is set to actual code.

◆ Ziti_load_context()

int Ziti_load_context	(	ziti_handle_t *	h,
		const char *	identity
	)

Load Ziti identity.

First it tries to parse [identity] as identity Json. if that fails it tries to load it from file using [identity] as the path.

Ziti identity handle is returned to [h] on success or if additional authentication is required if passed [identity] parameter is deemed invalid the handle is set to [ZITI_INVALID_HANDLE] and error code is returned.

Parameters

h	pointer to ziti_handle_t to be initialized
identity	identity config JSON or path to a file.

Returns: [ZITI_OK] success, returned handle can be used to access/bind ziti services [ZITI_EXTERNAL_LOGIN_REQUIRED] if the identity requires external login, application must call [Ziti_get_ext_signers] to get available external signers and then call [Ziti_login_external] with the selected signer name. [ZITI_PARTIALLY_AUTHENTICATED] if the identity is partially authenticated and requires additional authentication (TOTP) [ZITI_MFA_NOT_ENROLLED] if the identity is not enrolled in MFA but is required for authentication [ZITI_INVALID_STATE] if [h] is NULL [ZITI_INVALID_CONFIG] if [identity] is not a valid Ziti identity JSON

◆ Ziti_load_context_with_timeout()

int Ziti_load_context_with_timeout	(	ziti_handle_t *	h,
		const char *	identity,
		int	timeout_ms
	)

Load Ziti identity with timeout control.

Same as Ziti_load_context but with a timeout parameter to control how long the context loading process should wait for API calls to complete. This helps prevent indefinite retries when endpoints are not reachable.

Parameters

h	pointer to ziti_handle_t to be initialized
identity	identity config JSON or path to a file.
timeout_ms	timeout in milliseconds for context loading operations. If 0, uses default behavior (no timeout). If > 0, context loading will fail with ZITI_TIMEOUT if not completed within this time.

Returns: [ZITI_OK] success, returned handle can be used to access/bind ziti services [ZITI_EXTERNAL_LOGIN_REQUIRED] if the identity requires external login, application must call [Ziti_get_ext_signers] to get available external signers and then call [Ziti_login_external] with the selected signer name. [ZITI_PARTIALLY_AUTHENTICATED] if the identity is partially authenticated and requires additional authentication (TOTP) [ZITI_MFA_NOT_ENROLLED] if the identity is not enrolled in MFA but is required for authentication [ZITI_TIMEOUT] if context loading did not complete within the specified timeout [ZITI_INVALID_STATE] if [h] is NULL [ZITI_INVALID_CONFIG] if [identity] is not a valid Ziti identity JSON

◆ Ziti_login_external()

char * Ziti_login_external	(	ziti_handle_t	ztx,
		const char *	signer_name
	)

Start external login process.

This method is used to start the external login process for the given Ziti context. It will return a URL that the application should prompt user to open in their browser to complete the authentication.

the returned URL must be freed with free().

Parameters

ztx	Ziti context handle
signer_name	name of the external JWT signer to use

Returns: URL to be opened in a browser, or NULL on error.

◆ Ziti_login_totp()

int Ziti_login_totp	(	ziti_handle_t	ztx,
		const char *	code
	)

Login with TOTP code.

This method is used to complete the authentication process by providing a TOTP code. It should be called after the user has entered their TOTP code.

Parameters

ztx	Ziti context handle
code	TOTP code provided by the user

Returns: 0 on success, error code on failure

◆ Ziti_socket()

ziti_socket_t Ziti_socket ( int type )

creates a socket handle(Windows) or file descriptor(*nix) suitable for connecting to a Ziti service

Parameters

type	socket type which defines communication semantics, only SOCK_STREAM and SOCK_DGRAM are supported at this time (see socket(2))

Returns: native socket handle

◆ Ziti_wait_for_auth()

int Ziti_wait_for_auth	(	ziti_handle_t	ztx,
		int	timeout_ms
	)

Wait for authentication to complete.

This method blocks until the authentication is completed or the timeout is reached. If the authentication is successful, it returns 0, otherwise it returns a negative error code.

Parameters

ztx	Ziti context handle
timeout_ms	timeout in milliseconds, 0 means no timeout

Returns: 0 on success, negative error code on failure

Macros

Typedefs

Functions

Macro Definition Documentation

◆ ZITI_INVALID_HANDLE

Typedef Documentation

◆ ziti_handle_t

◆ ziti_socket_t

Function Documentation

◆ Ziti_accept()

◆ Ziti_bind()

◆ Ziti_check_socket()

◆ Ziti_close()

◆ Ziti_connect()

◆ Ziti_connect_addr()

◆ Ziti_enroll_controller()

◆ Ziti_enroll_identity()

◆ Ziti_get_ext_signers()

◆ Ziti_last_error()

◆ Ziti_lib_init()

◆ Ziti_lib_shutdown()

◆ Ziti_listen()

◆ Ziti_load_context()

◆ Ziti_load_context_with_timeout()

◆ Ziti_login_external()

◆ Ziti_login_totp()

◆ Ziti_socket()

◆ Ziti_wait_for_auth()