-
Notifications
You must be signed in to change notification settings - Fork 14
/
ziti.h
1106 lines (1000 loc) · 41.7 KB
/
ziti.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// Copyright (c) 2022-2024. NetFoundry Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
//
// You may obtain a copy of the License at
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
/**
* @file ziti.h
* @brief Defines the macros, functions, typedefs and constants required to interface with a Ziti Network.
*/
#ifndef ZITI_ZITI_H
#define ZITI_ZITI_H
#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"
#ifdef __cplusplus
extern "C" {
#endif
/**
* Flag indicating service `Dial` permission
*/
#define ZITI_CAN_DIAL 1U
/**
* Flag indicating service `Bind` permission
*/
#define ZITI_CAN_BIND 2U
/**
* The default timeout in milliseconds for connection operations to succeed.
*/
#define ZITI_DEFAULT_TIMEOUT 10000
/**
* @brief 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 ziti_context_init(), ziti_shutdown()
*/
typedef struct ziti_ctx *ziti_context;
/**
* @brief 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 ziti_conn_init(), ziti_close()
*/
typedef struct ziti_conn *ziti_connection;
/**
* @brief 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 ziti_service_available(), ZITI_ERRORS
*/
typedef void (*ziti_service_cb)(ziti_context ztx, ziti_service *, int status, void *data);
/**
* @brief Posture response MAC address callback
*
* This callback should be invoked after gathering the relevant MAC Addresses
* available during a ziti_pq_mac_cb()
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param mac_addresses an array of the mac addresses the host currently has access to. Values should be hex strings. Nil signifies not supported.
* @param num_mac the size of the mac_addresses array
*
* @see ziti_pq_mac_cb()
*/
typedef void (*ziti_pr_mac_cb)(ziti_context ztx, const char *id, char **mac_addresses, int num_mac);
/**
* @brief 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 ziti_pr_mac_cb
*/
typedef void (*ziti_pq_mac_cb)(ziti_context ztx, const char *id, ziti_pr_mac_cb response_cb);
/**
* @brief Posture response Domain callback
*
* This callback should be invoked after gathering the relevant Domain
* of the host during a ziti_pq_domain_cb()
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param domain the domain the host has joint or nil if not supported
*
* @see ziti_pq_domain_cb()
*/
typedef void (*ziti_pr_domain_cb)(ziti_context ztx, const char *id, const char *domain);
/**
* @brief 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.
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param response_cb the callback to invoke to supply values
*
* @see ziti_pr_domain_cb
*/
typedef void (*ziti_pq_domain_cb)(ziti_context ztx, const char *id, ziti_pr_domain_cb response_cb);
/**
* @brief Posture response OS callback
*
* This callback should be invoked after gathering the relevant OS versions
* of the host during a ziti_pq_os_cb()
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param os_type the OS type: Windows, Linux, Android, macOS, iOS
* @param os_version the OS version or kernel version
* @param os_build the build of the OS or nil if not supported
*
* @see ziti_pq_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);
/**
* @brief 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.
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param response_cb the callback to invoke to supply values
*
* @see ziti_pr_os_cb
*/
typedef void (*ziti_pq_os_cb)(ziti_context ztx, const char *id, ziti_pr_os_cb response_cb);
/**
* @brief Posture response process callback
*
* This callback should be invoked after gathering the relevant process information
* from the host during a ziti_pq_process_cb()
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param path the path of the inspect process
* @param is_running if the process is running
* @param sha_512_hash the sha512 hash of the process's binary file
* @param signers sha1 hex string fingerprints of the binary or nil if not supported
* @param num_signers the number of signers
*
* @see ziti_pq_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);
/**
* @brief 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
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param path the process path to inspect
* @param response_cb the callback to invoke
*
* @see ziti_pr_process_cb
*/
typedef void (*ziti_pq_process_cb)(ziti_context ztx, const char *id, const char *path,
ziti_pr_process_cb response_cb);
/**
* @brief 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 ziti_event_type
* @see ziti_event_t
* @see ziti_options.event_cb
* @see ziti_options.events
*/
typedef void (*ziti_event_cb)(ziti_context ztx, const ziti_event_t *event);
/**
* @brief ziti_context runtime options
*
* @see ziti_context_set_options()
*/
typedef struct ziti_options_s {
bool disabled; // if true initial state will be disabled
const char **config_types;
unsigned int api_page_size;
long refresh_interval; //the duration in seconds between checking for updates from the controller
rate_type metrics_type; //an enum describing the metrics to collect
//posture query cbs
ziti_pq_mac_cb pq_mac_cb;
ziti_pq_os_cb pq_os_cb;
ziti_pq_process_cb pq_process_cb;
ziti_pq_domain_cb pq_domain_cb;
void *app_ctx;
/**
* \brief subscribed event types.
*/
unsigned int events;
/**
* \brief callback invoked is response to subscribed events.
*/
ziti_event_cb event_cb;
} ziti_options;
typedef struct ziti_enroll_opts_s {
const char *jwt;
const char *enroll_key;
const char *enroll_cert;
const char *enroll_name;
const char *jwt_content;
bool use_keychain; // use keychain if generating new key
} ziti_enroll_opts;
typedef struct ziti_dial_opts_s {
/** enable stream semantics
* this allows SDK to consolidate multiple write requests to lower overlay overhead
*/
bool stream;
int connect_timeout_seconds;
char *identity;
void *app_data;
size_t app_data_sz;
} ziti_dial_opts;
typedef struct ziti_client_ctx_s {
char *caller_id;
const uint8_t *app_data;
size_t app_data_sz;
} ziti_client_ctx;
typedef enum ziti_terminator_precedence_e {
PRECEDENCE_DEFAULT = 0,
PRECEDENCE_REQUIRED,
PRECEDENCE_FAILED
} ziti_terminator_precedence;
typedef struct ziti_listen_opts_s {
uint16_t terminator_cost;
uint8_t terminator_precedence;
int connect_timeout_seconds;
int max_connections;
char *identity;
bool bind_using_edge_identity;
} ziti_listen_opts;
/**
* @brief 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.
*
* @param conn The Ziti connection which received the data
* @param data incoming data buffer
* @param length size of data or error code as defined in #ZITI_ERRORS (will receive #ZITI_EOF
* when connection is closed)
*
* @return indicate how much data was consumed
* @see ziti_dial(), ziti_accept(), ZITI_ERRORS
*/
typedef ssize_t (*ziti_data_cb)(ziti_connection conn, const uint8_t *data, ssize_t length);
/**
* @brief 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.
*
* @param conn the Ziti connection struct
* @param status the result of the function. #ZITI_OK if successful otherwise see #ZITI_ERRORS
*
* @see ziti_dial(), ziti_accept(), ZITI_ERRORS
*/
typedef void (*ziti_conn_cb)(ziti_connection conn, int status);
/**
* @brief 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.
*
* @param serv hosting connection, initialized with ziti_listen()
* @param client client connection - generally passed to ziti_accept() in this function
* @param status #ZITI_OK or error
* @param ctx object containing application data passed by dialing identity, \see ziti_dial_opts.
* the reference to this object is only valid for the duration of the callback.
*
* @see ziti_listen(), ZITI_ERRORS
*/
typedef void (*ziti_client_cb)(ziti_connection serv, ziti_connection client, int status, const ziti_client_ctx *ctx);
/**
* @brief 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 ziti_listen()
*/
typedef ziti_conn_cb ziti_listen_cb;
/**
* @brief 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 ziti_write(), ZITI_ERRORS
*/
typedef void (*ziti_write_cb)(ziti_connection conn, ssize_t status, void *write_ctx);
/**
* @brief Callback called after ziti_enroll() is complete.
*
* This callback is invoked on the conclusion of the ziti_enroll() function. The result of the
* ziti_enroll() function may be an error condition so it is important to verify the provided
* status code in this callback.
*
* This callback also receives a Ziti identity json salvo if the enrollment was successful.
* This identity should be persisted into a file, and used in subsequent calls to ziti_load_config().
*
* @param cfg identity config object, NULL if enrollment fails for any reason
* @param status enrollment success or error code
* @param err_message description of error, or NULL if enrollment succeeded
* @param enroll_ctx additional context to be passed into #ziti_enroll_cb callback
*
* @see ziti_enroll(), ZITI_ERRORS
*/
typedef void (*ziti_enroll_cb)(const ziti_config *cfg, int status, const char *err_message, void *enroll_ctx);
/**
* @brief Callback called after connection was closed.
*
* @param conn connection that was closed
*
* @see ziti_close()
*/
typedef void (*ziti_close_cb)(ziti_connection conn);
/**
* @brief Performs a Ziti enrollment.
*
* This function is used to enroll a Ziti Edge identity. The Ziti C SDK is based around the [libuv](http://libuv.org/)
* library and maintains similar semantics. This function is used to setup the chain of callbacks
* needed once the loop begins to execute.
*
* @param opt enrollment options
* @param loop libuv event loop
* @param enroll_cb callback to be called when enrollment is complete
* @param enroll_ctx additional context to be passed into #ziti_enroll_cb callback
* @return #ZITI_OK or corresponding #ZITI_ERRORS
*/
ZITI_FUNC
extern int ziti_enroll(const ziti_enroll_opts *opts, uv_loop_t *loop,
ziti_enroll_cb enroll_cb, void *enroll_ctx);
/**
* Provide app information to Ziti SDK.
*
* App information is reported to Ziti Controller. Supplying this information is optional.
*/
ZITI_FUNC
extern void ziti_set_app_info(const char *app_id, const char *app_version);
/**
* 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.
* @param config target ziti_config object
* @param conf_str identity config JSON or path to a file.
* @return ZITI_OK on success or error code
*/
ZITI_FUNC
extern int ziti_load_config(ziti_config *config, const char* conf_str);
ZITI_FUNC
extern int ziti_context_init(ziti_context *ztx, const ziti_config *config);
ZITI_FUNC
extern int ziti_context_set_options(ziti_context ztx, const ziti_options *options);
ZITI_FUNC
extern int ziti_context_run(ziti_context ztx, uv_loop_t *loop);
/**
* \brief 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.
* @param ztx
* @return #ZITI_OK on success, or error code
*/
ZITI_FUNC
extern int ziti_refresh(ziti_context ztx);
/**
* return if context is enabled
* @param ztx ziti context
* @return
*/
ZITI_FUNC
extern bool ziti_is_enabled(ziti_context ztx);
/**
* Enable or disable given Ziti context.
* @param ztx
* @param enabled
*/
ZITI_FUNC
extern void ziti_set_enabled(ziti_context ztx, bool enabled);
/**
* @brief returns ziti_options.app_ctx for the given Ziti context.
*
* @param ztx
* @return application context that was passed as ziti_oprions.app_ctx
*/
ZITI_FUNC
extern void *ziti_app_ctx(ziti_context ztx);
/**
* @brief return SDK version
* @return SDK version
*/
ZITI_FUNC
extern const ziti_version *ziti_get_version();
/**
* @brief return Ziti controller version for given context
* @param ztx ziti context
* @return controller version
*/
ZITI_FUNC
extern const ziti_version *ziti_get_controller_version(ziti_context ztx);
/**
* @brief controller URL of the given context
* @param ztx ziti context
* @return controller URL
*/
ZITI_FUNC
extern const char *ziti_get_controller(ziti_context ztx);
/**
* @brief Ziti identity of the given context.
* @param ztx ziti context
* @return ziti identity
*/
ZITI_FUNC
extern const ziti_identity *ziti_get_identity(ziti_context ztx);
typedef void (*ziti_ext_signers_cb)(ziti_context, int err, ziti_jwt_signer_array, void*);
/**
* \brief 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]).
*
* @param ztx ziti context
* @param cb callback for the result
* @param ctx callback context
* @return
*/
ZITI_FUNC
extern int ziti_get_ext_jwt_signers(ziti_context ztx, ziti_ext_signers_cb cb, void *ctx);
/**
* \brief select external JWT signer to initiate OIDC authentication flow
*
* @param ztx ziti context
* @param name name of JWT signer configured for the ziti network
* @return
*/
ZITI_FUNC
extern int ziti_use_ext_jwt_signer(ziti_context ztx, const char *name);
/**
* @brief Retrieve current transfer rates. Rates are in bytes/second.
*
* Calculation is using 1 minute EWMA.
* @param ztx ziti context
* @param up rate of bytes going up
* @param down rate of bytes going down
*/
ZITI_FUNC
extern void ziti_get_transfer_rates(ziti_context ztx, double *up, double *down);
/**
* @brief Shutdown Ziti Edge identity context and reclaim the memory from the provided #ziti_context.
*
* @param ztx the Ziti Edge identity context to be shut down. this reference is not safe to use after this call
*
* @return #ZITI_OK or corresponding #ZITI_ERRORS
*/
ZITI_FUNC
extern int ziti_shutdown(ziti_context ztx);
/**
* @brief 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:
* \code
* ziti_dump(ztx, fprintf, stderr);
* \endcode
*
* @param ztx the Ziti Edge identity context to print debug information for
* @param printer function to be called for output
* @param ctx first argument passed into `printer` function
*/
ZITI_FUNC
extern void ziti_dump(ziti_context ztx, int (*printer)(void *ctx, const char *fmt, ...), void *ctx);
ZITI_FUNC
const char *ziti_get_appdata_raw(ziti_context ztx, const char *key);
ZITI_FUNC
int ziti_get_appdata(ziti_context ztx, const char *key, void *data,
int (*parse_func)(void *, const char *, size_t));
/**
* @brief 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.
*
* @param ztx the Ziti Edge identity context to initialize the connection with
* @param conn an uninitialized #ziti_connection to be initialized
* @param data additional context to carry forward in ziti_dial() and ziti_listen() related callbacks
*
* @return #ZITI_OK or corresponding #ZITI_ERRORS
*
* @see ziti_dial(), ziti_listen(), ZITI_ERRORS
*/
ZITI_FUNC
extern int ziti_conn_init(ziti_context ztx, ziti_connection *conn, void *data);
/**
* @brief Return Ziti context for given connection.
*
* @param conn ziti connection
* @return ziti context connection belongs to
*/
ZITI_FUNC
extern ziti_context ziti_conn_context(ziti_connection conn);
/**
* @brief 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.
*
* @param conn the #ziti_connection to retrieve the context from
*
* @return custom data passed into ziti_conn_init()
*/
ZITI_FUNC
extern void *ziti_conn_data(ziti_connection conn);
/**
* @brief 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.
*
* @param conn the #ziti_connection to set the context to
* @param data custom data
*
* @see ziti_conn_data(), ziti_conn_init()
*/
ZITI_FUNC
extern void ziti_conn_set_data(ziti_connection conn, void *data);
/**
* @brief 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.
*
* @param conn
* @param cb
* @return ZITI_OK or error code
*/
ZITI_FUNC
extern int ziti_conn_set_data_cb(ziti_connection conn, ziti_data_cb cb);
/**
* @brief Get the identity of the client that initiated the #ziti_connection.
*
* @return identity of the client that requested the connection.
*/
ZITI_FUNC
extern const char *ziti_conn_source_identity(ziti_connection conn);
/**
* @brief 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.
*
* @param ztx the Ziti Edge identity context to use to check for the service's availability on
* @param service the name of the service to check
* @param cb callback called with #ZITI_OK or #ZITI_SERVICE_NOT_AVAILABLE
* @param ctx additional context to be passed to the #ziti_service_cb
*
* @return #ZITI_OK or corresponding #ZITI_ERRORS
*/
ZITI_FUNC
extern int ziti_service_available(ziti_context ztx, const char *service, ziti_service_cb cb, void *ctx);
ZITI_FUNC
extern const ziti_service *ziti_service_for_addr_str(ziti_context ztx, ziti_protocol proto, const char *addr, int port);
ZITI_FUNC
extern const ziti_service *ziti_service_for_addr(ziti_context ztx, ziti_protocol proto, const ziti_address *addr, int port);
/**
* @brief 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.
*
* @param conn the #ziti_connection to use in the dial operation
* @param service the name of the service to dial
* @param cb invoked after the dial operation completes
* @param data_cb invoked if the dial operation succeeds with data received over the connection
*
* @return #ZITI_OK or corresponding #ZITI_ERRORS
*
* @see ziti_dial(), ziti_write()
*/
ZITI_FUNC
extern int ziti_dial(ziti_connection conn, const char *service, ziti_conn_cb cb, ziti_data_cb data_cb);
ZITI_FUNC
extern 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);
/**
* @brief 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.
*
* @param serv_conn the #ziti_connection acting as a server which will be hosting the service
* @param service the name of the service to be hosted
* @param lcb invoked after the function completes
* @param cb a callback invoked when when client is attempting to connect to advertised service
*
* @return #ZITI_OK or corresponding #ZITI_ERRORS
*
* @see ziti_accept()
*/
ZITI_FUNC
extern int ziti_listen(ziti_connection serv_conn, const char *service, ziti_listen_cb lcb, ziti_client_cb cb);
ZITI_FUNC
extern 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);
/**
* @brief 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.
*
* @param clt a #ziti_connection representing the incoming client connection
* @param cb a callback invoked when the function completes
* @param data_cb a callback invoked each time the client sends data
*
* @return #ZITI_OK or corresponding #ZITI_ERRORS
*
* @see ziti_listen()
*/
ZITI_FUNC
extern int ziti_accept(ziti_connection clt, ziti_conn_cb cb, ziti_data_cb data_cb);
/**
* @brief Closes the given connection.
*
* When no longer needed a [connection](#ziti_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.
*
* @param conn the #ziti_connection to be closed
* @param close_cb callback called after connection is closed
*
* @return #ZITI_OK
* #ZITI_CONN_CLOSED if connection was already ziti_close() was already called on the given connection
* other #ZITI_ERRORS
*/
ZITI_FUNC
extern int ziti_close(ziti_connection conn, ziti_close_cb close_cb);
/**
* @brief 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.
*
* @param conn the #ziti_connection to be closed
*
* @return #ZITI_OK or corresponding #ZITI_ERRORS
*/
ZITI_FUNC
extern int ziti_close_write(ziti_connection conn);
/**
* @brief 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.
*
* @param conn the #ziti_connection used to write data to
* @param data a buffer of data to write over the provided #ziti_connection
* @param length the length of data in the data buffer to send. Make sure to not specify
* @param write_cb a callback invoked after the function completes indicating the buffer can now be reclaimed
* @param write_ctx additional context to be passed to the #ziti_write_cb callback
*
* @return #ZITI_OK or corresponding #ZITI_ERRORS
*/
ZITI_FUNC
extern int ziti_write(ziti_connection conn, uint8_t *data, size_t length, ziti_write_cb write_cb, void *write_ctx);
/**
* @brief 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.
*
* @param conn
* @param handle IO handle, must be a stream (UV_TCP, UV_PIPE, UV_TTY) or a UV_UDP handle
* @param on_close
* @return 0 on success, error code on failure
*/
ZITI_FUNC
extern int ziti_conn_bridge(ziti_connection conn, uv_handle_t *handle, uv_close_cb on_close);
/**
* set idle timeout on bridged connection.
* @param conn ziti_connection previously bridged with [ziti_conn_bridge] or [ziti_conn_bridge_fds]
* @param millis timeout after which bridge will be closed absent any traffic
* @return 0 on success, error code on failure
*/
ZITI_FUNC
extern int ziti_conn_bridge_idle_timeout(ziti_connection conn, unsigned long millis);
/**
* @brief 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.
*
* @param conn
* @param input
* @param output
* @param close_cb
* @param ctx
* @return
*/
ZITI_FUNC
extern 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);
/**
* @brief 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.
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param status an error code or #ZITI_OK
* @param mfa_enrollment contents of the mfa enrollment or NULL if status is an error
* @param ctx additional context to be passed into #ziti_mfa_enroll_cb callback
*
*/
typedef void (*ziti_mfa_enroll_cb)(ziti_context ztx, int status, ziti_mfa_enrollment *mfa_enrollment, void *ctx);
/**
* @brief Generic callback called after various MFA functions
*
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param status an error code or #ZITI_OK
* @param ctx additional context to be passed into the original mfa call
*/
typedef void (*ziti_mfa_cb)(ziti_context ztx, int status, void *ctx);
/**
* @brief 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.
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param status an error code or #ZITI_OK
* @param recovery_codes null terminated array of recovery codes
* @param ctx additional context to be passed into to the original call
*
*/
typedef void (*ziti_mfa_recovery_codes_cb)(ziti_context ztx, int status, const char **recovery_codes, void *ctx);
/**
* @brief 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.
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param ziti_mfa_enroll_cb callback to receive MFA enrollment initialization status
* @param ctx additional context to be passed into the enroll_cb callback
*/
ZITI_FUNC
extern void ziti_mfa_enroll(ziti_context ztx, ziti_mfa_enroll_cb enroll_cb, void *ctx);
/**
* @brief 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.
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param code a TOTP or recovery code, may be empty string for MFA enrollments that have not completed via ziti_mfa_verify
* @param remove_cb callback to receive MFA removal status
* @param ctx additional context to be passed into the remove_cb callback
*/
ZITI_FUNC
extern void ziti_mfa_remove(ziti_context ztx, const char *code, ziti_mfa_cb remove_cb, void *ctx);
/**
* @brief 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.
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param code a valid TOTP code, must not be a recovery code
* @param remove_cb callback to receive MFA verify status
* @param ctx additional context to be passed into the verify_cb callback
*
* @return #ZITI_OK or corresponding #ZITI_ERRORS
*/
ZITI_FUNC
extern void ziti_mfa_verify(ziti_context ztx, char *code, ziti_mfa_cb verify_cb, void *ctx);
/**
* @brief 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.
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param code a TOTP code, may be empty string for MFA enrollments that have not completed vi ziti_mfa_verify
* @param remove_cb callback to receive the result status
* @param ctx additional context to be passed into the get_cb callback
*/
ZITI_FUNC
extern void ziti_mfa_get_recovery_codes(ziti_context ztx, const char *code, ziti_mfa_recovery_codes_cb get_cb, void *ctx);
/**
* @brief 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.
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param code a TOTP code
* @param new_cb callback to receive the result status
* @param ctx additional context to be passed into the get_cb callback
*/
ZITI_FUNC
extern void ziti_mfa_new_recovery_codes(ziti_context ztx, char *code, ziti_mfa_recovery_codes_cb new_cb, void *ctx);
/**
* @brief 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.
*
* @param ztx the handle to the Ziti Edge identity context needed for other Ziti C SDK functions
* @param code a TOTP code
* @param auth_cb callback to receive the result status
* @param ctx additional context to be passed into the callback
*/