Defines the macros, functions, typedefs and constants required to interface with a Ziti Network. More...

#include <stdint.h>
#include <tlsuv/tlsuv.h>
#include <uv.h>
#include "errors.h"
#include "externs.h"
#include "ziti_model.h"
#include "enums.h"
#include "ziti_events.h"
#include "enroll.h"

Data Structures
struct	ziti_options
	ziti_context runtime options More...

struct	ziti_dial_opts

struct	ziti_client_ctx

struct	ziti_listen_opts

Macros
#define	ZITI_CAN_DIAL 1U
	Flag indicating service `Dial` permission.

#define	ZITI_CAN_BIND 2U
	Flag indicating service `Bind` permission.

#define	ZITI_DEFAULT_TIMEOUT 10000
	The default timeout in milliseconds for connection operations to succeed.

Typedefs
typedef struct ziti_ctx *	ziti_context
	Represents the Ziti Edge identity context.

typedef struct ziti_conn *	ziti_connection
	Represents a Ziti connection.

typedef void(*	ziti_service_cb) (ziti_context ztx, const ziti_service , int status, void data)
	Service status callback.

typedef void(*	ziti_pr_mac_cb) (ziti_context ztx, const char id, char *mac_addresses, int num_mac)
	Posture response MAC address callback.

typedef void(*	ziti_pq_mac_cb) (ziti_context ztx, const char *id, ziti_pr_mac_cb response_cb)
	Posture Query for MAC addresses callback.

typedef void(*	ziti_pr_domain_cb) (ziti_context ztx, const char id, const char domain)
	Posture response Domain callback.

typedef void(*	ziti_pq_domain_cb) (ziti_context ztx, const char *id, ziti_pr_domain_cb response_cb)
	Posture Query for Domain callback.

typedef void(*	ziti_pr_os_cb) (ziti_context ztx, const char id, const char os_type, const char os_version, const char os_build)
	Posture response OS callback.

typedef void(*	ziti_pq_os_cb) (ziti_context ztx, const char *id, ziti_pr_os_cb response_cb)
	Posture Query for OS callback.

typedef void(*	ziti_pr_process_cb) (ziti_context ztx, const char id, const char path, bool is_running, const char sha_512_hash, char *signers, int num_signers)
	Posture response process callback.

typedef void(*	ziti_pq_process_cb) (ziti_context ztx, const char id, const char path, ziti_pr_process_cb response_cb)
	Posture Query for process callback.

typedef void(*	ziti_event_cb) (ziti_context ztx, const ziti_event_t *event)
	Ziti Event callback.

typedef ssize_t(*	ziti_data_cb) (ziti_connection conn, const uint8_t *data, ssize_t length)
	Data callback.

typedef void(*	ziti_conn_cb) (ziti_connection conn, int status)
	Connection callback.

typedef void(*	ziti_client_cb) (ziti_connection serv, ziti_connection client, int status, const ziti_client_ctx *ctx)
	Callback called when client connects to a service hosted by given context.

typedef ziti_conn_cb	ziti_listen_cb
	Defines the ziti_listen_cb.

typedef void(*	ziti_write_cb) (ziti_connection conn, ssize_t status, void *write_ctx)
	Callback called after ziti_write() is complete.

typedef void(*	ziti_close_cb) (ziti_connection conn)
	Callback called after connection was closed.

typedef void(*	ziti_ext_signers_cb) (ziti_context, int err, ziti_jwt_signer_array, void *)

typedef void(*	ziti_mfa_enroll_cb) (ziti_context ztx, int status, ziti_mfa_enrollment mfa_enrollment, void ctx)
	Callback called after ziti_mfa_enroll()

typedef void(*	ziti_mfa_cb) (ziti_context ztx, int status, void *ctx)
	Generic callback called after various MFA functions.

typedef void(*	ziti_mfa_recovery_codes_cb) (ziti_context ztx, int status, const char *recovery_codes, void ctx)
	Callback called after ziti_mfa_get_recovery_codes() and ziti_mfa_new_recovery_codes()

typedef void(*	ziti_extend_cert_authenticator_cb) (ziti_context ztx, const char cert_pem, int status, void ctx)
	Extend Certificate Authenticator Callback.

typedef void(*	ziti_verify_extend_cert_authenticator_cb) (ziti_context ztx, int status, void *ctx)
	Verify Extend Certificate Authenticator Callback.

Functions
void	ziti_set_app_info (const char app_id, const char app_version)
	Provide app information to Ziti SDK.

int	ziti_load_config (ziti_config config, const char conf_str)
	Load ziti identity config from memory or file.

int	ziti_context_init (ziti_context ztx, const ziti_config config)

int	ziti_context_set_options (ziti_context ztx, const ziti_options *options)

int	ziti_context_run (ziti_context ztx, uv_loop_t *loop)

int	ziti_refresh (ziti_context ztx)
	Trigger refresh ahead of normal refresh cycle.

bool	ziti_is_enabled (ziti_context ztx)
	return if context is enabled

void	ziti_set_enabled (ziti_context ztx, bool enabled)
	Enable or disable given Ziti context.

void *	ziti_app_ctx (ziti_context ztx)
	returns ziti_options.app_ctx for the given Ziti context.

const ziti_version *	ziti_get_version ()
	return SDK version

const ziti_version *	ziti_get_controller_version (ziti_context ztx)
	return Ziti controller version for given context

const char *	ziti_get_controller (ziti_context ztx)
	controller URL of the given context

const ziti_identity *	ziti_get_identity (ziti_context ztx)
	Ziti identity of the given context.

int	ziti_get_ext_jwt_signers (ziti_context ztx, ziti_ext_signers_cb cb, void *ctx)
	Get a list of available external JWT signers.

int	ziti_use_ext_jwt_signer (ziti_context ztx, const char *name)
	select external JWT signer to initiate OIDC authentication flow

int	ziti_get_transfer_rates (ziti_context ztx, double up, double down)
	Retrieve current transfer rates.

int	ziti_shutdown (ziti_context ztx)
	Shutdown Ziti Edge identity context and reclaim the memory from the provided ziti_context.

void	ziti_dump (ziti_context ztx, int(printer)(void ctx, const char fmt,...), void ctx)
	Shutdown Ziti Edge identity context and reclaim the memory from the provided ziti_context.

const char *	ziti_get_appdata_raw (ziti_context ztx, const char *key)

int	ziti_get_appdata (ziti_context ztx, const char key, void data, int(parse_func)(void , const char *, size_t))

int	ziti_conn_init (ziti_context ztx, ziti_connection conn, void data)
	Initializes a connection.

ziti_context	ziti_conn_context (ziti_connection conn)
	Return Ziti context for given connection.

void *	ziti_conn_data (ziti_connection conn)
	Retrieves any custom data associated with the given ziti_connection.

void	ziti_conn_set_data (ziti_connection conn, void *data)
	Set or clear custom data associated with the given ziti_connection.

int	ziti_conn_set_data_cb (ziti_connection conn, ziti_data_cb cb)
	Set new data callback on ziti connection.

const char *	ziti_conn_source_identity (ziti_connection conn)
	Get the identity of the client that initiated the ziti_connection.

int	ziti_service_available (ziti_context ztx, const char service, ziti_service_cb cb, void ctx)
	Checks availability of the service for the given edge context.

const ziti_service *	ziti_service_for_addr_str (ziti_context ztx, ziti_protocol proto, const char *addr, int port)

const ziti_service *	ziti_service_for_addr (ziti_context ztx, ziti_protocol proto, const ziti_address *addr, int port)

int	ziti_dial (ziti_connection conn, const char *service, ziti_conn_cb cb, ziti_data_cb data_cb)
	Establishes connection to a Ziti service.

int	ziti_dial_with_options (ziti_connection conn, const char service, ziti_dial_opts dial_opts, ziti_conn_cb cb, ziti_data_cb data_cb)

int	ziti_listen (ziti_connection serv_conn, const char *service, ziti_listen_cb lcb, ziti_client_cb cb)
	Start accepting ziti client connections.

int	ziti_listen_with_options (ziti_connection serv_conn, const char service, ziti_listen_opts listen_opts, ziti_listen_cb lcb, ziti_client_cb cb)

int	ziti_accept (ziti_connection clt, ziti_conn_cb cb, ziti_data_cb data_cb)
	Completes client connection.

int	ziti_close (ziti_connection conn, ziti_close_cb close_cb)
	Closes the given connection.

int	ziti_close_write (ziti_connection conn)
	Closes the outgoing (write) side of the given ziti connection.

int	ziti_write (ziti_connection conn, uint8_t data, size_t length, ziti_write_cb write_cb, void write_ctx)
	Send data to the connection peer.

int	ziti_conn_bridge (ziti_connection conn, uv_handle_t *handle, uv_close_cb on_close)
	Bridge [ziti_connection] to a given IO stream.

int	ziti_conn_bridge_idle_timeout (ziti_connection conn, unsigned long millis)
	set idle timeout on bridged connection.

int	ziti_conn_bridge_fds (ziti_connection conn, uv_os_fd_t input, uv_os_fd_t output, void(close_cb)(void ctx), void *ctx)
	Bridge [ziti_connection] to given IO file descriptors.

void	ziti_mfa_enroll (ziti_context ztx, ziti_mfa_enroll_cb enroll_cb, void *ctx)
	Attempts to initialize MFA enrollment.

void	ziti_mfa_remove (ziti_context ztx, const char code, ziti_mfa_cb remove_cb, void ctx)
	Attempts to remove MFA.

void	ziti_mfa_verify (ziti_context ztx, char code, ziti_mfa_cb verify_cb, void ctx)
	Attempts to verify MFA enrollment.

void	ziti_mfa_get_recovery_codes (ziti_context ztx, const char code, ziti_mfa_recovery_codes_cb get_cb, void ctx)
	Attempts to retrieve the current recovery codes for the identity.

void	ziti_mfa_new_recovery_codes (ziti_context ztx, char code, ziti_mfa_recovery_codes_cb new_cb, void ctx)
	Attempts to generate new recovery codes and retrieve the new recovery codes for MFA.

void	ziti_mfa_auth (ziti_context ztx, const char code, ziti_mfa_cb auth_cb, void ctx)
	Attempt to submit an MFA code for evaluation.

int	ziti_ext_auth (ziti_context ztx, void(ziti_ext_launch)(ziti_context, const char url, void ), void ctx)

int	ziti_ext_auth_token (ziti_context ztx, const char *token)

void	ziti_endpoint_state_change (ziti_context ztx, bool woken, bool unlocked)
	Alerts that the host running the `ziti_context` has undergone a state change.

int	ziti_extend_cert_authenticator (ziti_context ztx, const char csr_pem, ziti_extend_cert_authenticator_cb cb, void ctx)
	Attempts extend the lifetime of a 1st party client certificate (issued by the Ziti Controller)

int	ziti_verify_extend_cert_authenticator (ziti_context ztx, const char new_cert, ziti_verify_extend_cert_authenticator_cb cb, void ctx)
	Called in response to a ziti_extend_cert_authenticator_cb to verify a new client certificate.

int	ziti_set_client_cert (ziti_context ztx, const char cert_buf, size_t cert_len, const char key_buf, size_t key_len)
	Updates the certificate context for the ZTX with a new client certificate and key.

Detailed Description

Defines the macros, functions, typedefs and constants required to interface with a Ziti Network.

Macro Definition Documentation

◆ ZITI_CAN_BIND

#define ZITI_CAN_BIND 2U

Flag indicating service Bind permission.

◆ ZITI_CAN_DIAL

#define ZITI_CAN_DIAL 1U

Flag indicating service Dial permission.

◆ ZITI_DEFAULT_TIMEOUT

#define ZITI_DEFAULT_TIMEOUT 10000

The default timeout in milliseconds for connection operations to succeed.

Typedef Documentation

◆ ziti_client_cb

typedef void(* ziti_client_cb) (ziti_connection serv, ziti_connection client, int status, const ziti_client_ctx *ctx)

Callback called when client connects to a service hosted by given context.

This callback is invoked after ziti_listen() is completed. The result of the function may be an error condition so it is important to verify the status code in this callback. If successful the status will be set to ZITI_OK otherwise the value will be a value defined in #ZITI_ERRORS

Generally this callback is used for any preparations necessary before accepting incoming data from the Ziti network.

Parameters

serv	hosting connection, initialized with ziti_listen()
client	client connection - generally passed to ziti_accept() in this function
status	ZITI_OK or error
ctx	object containing application data passed by dialing identity,

See also: ziti_dial_opts. the reference to this object is only valid for the duration of the callback.; ziti_listen(), ZITI_ERRORS

◆ ziti_close_cb

typedef void(* ziti_close_cb) (ziti_connection conn)

Callback called after connection was closed.

Parameters

conn	connection that was closed

See also: ziti_close()

◆ ziti_conn_cb

typedef void(* ziti_conn_cb) (ziti_connection conn, int status)

Connection callback.

This callback is invoked after ziti_dial() or ziti_accept() is completed. The result of the function may be an error condition so it is important to verify the status code in this callback. If successful the status will be set to ZITI_OK.

Parameters

conn	the Ziti connection struct
status	the result of the function. ZITI_OK if successful otherwise see #ZITI_ERRORS

See also: ziti_dial(), ziti_accept(), ZITI_ERRORS

◆ ziti_connection

typedef struct ziti_conn* ziti_connection

Represents a Ziti connection.

The heart of Ziti is around reading and writing data securely and efficiently. In order to do that a connection is required which will allow a developer to do so. This pointer is passed to numerous Ziti C SDK functions and is returned in many callbacks. This structure is an opaque handle to the state necessary for the Ziti C SDK to function properly.

A connection is initialized by passing a pointer to ziti_conn_init(). The connection will need to be freed when no longer needed.

See also: ziti_conn_init(), ziti_close()

◆ ziti_context

typedef struct ziti_ctx* ziti_context

Represents the Ziti Edge identity context.

The Ziti C SDK will use this pointer to initialize and track the memory needed during normal usage. This structure is opaque to the API user but is necessary for normal Ziti SDK operation. After a successful initialization via ziti_context_init() the pointer will be initialized. The context is necessary for many of the C SDK functions and is passed as a parameter in many of the callbacks. ziti_shutdown() should be invoked when the Ziti connections are no longer needed. The Ziti C SDK will reclaim any allocated memory at this time.

See also: ziti_context_init(), ziti_shutdown()

◆ ziti_data_cb

typedef ssize_t(* ziti_data_cb) (ziti_connection conn, const uint8_t *data, ssize_t length)

Data callback.

This callback is invoked when data arrives at the Ziti C SDK. Data arrives in the Ziti C SDK either as a response to a Ziti connection from an ziti_dial() or as an incoming request via ziti_accept. Return value should indicate how much data was consumed by the application. This callback will be called again at some later time and as many times as needed for application to accept the rest.

Parameters

conn	The Ziti connection which received the data
data	incoming data buffer
length	size of data or error code as defined in #ZITI_ERRORS (will receive ZITI_EOF when connection is closed)

Returns: indicate how much data was consumed

See also: ziti_dial(), ziti_accept(), ZITI_ERRORS

◆ ziti_event_cb

typedef void(* ziti_event_cb) (ziti_context ztx, const ziti_event_t *event)

Ziti Event callback.

This callback is invoked when certain changes happen for a given ziti context. Subscription to events is managed by setting desired types on ziti_options.events field.

See also: ziti_event_type; ziti_event_t; ziti_options.event_cb; ziti_options.events

◆ ziti_ext_signers_cb

typedef void(* ziti_ext_signers_cb) (ziti_context, int err, ziti_jwt_signer_array, void *)

◆ ziti_extend_cert_authenticator_cb

typedef void(* ziti_extend_cert_authenticator_cb) (ziti_context ztx, const char *cert_pem, int status, void *ctx)

Extend Certificate Authenticator Callback.

This callback is invoked on the conclusion of ziti_extend_cert_authenticator(). The result of the function may be an error condition so it is important to verify the status code in this callback. In the event the certificate authenticator extension request cannot be completed an error will be returned otherwise ZITI_OK is expected.

See also: ziti_extend_cert_authenticator(), ZITI_ERRORS

◆ ziti_listen_cb

typedef ziti_conn_cb ziti_listen_cb

Defines the ziti_listen_cb.

A convenience to make the API align better when a human looks at it and as a place to change the listen callback in the unlikely event it is needed.

See also: ziti_listen()

◆ ziti_mfa_cb

typedef void(* ziti_mfa_cb) (ziti_context ztx, int status, void *ctx)

Generic callback called after various MFA functions.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
status	an error code or ZITI_OK
ctx	additional context to be passed into the original mfa call

◆ ziti_mfa_enroll_cb

typedef void(* ziti_mfa_enroll_cb) (ziti_context ztx, int status, ziti_mfa_enrollment *mfa_enrollment, void *ctx)

Callback called after ziti_mfa_enroll()

This function is invoked after a call to ziti_mfa_enroll. It will contain either a status error or an mfa_enrollment struct that will be free'ed after the call back finishes.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
status	an error code or ZITI_OK
mfa_enrollment	contents of the mfa enrollment or NULL if status is an error
ctx	additional context to be passed into ziti_mfa_enroll_cb callback

◆ ziti_mfa_recovery_codes_cb

typedef void(* ziti_mfa_recovery_codes_cb) (ziti_context ztx, int status, const char **recovery_codes, void *ctx)

Callback called after ziti_mfa_get_recovery_codes() and ziti_mfa_new_recovery_codes()

This function is invoked after a call to get or regenerate mfa recovery codes.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
status	an error code or ZITI_OK
recovery_codes	null terminated array of recovery codes
ctx	additional context to be passed into to the original call

◆ ziti_pq_domain_cb

typedef void(* ziti_pq_domain_cb) (ziti_context ztx, const char *id, ziti_pr_domain_cb response_cb)

Posture Query for Domain callback.

This callback is invoked when the Domain of the current host is needed. The callback will be supplied a followup callback to supply the host's domain.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
response_cb	the callback to invoke to supply values

See also: ziti_pr_domain_cb

◆ ziti_pq_mac_cb

typedef void(* ziti_pq_mac_cb) (ziti_context ztx, const char *id, ziti_pr_mac_cb response_cb)

Posture Query for MAC addresses callback.

This callback is invoked when the MAC addresses of the current host are needed. The callback will be supplied a followup callback to supply an array of MAC Addresses.

See also: ziti_pr_mac_cb

◆ ziti_pq_os_cb

typedef void(* ziti_pq_os_cb) (ziti_context ztx, const char *id, ziti_pr_os_cb response_cb)

Posture Query for OS callback.

This callback is invoked when the OS version info of the current host is needed. The callback will be supplied a followup callback to supply the host's OS information.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
response_cb	the callback to invoke to supply values

See also: ziti_pr_os_cb

◆ ziti_pq_process_cb

typedef void(* ziti_pq_process_cb) (ziti_context ztx, const char *id, const char *path, ziti_pr_process_cb response_cb)

Posture Query for process callback.

This callback is invoked when process info is needed from the host. The callback will be supplied a followup callback to supply the process's status

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
path	the process path to inspect
response_cb	the callback to invoke

See also: ziti_pr_process_cb

◆ ziti_pr_domain_cb

typedef void(* ziti_pr_domain_cb) (ziti_context ztx, const char *id, const char *domain)

Posture response Domain callback.

This callback should be invoked after gathering the relevant Domain of the host during a ziti_pq_domain_cb()

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
domain	the domain the host has joint or nil if not supported

See also: ziti_pq_domain_cb()

◆ ziti_pr_mac_cb

typedef void(* ziti_pr_mac_cb) (ziti_context ztx, const char *id, char **mac_addresses, int num_mac)

Posture response MAC address callback.

This callback should be invoked after gathering the relevant MAC Addresses available during a ziti_pq_mac_cb()

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
mac_addresses	an array of the mac addresses the host currently has access to. Values should be hex strings. Nil signifies not supported.
num_mac	the size of the mac_addresses array

See also: ziti_pq_mac_cb()

◆ ziti_pr_os_cb

typedef void(* ziti_pr_os_cb) (ziti_context ztx, const char *id, const char *os_type, const char *os_version, const char *os_build)

Posture response OS callback.

This callback should be invoked after gathering the relevant OS versions of the host during a ziti_pq_os_cb()

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
os_type	the OS type: Windows, Linux, Android, macOS, iOS
os_version	the OS version or kernel version
os_build	the build of the OS or nil if not supported

See also: ziti_pq_os_cb()

◆ ziti_pr_process_cb

typedef void(* ziti_pr_process_cb) (ziti_context ztx, const char *id, const char *path, bool is_running, const char *sha_512_hash, char **signers, int num_signers)

Posture response process callback.

This callback should be invoked after gathering the relevant process information from the host during a ziti_pq_process_cb()

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
path	the path of the inspect process
is_running	if the process is running
sha_512_hash	the sha512 hash of the process's binary file
signers	sha1 hex string fingerprints of the binary or nil if not supported
num_signers	the number of signers

See also: ziti_pq_process_cb()

◆ ziti_service_cb

typedef void(* ziti_service_cb) (ziti_context ztx, const ziti_service *, int status, void *data)

Service status callback.

This callback is invoked on the conclusion of ziti_service_available(). The result of the function may be an error condition so it is important to verify the status code in this callback. In the event the service does not exist or the identity has not been given the access to the service the ZITI_SERVICE_UNAVAILABLE error code will be returned otherwise ZITI_OK is expected.

See also: ziti_service_available(), ZITI_ERRORS

◆ ziti_verify_extend_cert_authenticator_cb

typedef void(* ziti_verify_extend_cert_authenticator_cb) (ziti_context ztx, int status, void *ctx)

Verify Extend Certificate Authenticator Callback.

This callback is invoked on the conclusion of ziti_verify_extend_cert_authenticator(). The result of the function may be an error condition so it is important to verify the status code in this callback. In the event the certificate authenticator extension verification request cannot be completed an error will be returned otherwise ZITI_OK is expected. At the end of this callback's invocation, the new client certificate PEM should be stored and set for use via ziti_set_client_cert on new connections and reconnections.

See also: ziti_extend_cert_authenticator(), ZITI_ERRORS

◆ ziti_write_cb

typedef void(* ziti_write_cb) (ziti_connection conn, ssize_t status, void *write_ctx)

Callback called after ziti_write() is complete.

This callback is triggered on the completion of ziti_write(). The result of the ziti_write() function may be an error condition so it is important to verify the provided status code in this callback.

This callback is often used to free or reinitialize the buffer associated with the ziti_write() invocation. It is important to not free this memory until after data has been written to the wire else the results of the write operation may be unexpected.

See also: ziti_write(), ZITI_ERRORS

Function Documentation

◆ ziti_accept()

int ziti_accept	(	ziti_connection	clt,
		ziti_conn_cb	cb,
		ziti_data_cb	data_cb
	)

extern

Completes client connection.

After a client connects to a hosted Ziti service this function is invoked to finish the connection establishment. This function will establish the callbacks necessary to send data to the connecting client or to process data sent by the client.

After this function completes the ziti_conn_cb callback is invoked. The callback will contain the status of the function call as well so it's important to verify the status.

Data sent by the client is processed in the ziti_data_cb callback. Every invocation of the callback could indicate an error or that the connection is no longer usable so it is important to check the status of the function each time it is invoked.

Parameters

clt	a ziti_connection representing the incoming client connection
cb	a callback invoked when the function completes
data_cb	a callback invoked each time the client sends data

Returns: ZITI_OK or corresponding #ZITI_ERRORS

See also: ziti_listen()

◆ ziti_app_ctx()

void * ziti_app_ctx ( ziti_context ztx )

extern

returns ziti_options.app_ctx for the given Ziti context.

Parameters

ztx

Returns: application context that was passed as ziti_oprions.app_ctx

◆ ziti_close()

int ziti_close	(	ziti_connection	conn,
		ziti_close_cb	close_cb
	)

extern

Closes the given connection.

When no longer needed a connection should be closed to gracefully disconnect. This function should be invoked after any status is returned which indicates an error situation.

This method initiates the disconnect(if needed) and the release all associated resources. After close_cb() is called, the ziti_connection handle is no longer valid.

Parameters

conn	the ziti_connection to be closed
close_cb	callback called after connection is closed

Returns: ZITI_OK ZITI_CONN_CLOSED if connection was already ziti_close() was already called on the given connection other #ZITI_ERRORS

◆ ziti_close_write()

int ziti_close_write ( ziti_connection conn )

extern

Closes the outgoing (write) side of the given ziti connection.

Any pending write requests will be able to complete. The conn should refer to a initialized ziti connection.

This notifies peer ziti connection that no more data will be sent – peer receives EOF. Any further calls to ziti_write() will return an error.

This leaves incoming(read) side of ziti connection open.

Note: this is roughly equivalent to calling uv_shutdown() on a duplex uv_stream, or shutdown(sock, SHUT_WR) on socket fd.

Parameters

conn	the ziti_connection to be closed

Returns: ZITI_OK or corresponding #ZITI_ERRORS

◆ ziti_conn_bridge()

int ziti_conn_bridge	(	ziti_connection	conn,
		uv_handle_t *	handle,
		uv_close_cb	on_close
	)

extern

Bridge [ziti_connection] to a given IO stream.

This sets up the connection bridge: all bytes read from ziti_connection are forwarded to the IO stream, and vice a versa. Both ziti_connection and stream have to be established prior to this call.

[on_close] is called after the bridge is terminated and ziti_connection was closed.

Parameters

conn
handle	IO handle, must be a stream (UV_TCP, UV_PIPE, UV_TTY) or a UV_UDP handle
on_close

Returns: 0 on success, error code on failure

◆ ziti_conn_bridge_fds()

int ziti_conn_bridge_fds	(	ziti_connection	conn,
		uv_os_fd_t	input,
		uv_os_fd_t	output,
		void()(void ctx)	close_cb,
		void *	ctx
	)

extern

Bridge [ziti_connection] to given IO file descriptors.

All bytes read from ziti_connection are written to output fd, all bytes read from input fd are sent to ziti_connection.

Parameters

conn
input
output
close_cb
ctx

Returns

◆ ziti_conn_bridge_idle_timeout()

int ziti_conn_bridge_idle_timeout	(	ziti_connection	conn,
		unsigned long	millis
	)

extern

set idle timeout on bridged connection.

Parameters

conn	ziti_connection previously bridged with [ziti_conn_bridge] or [ziti_conn_bridge_fds]
millis	timeout after which bridge will be closed absent any traffic

Returns: 0 on success, error code on failure

◆ ziti_conn_context()

ziti_context ziti_conn_context ( ziti_connection conn )

extern

Return Ziti context for given connection.

Parameters

conn	ziti connection

Returns: ziti context connection belongs to

◆ ziti_conn_data()

void * ziti_conn_data ( ziti_connection conn )

extern

Retrieves any custom data associated with the given ziti_connection.

This function returns the custom data associated to the ziti_connection supplied in the ziti_conn_init() function.

Parameters

conn	the ziti_connection to retrieve the context from

Returns: custom data passed into ziti_conn_init()

◆ ziti_conn_init()

int ziti_conn_init	(	ziti_context	ztx,
		ziti_connection *	conn,
		void *	data
	)

extern

Initializes a connection.

This function takes an uninitialized ziti_connection and prepares it to be used in the Ziti C SDK and allows for additional context to be carried forward.

Parameters

ztx	the Ziti Edge identity context to initialize the connection with
conn	an uninitialized ziti_connection to be initialized
data	additional context to carry forward in ziti_dial() and ziti_listen() related callbacks

Returns: ZITI_OK or corresponding #ZITI_ERRORS

See also: ziti_dial(), ziti_listen(), ZITI_ERRORS

◆ ziti_conn_set_data()

void ziti_conn_set_data	(	ziti_connection	conn,
		void *	data
	)

extern

Set or clear custom data associated with the given ziti_connection.

This function associates the custom data to the ziti_connection. Pass NULL to clear associated data.

Parameters

conn	the ziti_connection to set the context to
data	custom data

See also: ziti_conn_data(), ziti_conn_init()

◆ ziti_conn_set_data_cb()

int ziti_conn_set_data_cb	(	ziti_connection	conn,
		ziti_data_cb	cb
	)

extern

Set new data callback on ziti connection.

This allows application to defer setting callback until connection is established (inside [ziti_conn_cb]), or change processing at any time.

Parameters

conn
cb

Returns: ZITI_OK or error code

◆ ziti_conn_source_identity()

const char * ziti_conn_source_identity ( ziti_connection conn )

extern

Get the identity of the client that initiated the ziti_connection.

Returns: identity of the client that requested the connection.

◆ ziti_context_init()

int ziti_context_init	(	ziti_context *	ztx,
		const ziti_config *	config
	)

extern

◆ ziti_context_run()

int ziti_context_run	(	ziti_context	ztx,
		uv_loop_t *	loop
	)

extern

◆ ziti_context_set_options()

int ziti_context_set_options	(	ziti_context	ztx,
		const ziti_options *	options
	)

extern

◆ ziti_dial()

int ziti_dial	(	ziti_connection	conn,
		const char *	service,
		ziti_conn_cb	cb,
		ziti_data_cb	data_cb
	)

extern

Establishes connection to a Ziti service.

Before any bytes can be sent over the Ziti Network a ziti_connection must be dialed to a service. This function will attempt to dial the service with the given name. The result of the service dial will be called back using the provided ziti_conn_cb.

If the dial succeeds the provided ziti_data_cb is used to handle bytes returned from the service. If the dial fails only the ziti_conn_cb will be invoked with the corresponding #ZITI_ERRORS code.

Parameters

conn	the ziti_connection to use in the dial operation
service	the name of the service to dial
cb	invoked after the dial operation completes
data_cb	invoked if the dial operation succeeds with data received over the connection

Returns: ZITI_OK or corresponding #ZITI_ERRORS

See also: ziti_dial(), ziti_write()

◆ ziti_dial_with_options()

int ziti_dial_with_options	(	ziti_connection	conn,
		const char *	service,
		ziti_dial_opts *	dial_opts,
		ziti_conn_cb	cb,
		ziti_data_cb	data_cb
	)

extern

◆ ziti_dump()

void ziti_dump	(	ziti_context	ztx,
		int()(void ctx, const char *fmt,...)	printer,
		void *	ctx
	)

extern

Shutdown Ziti Edge identity context and reclaim the memory from the provided ziti_context.

This function will output debugging information to standard out. The output from this command may be useful when submitting issues.

this method is designed to be suitable to use with fprintf() like this:

ziti_dump(ztx, fprintf, stderr);

ziti_dump

void ziti_dump(ziti_context ztx, int(*printer)(void *ctx, const char *fmt,...), void *ctx)

Shutdown Ziti Edge identity context and reclaim the memory from the provided ziti_context.

Parameters

ztx	the Ziti Edge identity context to print debug information for
printer	function to be called for output
ctx	first argument passed into `printer` function

◆ ziti_endpoint_state_change()

void ziti_endpoint_state_change	(	ziti_context	ztx,
		bool	woken,
		bool	unlocked
	)

extern

Alerts that the host running the ziti_context has undergone a state change.

Notifies that the host has undergone a state change: either woke or unlocked. Being "woke" is defined as the screen dimming/shutting off Being "unlocked" is defined as having the device unlocked via a security mechanism.

At one time, a device may be "woken" and "unlocked".

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
woken	whether the host device has been woke from sleep/hibernation
unlocked	whether the host device has been unlocked

◆ ziti_ext_auth()

int ziti_ext_auth	(	ziti_context	ztx,
		void()(ziti_context, const char url, void *)	ziti_ext_launch,
		void *	ctx
	)

extern

◆ ziti_ext_auth_token()

int ziti_ext_auth_token	(	ziti_context	ztx,
		const char *	token
	)

extern

◆ ziti_extend_cert_authenticator()

int ziti_extend_cert_authenticator	(	ziti_context	ztx,
		const char *	csr_pem,
		ziti_extend_cert_authenticator_cb	cb,
		void *	ctx
	)

extern

Attempts extend the lifetime of a 1st party client certificate (issued by the Ziti Controller)

Attempts to extend the current authenticator used for the ztx's authentication. If it is not a certificate authenticator or it is not extendable, errors will be returned in subsequent events.

Responses are provided via a ziti_extend_cert_authenticator_cb callback. On that callback, check the error field for issues. If there are no errors persist the new_client_cert_pem and make a subsequent call to ziti_verify_extend_cert_authenticator to enable use of the new client certificate.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
csr	a CSR representing the request for a new client certificate
ctx	additional context to be passed back to the call via cb
cb	a callback for the result of the certificate extension request

Returns: returns ZITI_OK on success, otherwise error

◆ ziti_get_appdata()

int ziti_get_appdata	(	ziti_context	ztx,
		const char *	key,
		void *	data,
		int()(void , const char *, size_t)	parse_func
	)

◆ ziti_get_appdata_raw()

const char * ziti_get_appdata_raw	(	ziti_context	ztx,
		const char *	key
	)

◆ ziti_get_controller()

const char * ziti_get_controller ( ziti_context ztx )

extern

controller URL of the given context

Parameters

ztx	ziti context

Returns: controller URL

◆ ziti_get_controller_version()

const ziti_version * ziti_get_controller_version ( ziti_context ztx )

extern

return Ziti controller version for given context

Parameters

ztx	ziti context

Returns: controller version

◆ ziti_get_ext_jwt_signers()

int ziti_get_ext_jwt_signers	(	ziti_context	ztx,
		ziti_ext_signers_cb	cb,
		void *	ctx
	)

extern

Get a list of available external JWT signers.

this list can be presented to the user to select provider with which to continue authentication flow (via [ziti_use_ext_jwt_signer]).

Parameters

ztx	ziti context
cb	callback for the result
ctx	callback context

Returns

◆ ziti_get_identity()

const ziti_identity * ziti_get_identity ( ziti_context ztx )

extern

Ziti identity of the given context.

Parameters

ztx	ziti context

Returns: ziti identity

◆ ziti_get_transfer_rates()

int ziti_get_transfer_rates	(	ziti_context	ztx,
		double *	up,
		double *	down
	)

extern

Retrieve current transfer rates.

Rates are in bytes/second.

Calculation is using 1 minute EWMA.

Parameters

ztx	ziti context
up	rate of bytes going up
down	rate of bytes going down

Returns: ZITI_OK or error code

◆ ziti_get_version()

const ziti_version * ziti_get_version ( )

extern

return SDK version

Returns: SDK version

◆ ziti_is_enabled()

bool ziti_is_enabled ( ziti_context ztx )

extern

return if context is enabled

Parameters

ztx	ziti context

Returns

◆ ziti_listen()

int ziti_listen	(	ziti_connection	serv_conn,
		const char *	service,
		ziti_listen_cb	lcb,
		ziti_client_cb	cb
	)

extern

Start accepting ziti client connections.

This function is invoked to tell the Ziti SDK to accept connections from other Ziti clients for the provided service name. The identity configured in the Ziti C SDK will need to be configured to host the service via the Ziti Controller.

When this function completes the ziti_listen_cb callback will be invoked. This callback is what will verify the success or failure of the listen operation.

Once successfully listening the ziti_client_cb will be invoked when a Ziti client attempts to dial this service name.

Parameters

serv_conn	the ziti_connection acting as a server which will be hosting the service
service	the name of the service to be hosted
lcb	invoked after the function completes
cb	a callback invoked when when client is attempting to connect to advertised service

Returns: ZITI_OK or corresponding #ZITI_ERRORS

See also: ziti_accept()

◆ ziti_listen_with_options()

int ziti_listen_with_options	(	ziti_connection	serv_conn,
		const char *	service,
		ziti_listen_opts *	listen_opts,
		ziti_listen_cb	lcb,
		ziti_client_cb	cb
	)

extern

◆ ziti_load_config()

int ziti_load_config	(	ziti_config *	config,
		const char *	conf_str
	)

extern

Load ziti identity config from memory or file.

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

Parameters

config	target ziti_config object
conf_str	identity config JSON or path to a file.

Returns: ZITI_OK on success or error code

◆ ziti_mfa_auth()

void ziti_mfa_auth	(	ziti_context	ztx,
		const char *	code,
		ziti_mfa_cb	auth_cb,
		void *	ctx
	)

extern

Attempt to submit an MFA code for evaluation.

Attempts submit an MFA code for evaluation. This should be done in response to the ZitiMfaAuthEvent event or when posture check timeouts would occur for a service.

An error status will be returned if the request fails, ZITI_OK is expected on success via the ziti_mfa_cb provided.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
code	a TOTP code
auth_cb	callback to receive the result status
ctx	additional context to be passed into the callback

◆ ziti_mfa_enroll()

void ziti_mfa_enroll	(	ziti_context	ztx,
		ziti_mfa_enroll_cb	enroll_cb,
		void *	ctx
	)

extern

Attempts to initialize MFA enrollment.

Attempts to initialize enrollment. On success or failure the supplied enroll_cb will be called with relevant status information. The supplied ztx must be have passed a primary authentication mechanism (cert, updb, etc).

An error status will be returned if the request fails, ZITI_OK is expected on success.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
ziti_mfa_enroll_cb	callback to receive MFA enrollment initialization status
ctx	additional context to be passed into the enroll_cb callback

◆ ziti_mfa_get_recovery_codes()

void ziti_mfa_get_recovery_codes	(	ziti_context	ztx,
		const char *	code,
		ziti_mfa_recovery_codes_cb	get_cb,
		void *	ctx
	)

extern

Attempts to retrieve the current recovery codes for the identity.

Attempts to retrieve the recovery codes for the current identity. On success or failure the supplied get_cb will be called with relevant status information. The supplied ztx must be fully authenticated.

An error status will be returned if the request fails, ZITI_OK is expected on success.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
code	a TOTP code, may be empty string for MFA enrollments that have not completed vi ziti_mfa_verify
remove_cb	callback to receive the result status
ctx	additional context to be passed into the get_cb callback

◆ ziti_mfa_new_recovery_codes()

void ziti_mfa_new_recovery_codes	(	ziti_context	ztx,
		char *	code,
		ziti_mfa_recovery_codes_cb	new_cb,
		void *	ctx
	)

extern

Attempts to generate new recovery codes and retrieve the new recovery codes for MFA.

Attempts to generate new recovery codes. All previous codes will become invalid and replaced with the new recovery codes. On success or failure the supplied get_cb will be called with relevant status information. The supplied ztx must be fully authenticated.

An error status will be returned if the request fails, ZITI_OK is expected on success.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
code	a TOTP code
new_cb	callback to receive the result status
ctx	additional context to be passed into the get_cb callback

◆ ziti_mfa_remove()

void ziti_mfa_remove	(	ziti_context	ztx,
		const char *	code,
		ziti_mfa_cb	remove_cb,
		void *	ctx
	)

extern

Attempts to remove MFA.

Attempts to remove MFA. On success or failure the supplied remove_cb will be called with relevant status information. The supplied ztx must be fully authenticated.

An error status will be returned if the request fails, ZITI_OK is expected on success.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
code	a TOTP or recovery code, may be empty string for MFA enrollments that have not completed via ziti_mfa_verify
remove_cb	callback to receive MFA removal status
ctx	additional context to be passed into the remove_cb callback

◆ ziti_mfa_verify()

void ziti_mfa_verify	(	ziti_context	ztx,
		char *	code,
		ziti_mfa_cb	verify_cb,
		void *	ctx
	)

extern

Attempts to verify MFA enrollment.

Attempts to verify MFA enrollment. On success or failure the supplied verify_cb will be called with relevant status information. The supplied ztx must be authenticated. After verification, MFA enrollment is complete.

An error status will be returned if the request fails, ZITI_OK is expected on success.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
code	a valid TOTP code, must not be a recovery code
remove_cb	callback to receive MFA verify status
ctx	additional context to be passed into the verify_cb callback

Returns: ZITI_OK or corresponding #ZITI_ERRORS

◆ ziti_refresh()

int ziti_refresh ( ziti_context ztx )

extern

Trigger refresh ahead of normal refresh cycle.

This method will force ziti context to update its internal model from ziti controller. Appropriate events will be triggered as needed (just like during normal refresh cycle [ziti_options.refresh_interval]):

Service Added/Removed, etc.
Parameters

ztx

Returns
ZITI_OK on success, or error code

◆ ziti_service_available()

int ziti_service_available	(	ziti_context	ztx,
		const char *	service,
		ziti_service_cb	cb,
		void *	ctx
	)

extern

Checks availability of the service for the given edge context.

Checks to see if a given ziti_context has a service available by the name supplied. The supplied name is case sensitive. This function is not synchronous - the ziti_service_cb specified is invoked at the end of the function invocation with the result.

Parameters

ztx	the Ziti Edge identity context to use to check for the service's availability on
service	the name of the service to check
cb	callback called with ZITI_OK or #ZITI_SERVICE_NOT_AVAILABLE
ctx	additional context to be passed to the ziti_service_cb

Returns: ZITI_OK or corresponding #ZITI_ERRORS

◆ ziti_service_for_addr()

const ziti_service * ziti_service_for_addr	(	ziti_context	ztx,
		ziti_protocol	proto,
		const ziti_address *	addr,
		int	port
	)

extern

◆ ziti_service_for_addr_str()

const ziti_service * ziti_service_for_addr_str	(	ziti_context	ztx,
		ziti_protocol	proto,
		const char *	addr,
		int	port
	)

extern

◆ ziti_set_app_info()

void ziti_set_app_info	(	const char *	app_id,
		const char *	app_version
	)

extern

Provide app information to Ziti SDK.

App information is reported to Ziti Controller. Supplying this information is optional.

◆ ziti_set_client_cert()

int ziti_set_client_cert	(	ziti_context	ztx,
		const char *	cert_buf,
		size_t	cert_len,
		const char *	key_buf,
		size_t	key_len
	)

extern

Updates the certificate context for the ZTX with a new client certificate and key.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
cert_buf	a PEM formatted x509 certificate
cert_len	the length of cert_buf
key_buf	a PEM formatted x509 private key
key_len	the length of key_buf

Returns: returns 0 on success

◆ ziti_set_enabled()

void ziti_set_enabled	(	ziti_context	ztx,
		bool	enabled
	)

extern

Enable or disable given Ziti context.

Parameters

ztx
enabled

◆ ziti_shutdown()

int ziti_shutdown ( ziti_context ztx )

extern

Shutdown Ziti Edge identity context and reclaim the memory from the provided ziti_context.

Parameters

ztx	the Ziti Edge identity context to be shut down. this reference is not safe to use after this call

Returns: ZITI_OK or corresponding #ZITI_ERRORS

◆ ziti_use_ext_jwt_signer()

int ziti_use_ext_jwt_signer	(	ziti_context	ztx,
		const char *	name
	)

extern

select external JWT signer to initiate OIDC authentication flow

Parameters

ztx	ziti context
name	name of JWT signer configured for the ziti network

Returns

◆ ziti_verify_extend_cert_authenticator()

int ziti_verify_extend_cert_authenticator	(	ziti_context	ztx,
		const char *	new_cert,
		ziti_verify_extend_cert_authenticator_cb	cb,
		void *	ctx
	)

extern

Called in response to a ziti_extend_cert_authenticator_cb to verify a new client certificate.

After calling ziti_extend_cert_authenticator a ziti_extend_cert_authenticator_cb callback will be invoked. In order to have the new client cert provided in the event become active, the controller requires that the client verify that it has received the new certificate. Calling this function will verify the certificate and cause the new client certificate to become active, inactivating the old certificate. At the end of execution the provided callback will be invoked with ZITI_OK or an error.

ziti_set_client_cert should be called shortly after on success.

Parameters

ztx	the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
new_cert	the new client certificate that will become active on successful verification, provided in the extension event
ctx	additional context to be passed back in raised events

Returns: returns ZITI_OK on success, otherwise error

◆ ziti_write()

int ziti_write	(	ziti_connection	conn,
		uint8_t *	data,
		size_t	length,
		ziti_write_cb	write_cb,
		void *	write_ctx
	)

extern

Send data to the connection peer.

This function is invoked to send data from the Ziti C SDK to the peer on the other side of the Ziti connection. It is used to send data over the given connection and to establish the callback invoked after the data is sent. It is important to not free the buffer until the ziti_write_cb callback is invoked. It is only safe to free the buffer in the write callback.

Parameters

conn	the ziti_connection used to write data to
data	a buffer of data to write over the provided ziti_connection
length	the length of data in the data buffer to send. Make sure to not specify
write_cb	a callback invoked after the function completes indicating the buffer can now be reclaimed
write_ctx	additional context to be passed to the ziti_write_cb callback

Returns: ZITI_OK or corresponding #ZITI_ERRORS

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ZITI_CAN_BIND

◆ ZITI_CAN_DIAL

◆ ZITI_DEFAULT_TIMEOUT

Typedef Documentation

◆ ziti_client_cb

◆ ziti_close_cb

◆ ziti_conn_cb

◆ ziti_connection

◆ ziti_context

◆ ziti_data_cb

◆ ziti_event_cb

◆ ziti_ext_signers_cb

◆ ziti_extend_cert_authenticator_cb

◆ ziti_listen_cb

◆ ziti_mfa_cb

◆ ziti_mfa_enroll_cb

◆ ziti_mfa_recovery_codes_cb

◆ ziti_pq_domain_cb

◆ ziti_pq_mac_cb

◆ ziti_pq_os_cb

◆ ziti_pq_process_cb

◆ ziti_pr_domain_cb

◆ ziti_pr_mac_cb

◆ ziti_pr_os_cb

◆ ziti_pr_process_cb

◆ ziti_service_cb

◆ ziti_verify_extend_cert_authenticator_cb

◆ ziti_write_cb

Function Documentation

◆ ziti_accept()

◆ ziti_app_ctx()

◆ ziti_close()

◆ ziti_close_write()

◆ ziti_conn_bridge()

◆ ziti_conn_bridge_fds()

◆ ziti_conn_bridge_idle_timeout()

◆ ziti_conn_context()

◆ ziti_conn_data()

◆ ziti_conn_init()

◆ ziti_conn_set_data()

◆ ziti_conn_set_data_cb()

◆ ziti_conn_source_identity()

◆ ziti_context_init()

◆ ziti_context_run()

◆ ziti_context_set_options()

◆ ziti_dial()

◆ ziti_dial_with_options()

◆ ziti_dump()

◆ ziti_endpoint_state_change()

◆ ziti_ext_auth()

◆ ziti_ext_auth_token()

◆ ziti_extend_cert_authenticator()

◆ ziti_get_appdata()

◆ ziti_get_appdata_raw()

◆ ziti_get_controller()

◆ ziti_get_controller_version()

◆ ziti_get_ext_jwt_signers()

◆ ziti_get_identity()

◆ ziti_get_transfer_rates()

◆ ziti_get_version()

◆ ziti_is_enabled()

◆ ziti_listen()

◆ ziti_listen_with_options()

◆ ziti_load_config()

◆ ziti_mfa_auth()

◆ ziti_mfa_enroll()

◆ ziti_mfa_get_recovery_codes()

◆ ziti_mfa_new_recovery_codes()

◆ ziti_mfa_remove()

◆ ziti_mfa_verify()

◆ ziti_refresh()

◆ ziti_service_available()

◆ ziti_service_for_addr()

◆ ziti_service_for_addr_str()