zitilib.h File Reference

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

Go to the source code of this file.

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_load_context (ziti_handle_t *h, const char *identity)
	Load Ziti identity.
ziti_jwt_signer_array	Ziti_get_ext_signers (ziti_handle_t ztx)
	Get 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_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()

ziti_jwt_signer_array Ziti_get_ext_signers

(

ziti_handle_t

ztx

)

Get external signers available for authentication.

The result must be freed with [free_ziti_jwt_signer_array].

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_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