zitilib.h File Reference

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

Go to the source code of this file.

Typedefs
typedef struct ziti_ctx *	ziti_context
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
ziti_context	Ziti_load_context (const char *identity)
	Load Ziti identity.
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_context 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_context 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.

Typedef Documentation

ziti_context

typedef struct ziti_ctx* ziti_context

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_context	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_context	ztx,
		const char *	service,
		const char *	terminator
	)

Connect socket to a Ziti service.

Parameters

socket	socket handle created with [Ziti_socket()]
ztx	Ziti context
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_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()

ziti_context Ziti_load_context

(

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.

returns NULL in case of failure. [Ziti_last_error()] will give specific error code.

Parameters

identity

identity config JSON or path to a file.

Returns

Ziti Context handle or NULL if it fails

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