Ziti C SDK
Loading...
Searching...
No Matches
ziti.h
Go to the documentation of this file.
1// Copyright (c) 2022-2024. NetFoundry Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5//
6// You may obtain a copy of the License at
7// https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
20#ifndef ZITI_ZITI_H
21#define ZITI_ZITI_H
22
23#include <stdint.h>
24#include <tlsuv/tlsuv.h>
25#include <uv.h>
26#include "errors.h"
27
28#include "externs.h"
29#include "ziti_model.h"
30#include "enums.h"
31#include "ziti_events.h"
32#include "enroll.h"
33
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
42#define ZITI_CAN_DIAL 1U
43
47#define ZITI_CAN_BIND 2U
48
52#define ZITI_DEFAULT_TIMEOUT 10000
53
67typedef struct ziti_ctx *ziti_context;
68
82typedef struct ziti_conn *ziti_connection;
83
94typedef void (*ziti_service_cb)(ziti_context ztx, const ziti_service *, int status, void *data);
95
108typedef void (*ziti_terminator_cb)(ziti_context ztx, const ziti_terminator* const * terminators , int status, void *ctx);
109
122typedef void (*ziti_pr_mac_cb)(ziti_context ztx, const char *id, char **mac_addresses, int num_mac);
123
133typedef void (*ziti_pq_mac_cb)(ziti_context ztx, const char *id, ziti_pr_mac_cb response_cb);
134
146typedef void (*ziti_pr_domain_cb)(ziti_context ztx, const char *id, const char *domain);
147
159typedef void (*ziti_pq_domain_cb)(ziti_context ztx, const char *id, ziti_pr_domain_cb response_cb);
160
174typedef void (*ziti_pr_os_cb)(ziti_context ztx, const char *id, const char *os_type, const char *os_version, const char *os_build);
175
187typedef void (*ziti_pq_os_cb)(ziti_context ztx, const char *id, ziti_pr_os_cb response_cb);
188
189
205typedef void(*ziti_pr_process_cb)(ziti_context ztx, const char *id, const char *path, bool is_running,
206 const char *sha_512_hash, char **signers, int num_signers);
207
220typedef void (*ziti_pq_process_cb)(ziti_context ztx, const char *id, const char *path,
221 ziti_pr_process_cb response_cb);
222
234typedef void (*ziti_event_cb)(ziti_context ztx, const ziti_event_t *event);
235
241typedef struct ziti_options_s {
242 bool disabled; // if true initial state will be disabled
243 const char **config_types;
244
245 unsigned int api_page_size;
246 long refresh_interval; //the duration in seconds between checking for updates from the controller
247 rate_type metrics_type; //an enum describing the metrics to collect
248
249 //posture query cbs
254
255 void *app_ctx;
256
260 unsigned int events;
261
266
279
280typedef struct ziti_dial_opts_s {
284 bool stream;
286 char *identity;
287 void *app_data;
290
291typedef struct ziti_client_ctx_s {
293 const uint8_t *app_data;
296
297
306
324typedef ssize_t (*ziti_data_cb)(ziti_connection conn, const uint8_t *data, ssize_t length);
325
338typedef void (*ziti_conn_cb)(ziti_connection conn, int status);
339
358typedef void (*ziti_client_cb)(ziti_connection serv, ziti_connection client, int status, const ziti_client_ctx *ctx);
359
369
382typedef void (*ziti_write_cb)(ziti_connection conn, ssize_t status, void *write_ctx);
383
384
385
393typedef void (*ziti_close_cb)(ziti_connection conn);
394
401extern void ziti_set_app_info(const char *app_id, const char *app_version);
402
412extern int ziti_load_config(ziti_config *config, const char* conf_str);
413
415extern int ziti_context_init(ziti_context *ztx, const ziti_config *config);
416
418extern int ziti_context_set_options(ziti_context ztx, const ziti_options *options);
419
421extern int ziti_context_run(ziti_context ztx, uv_loop_t *loop);
422
435
443
450extern void ziti_set_enabled(ziti_context ztx, bool enabled);
451
459extern void *ziti_app_ctx(ziti_context ztx);
460
467
475
482extern const char *ziti_get_controller(ziti_context ztx);
483
491
492
494
508
517extern int ziti_use_ext_jwt_signer(ziti_context ztx, const char *name);
518
529extern int ziti_get_transfer_rates(ziti_context ztx, double *up, double *down);
530
540
557extern void ziti_dump(ziti_context ztx, int (*printer)(void *ctx, const char *fmt, ...), void *ctx);
558
560const char *ziti_get_appdata_raw(ziti_context ztx, const char *key);
561
563int ziti_get_appdata(ziti_context ztx, const char *key, void *data,
564 int (*parse_func)(void *, const char *, size_t));
565
581extern int ziti_conn_init(ziti_context ztx, ziti_connection *conn, void *data);
582
591
604
616extern void ziti_conn_set_data(ziti_connection conn, void *data);
617
629
637
653extern int ziti_service_available(ziti_context ztx, const char *service, ziti_service_cb cb, void *ctx);
654
666extern int ziti_list_terminators(ziti_context ztx, const char *service, ziti_terminator_cb cb, void *ctx);
667
669extern const ziti_service *ziti_service_for_addr_str(ziti_context ztx, ziti_protocol proto, const char *addr, int port);
670
672extern const ziti_service *ziti_service_for_addr(ziti_context ztx, ziti_protocol proto, const ziti_address *addr, int port);
673
674
695extern int ziti_dial(ziti_connection conn, const char *service, ziti_conn_cb cb, ziti_data_cb data_cb);
696
698extern int ziti_dial_with_options(ziti_connection conn, const char *service, ziti_dial_opts *dial_opts, ziti_conn_cb cb,
699 ziti_data_cb data_cb);
700
724extern int ziti_listen(ziti_connection serv_conn, const char *service, ziti_listen_cb lcb, ziti_client_cb cb);
725
727extern int ziti_listen_with_options(ziti_connection serv_conn, const char *service, ziti_listen_opts *listen_opts,
729
754
772extern int ziti_close(ziti_connection conn, ziti_close_cb close_cb);
773
793
811extern int ziti_write(ziti_connection conn, uint8_t *data, size_t length, ziti_write_cb write_cb, void *write_ctx);
812
827extern int ziti_conn_bridge(ziti_connection conn, uv_handle_t *handle, uv_close_cb on_close);
828
836extern int ziti_conn_bridge_idle_timeout(ziti_connection conn, unsigned long millis);
837
851extern 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);
852
866typedef void (*ziti_mfa_enroll_cb)(ziti_context ztx, int status, ziti_mfa_enrollment *mfa_enrollment, void *ctx);
867
876typedef void (*ziti_mfa_cb)(ziti_context ztx, int status, void *ctx);
877
886typedef void (*ziti_ext_auth_launch_cb)(ziti_context ztx, const char *url, void *ctx);
887
899typedef void (*ziti_mfa_recovery_codes_cb)(ziti_context ztx, int status, const char **recovery_codes, void *ctx);
900
915extern void ziti_mfa_enroll(ziti_context ztx, ziti_mfa_enroll_cb enroll_cb, void *ctx);
916
932extern void ziti_mfa_remove(ziti_context ztx, const char *code, ziti_mfa_cb remove_cb, void *ctx);
933
951extern void ziti_mfa_verify(ziti_context ztx, char *code, ziti_mfa_cb verify_cb, void *ctx);
952
953
968extern void ziti_mfa_get_recovery_codes(ziti_context ztx, const char *code, ziti_mfa_recovery_codes_cb get_cb, void *ctx);
969
985extern void ziti_mfa_new_recovery_codes(ziti_context ztx, char *code, ziti_mfa_recovery_codes_cb new_cb, void *ctx);
986
1003extern void ziti_mfa_auth(ziti_context ztx, const char *code, ziti_mfa_cb auth_cb, void *ctx);
1004
1015extern int ziti_ext_auth(ziti_context ztx, ziti_ext_auth_launch_cb launch_cb, void *ctx);
1016
1017extern int ziti_ext_auth_token(ziti_context ztx, const char *token);
1018
1033extern void ziti_endpoint_state_change(ziti_context ztx, bool woken, bool unlocked);
1034
1045typedef void (*ziti_extend_cert_authenticator_cb)(ziti_context ztx, const char* cert_pem, int status, void *ctx);
1046
1064extern int ziti_extend_cert_authenticator(ziti_context ztx, const char *csr_pem, ziti_extend_cert_authenticator_cb cb, void *ctx);
1065
1077typedef void (*ziti_verify_extend_cert_authenticator_cb)(ziti_context ztx, int status, void *ctx);
1078
1097
1109extern int ziti_set_client_cert(ziti_context ztx, const char *cert_buf, size_t cert_len, const char *key_buf, size_t key_len);
1110
1111#ifdef __cplusplus
1112}
1113#endif
1114
1115#endif /* ZITI_ZITI_H */
rate_type
Represents the type and rate of metric to capture.
Definition enums.h:21
Defines the macros, functions, typedefs and constants pertaining to errors observed when using a Ziti...
#define ZITI_FUNC
Definition externs.h:38
Definition ziti_model.h:211
Definition ziti.h:291
size_t app_data_sz
Definition ziti.h:294
const uint8_t * app_data
Definition ziti.h:293
char * caller_id
Definition ziti.h:292
Definition ziti_model.h:272
Definition ziti.h:280
void * app_data
Definition ziti.h:287
size_t app_data_sz
Definition ziti.h:288
bool stream
enable stream semantics this allows SDK to consolidate multiple write requests to lower overlay overh...
Definition ziti.h:284
char * identity
Definition ziti.h:286
int connect_timeout_seconds
Definition ziti.h:285
Object passed to ziti_options.event_cb.
Definition ziti_events.h:144
Definition ziti_model.h:274
Definition ziti.h:298
bool bind_using_edge_identity
Definition ziti.h:304
int max_connections
Definition ziti.h:302
uint16_t terminator_cost
Definition ziti.h:299
char * identity
Definition ziti.h:303
int connect_timeout_seconds
Definition ziti.h:301
uint8_t terminator_precedence
Definition ziti.h:300
Definition ziti_model.h:306
ziti_context runtime options
Definition ziti.h:241
ziti_pq_domain_cb pq_domain_cb
Definition ziti.h:253
unsigned int api_page_size
Definition ziti.h:245
long refresh_interval
Definition ziti.h:246
ziti_pq_mac_cb pq_mac_cb
Definition ziti.h:250
bool disabled
Definition ziti.h:242
unsigned int events
subscribed event types.
Definition ziti.h:260
const char ** config_types
Definition ziti.h:243
unsigned int cert_extension_window
this setting allows SDK to auto-extend identity certificate.
Definition ziti.h:277
ziti_event_cb event_cb
callback invoked is response to subscribed events.
Definition ziti.h:265
ziti_pq_os_cb pq_os_cb
Definition ziti.h:251
rate_type metrics_type
Definition ziti.h:247
ziti_pq_process_cb pq_process_cb
Definition ziti.h:252
void * app_ctx
Definition ziti.h:255
Definition ziti_model.h:282
Definition ziti_model.h:284
Definition ziti_model.h:266
void(* ziti_ext_signers_cb)(ziti_context, int err, ziti_jwt_signer_array, void *)
Definition ziti.h:493
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)
ziti_conn_cb ziti_listen_cb
Defines the ziti_listen_cb.
Definition ziti.h:368
int ziti_dial(ziti_connection conn, const char *service, ziti_conn_cb cb, ziti_data_cb data_cb)
Establishes connection to a Ziti service.
void(* ziti_terminator_cb)(ziti_context ztx, const ziti_terminator *const *terminators, int status, void *ctx)
callback providing the list of terminators
Definition ziti.h:108
int ziti_ext_auth_token(ziti_context ztx, const char *token)
void(* ziti_close_cb)(ziti_connection conn)
Callback called after connection was closed.
Definition ziti.h:393
void * ziti_conn_data(ziti_connection conn)
Retrieves any custom data associated with the given ziti_connection.
void(* ziti_extend_cert_authenticator_cb)(ziti_context ztx, const char *cert_pem, int status, void *ctx)
Extend Certificate Authenticator Callback.
Definition ziti.h:1045
ziti_context ziti_conn_context(ziti_connection conn)
Return Ziti context for given connection.
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.
Definition ziti.h:205
struct ziti_conn * ziti_connection
Represents a Ziti connection.
Definition ziti.h:82
void ziti_mfa_enroll(ziti_context ztx, ziti_mfa_enroll_cb enroll_cb, void *ctx)
Attempts to initialize MFA enrollment.
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.
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.
int ziti_refresh(ziti_context ztx)
Trigger refresh ahead of normal refresh cycle.
void(* ziti_ext_auth_launch_cb)(ziti_context ztx, const char *url, void *ctx)
Callback called by ziti_ext_auth to complete external authentication.
Definition ziti.h:886
int ziti_load_config(ziti_config *config, const char *conf_str)
Load ziti identity config from memory or file.
struct ziti_ctx * ziti_context
Represents the Ziti Edge identity context.
Definition ziti.h:67
void(* ziti_pr_domain_cb)(ziti_context ztx, const char *id, const char *domain)
Posture response Domain callback.
Definition ziti.h:146
const char * ziti_conn_source_identity(ziti_connection conn)
Get the identity of the client that initiated the ziti_connection.
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_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.
const ziti_service * ziti_service_for_addr_str(ziti_context ztx, ziti_protocol proto, const char *addr, int port)
void * ziti_app_ctx(ziti_context ztx)
returns ziti_options.app_ctx for the given Ziti context.
void ziti_set_app_info(const char *app_id, const char *app_version)
Provide app information to Ziti SDK.
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)
void(* ziti_conn_cb)(ziti_connection conn, int status)
Connection callback.
Definition ziti.h:338
void ziti_conn_set_data(ziti_connection conn, void *data)
Set or clear custom data associated with the given ziti_connection.
int ziti_close(ziti_connection conn, ziti_close_cb close_cb)
Closes the given connection.
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()
Definition ziti.h:899
void(* ziti_pq_domain_cb)(ziti_context ztx, const char *id, ziti_pr_domain_cb response_cb)
Posture Query for Domain callback.
Definition ziti.h:159
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.
Definition ziti.h:174
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.
Definition ziti.h:358
int ziti_conn_set_data_cb(ziti_connection conn, ziti_data_cb cb)
Set new data callback on ziti connection.
void(* ziti_mfa_enroll_cb)(ziti_context ztx, int status, ziti_mfa_enrollment *mfa_enrollment, void *ctx)
Callback called after ziti_mfa_enroll()
Definition ziti.h:866
void(* ziti_mfa_cb)(ziti_context ztx, int status, void *ctx)
Generic callback called after various MFA functions.
Definition ziti.h:876
const char * ziti_get_controller(ziti_context ztx)
controller URL of the given context
void ziti_set_enabled(ziti_context ztx, bool enabled)
Enable or disable given Ziti context.
const ziti_version * ziti_get_version()
return SDK version
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_listen_with_options(ziti_connection serv_conn, const char *service, ziti_listen_opts *listen_opts, ziti_listen_cb lcb, ziti_client_cb cb)
void(* ziti_service_cb)(ziti_context ztx, const ziti_service *, int status, void *data)
Service status callback.
Definition ziti.h:94
const char * ziti_get_appdata_raw(ziti_context ztx, const char *key)
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_listen(ziti_connection serv_conn, const char *service, ziti_listen_cb lcb, ziti_client_cb cb)
Start accepting ziti client connections.
ssize_t(* ziti_data_cb)(ziti_connection conn, const uint8_t *data, ssize_t length)
Data callback.
Definition ziti.h:324
int ziti_context_set_options(ziti_context ztx, const ziti_options *options)
int ziti_close_write(ziti_connection conn)
Closes the outgoing (write) side of the given ziti connection.
int ziti_shutdown(ziti_context ztx)
Shutdown Ziti Edge identity context and reclaim the memory from the provided ziti_context.
int ziti_context_run(ziti_context ztx, uv_loop_t *loop)
void(* ziti_verify_extend_cert_authenticator_cb)(ziti_context ztx, int status, void *ctx)
Verify Extend Certificate Authenticator Callback.
Definition ziti.h:1077
int ziti_get_appdata(ziti_context ztx, const char *key, void *data, int(*parse_func)(void *, const char *, size_t))
int ziti_get_transfer_rates(ziti_context ztx, double *up, double *down)
Retrieve current transfer rates.
void ziti_mfa_verify(ziti_context ztx, char *code, ziti_mfa_cb verify_cb, void *ctx)
Attempts to verify MFA enrollment.
void(* ziti_pr_mac_cb)(ziti_context ztx, const char *id, char **mac_addresses, int num_mac)
Posture response MAC address callback.
Definition ziti.h:122
bool ziti_is_enabled(ziti_context ztx)
return if context is enabled
int ziti_context_init(ziti_context *ztx, const ziti_config *config)
int ziti_conn_init(ziti_context ztx, ziti_connection *conn, void *data)
Initializes a 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.
void ziti_mfa_remove(ziti_context ztx, const char *code, ziti_mfa_cb remove_cb, void *ctx)
Attempts to remove MFA.
int ziti_ext_auth(ziti_context ztx, ziti_ext_auth_launch_cb launch_cb, void *ctx)
Authenticate with an external JWT signer.
int ziti_accept(ziti_connection clt, ziti_conn_cb cb, ziti_data_cb data_cb)
Completes client connection.
int ziti_conn_bridge_idle_timeout(ziti_connection conn, unsigned long millis)
set idle timeout on bridged connection.
int ziti_use_ext_jwt_signer(ziti_context ztx, const char *name)
select external JWT signer to initiate OIDC authentication flow
int ziti_list_terminators(ziti_context ztx, const char *service, ziti_terminator_cb cb, void *ctx)
List all terminators for the given service.
void(* ziti_pq_mac_cb)(ziti_context ztx, const char *id, ziti_pr_mac_cb response_cb)
Posture Query for MAC addresses callback.
Definition ziti.h:133
const ziti_service * ziti_service_for_addr(ziti_context ztx, ziti_protocol proto, const ziti_address *addr, int port)
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.
void(* ziti_pq_os_cb)(ziti_context ztx, const char *id, ziti_pr_os_cb response_cb)
Posture Query for OS callback.
Definition ziti.h:187
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.
void(* ziti_write_cb)(ziti_connection conn, ssize_t status, void *write_ctx)
Callback called after ziti_write() is complete.
Definition ziti.h:382
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.
Definition ziti.h:220
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_event_cb)(ziti_context ztx, const ziti_event_t *event)
Ziti Event callback.
Definition ziti.h:234
const ziti_version * ziti_get_controller_version(ziti_context ztx)
return Ziti controller version for given context
int ziti_conn_bridge(ziti_connection conn, uv_handle_t *handle, uv_close_cb on_close)
Bridge [ziti_connection] to a given IO stream.
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.
const ziti_identity * ziti_get_identity(ziti_context ztx)
Ziti identity of the given context.
ziti_jwt_signer ** ziti_jwt_signer_array
Definition ziti_model.h:268
ziti_protocol
Definition ziti_model.h:247