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
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="css/simple.css">
<link rel="stylesheet" href="css/screen.css">
<title>API Docs - Documentation</title>
</head>
<body>
<header>
<h1>Documentation</h1>
<p>eduVPN for Linux</p>
<nav>
<a href="index.html">About</a>
<a href="building.html">Building</a>
<a href="testing.html">Testing</a>
<a href="building-client.html">Building a client</a>
<a href="apidocs.html">API Docs</a>
</nav>
</header>
<main>
<aside>
<ul>
<li class="nav-item" data-level="2"><a href="#addserver" class="nav-link">AddServer</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#calculategateway" class="nav-link">CalculateGateway</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#cleanup" class="nav-link">Cleanup</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#cookiecancel" class="nav-link">CookieCancel</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#cookiedelete" class="nav-link">CookieDelete</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#cookienew" class="nav-link">CookieNew</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#cookiereply" class="nav-link">CookieReply</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#currentserver" class="nav-link">CurrentServer</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#deregister" class="nav-link">Deregister</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#discoorganizations" class="nav-link">DiscoOrganizations</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#discoservers" class="nav-link">DiscoServers</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#expirytimes" class="nav-link">ExpiryTimes</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#freestring" class="nav-link">FreeString</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#getconfig" class="nav-link">GetConfig</a>
<ul class="nav flex-column">
<li class="nav-item" data-level="3"><a href="#ask_profile" class="nav-link">ASK_PROFILE</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="3"><a href="#ask_location" class="nav-link">ASK_LOCATION</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="3"><a href="#oauth_started" class="nav-link">OAUTH_STARTED</a>
<ul class="nav flex-column">
</ul>
</li>
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#instate" class="nav-link">InState</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#newproxyguard" class="nav-link">NewProxyguard</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#proxyguardpeerips" class="nav-link">ProxyguardPeerIPs</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#proxyguardrestart" class="nav-link">ProxyguardRestart</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#proxyguardtunnel" class="nav-link">ProxyguardTunnel</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#register" class="nav-link">Register</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#removeserver" class="nav-link">RemoveServer</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#renewsession" class="nav-link">RenewSession</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#serverlist" class="nav-link">ServerList</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#setprofileid" class="nav-link">SetProfileID</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#setsecurelocation" class="nav-link">SetSecureLocation</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#setstate" class="nav-link">SetState</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#settokenhandler" class="nav-link">SetTokenHandler</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-level="2"><a href="#startfailover" class="nav-link">StartFailover</a>
<ul class="nav flex-column">
</ul>
</li>
</ul>
</aside>
<p>This document was automatically generated from the exports/exports.go file</p>
<h1 id="about-the-api">About the API<a class="headerlink" href="#about-the-api" title="Permanent link">#</a></h1>
<p>Some notes:</p>
<ul>
<li>
<p>Errors are returned as JSON c strings. The JSON type is defined in
<code>types/error/error.go Error</code>. Free them using <code>FreeString</code>. Same is the case for
other string types, you should also free them. The errors are always localized</p>
</li>
<li>
<p>Types are converted from the Go representation to C using JSON strings</p>
</li>
<li>
<p>Cookies are used for cancellation, just fancy contexts. Create a cookie using
<code>CookieNew</code>, pass it to the function that needs one as the first argument. To
cancel the function, call <code>CookieCancel</code>, passing in the same cookie as argument</p>
</li>
<li>
<p>Cookies must also be freed, by using the CookieDelete function if the cookie
is no longer needed</p>
</li>
<li>
<p>The state machine is used to track the state of a client. It is mainly used
for asking for certain data from the client, e.g. asking for profiles and
locations. But a client may also wish to build upon this state machine to build
the whole UI around it. The SetState and InState functions are useful for this</p>
</li>
</ul>
<h1 id="functions">Functions<a class="headerlink" href="#functions" title="Permanent link">#</a></h1>
<h2 id="addserver">AddServer<a class="headerlink" href="#addserver" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func AddServer(c C.uintptr_t, _type C.int, id *C.char, ot *C.longlong) *C.char
</code></pre>
<p>AddServer adds a server to the eduvpn-common server list <code>c</code> is the cookie
that is used for cancellation. Create a cookie first with CookieNew.
This same cookie is also used for replying to state transitions.</p>
<p><code>_type</code> is the type of server that needs to be added. This type is defined
in <code>types/server/server.go Type</code></p>
<p><code>id</code> is the identifier of the string:</p>
<ul>
<li>In case of secure internet: The organization ID</li>
<li>In case of custom server: The base URL</li>
<li>In case of institute access: The base URL</li>
</ul>
<p><code>ni</code> stands for non-interactive. If non-zero, any state transitions will not
be run.</p>
<p>This <code>ot</code> flag is useful for preprovisioned servers; set this to non-null to
non-interactively add a server. This flag represents the Unix time OAuth was
last triggered, if the server needs to be added non-interactively but there
is no token structure, set this to zero (integer) or the current Unix time.
This value will be overwritten once OAuth is triggered.</p>
<p>If the server cannot be added it returns the error as <code>types/error/error.go
Error</code>. Note that the server is removed when an error has occured</p>
<p>The following state callbacks are mandatory to handle:</p>
<ul>
<li>OAUTH_STARTED: This indicates that the OAuth procedure has been started,
it returns the URL as the data. The client should open the webbrowser
with this URL and continue the authorization process. Note: For mobile
platforms this returns a Cookie and data (json: <code>{"cookie": x, "data":
url}</code>). This <code>url</code> should also be opened in the browser like desktop
platforms. But these platforms also need to reply to the library to give
back the full authorization code URI with <code>CookieReply(x, uri)</code>. E.g.
<code>CookieReply(x, "/callback?code=...&state=...&iss=...")</code> this is the
path of the request that the apps get back when the user clicks approve.
For this, apps need to register an app url or sorts. For the valid
values for app URLs, see the redirect URIs for mobile platforms here
https://git.sr.ht/~fkooman/vpn-user-portal/tree/v3/item/src/OAuth/VpnClientDb.php</li>
</ul>
<p>Example Input (3=custom server): <code>AddServer(mycookie, 3,
"https://demo.eduvpn.nl", 0)</code></p>
<p>Example Output:</p>
<pre><code>{
"message": {
"en": "failed to add server"
},
"misc": false
}
</code></pre>
<h2 id="calculategateway">CalculateGateway<a class="headerlink" href="#calculategateway" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func CalculateGateway(subnet *C.char) (*C.char, *C.char)
</code></pre>
<p>CalculateGateway calculates the gateway for a subnet, it can take IPv4 or
IPv6 networks with CIDR notation as inputs and returns the gateway address.</p>
<p>This is useful to pass to <code>StartFailover</code>.
It returns an error if it fails to calculate a gateway.
The function is implemented according to: <a href="https://docs.eduvpn.org/server/v3/client-implementation-notes.html#fail-over">the eduVPN
docs</a>.</p>
<p>Example Input: <code>CalculateGateway("10.10.0.5/24")</code></p>
<p>Example Output: <code>"10.10.0.1", null</code></p>
<h2 id="cleanup">Cleanup<a class="headerlink" href="#cleanup" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func Cleanup(c C.uintptr_t) *C.char
</code></pre>
<p>Cleanup sends a <code>/disconnect</code> to cleanup the connection.</p>
<p>This MUST be called when disconnecting, see <a href="https://docs.eduvpn.org/server/v3/api.html#application-flow">the eduVPN
docs</a>. <code>c</code> is
the Cookie that needs to be passed. Create a new Cookie using <code>CookieNew</code>.</p>
<p>If it was unsuccessful, it returns an error.</p>
<p>Example Input: <code>Cleanup(myCookie)</code></p>
<p>Example Output:</p>
<pre><code>{
"message": {
"en": "cleanup was not successful"
},
"misc": false
}
</code></pre>
<h2 id="cookiecancel">CookieCancel<a class="headerlink" href="#cookiecancel" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func CookieCancel(c C.uintptr_t) *C.char
</code></pre>
<p>CookieCancel cancels the cookie.</p>
<p>This means that functions which take this as first argument,
return if they’re still running. The error cause is always
<code>context.Canceled</code> for that cancelled function: <a href="https://pkg.go.dev/context#pkg-variables">see the Go
docs</a>.</p>
<p>This CookieCancel function can also return an error if cancelling was
unsuccessful. Example Input: <code>CookieCancel(myCookie)</code></p>
<p>Example Output: null</p>
<h2 id="cookiedelete">CookieDelete<a class="headerlink" href="#cookiedelete" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func CookieDelete(c C.uintptr_t) *C.char
</code></pre>
<p>CookieDelete deletes the cookie by cancelling it and deleting the underlying
cgo handle.</p>
<p>This function MUST be called when the cookie that is created using
<code>CookieNew</code> is no longer needed. Example Input: <code>CookieDelete(myCookie)</code></p>
<p>Example Output: null</p>
<h2 id="cookienew">CookieNew<a class="headerlink" href="#cookienew" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func CookieNew() C.uintptr_t
</code></pre>
<p>CookieNew creates a new cookie and returns it. Functions that take a cookie
have it as the first argument.</p>
<p>This value should not be parsed or converted somehow by the client. This
value is simply to pass back to the Go library. This value has two purposes:</p>
<ul>
<li>Cancel a long running function</li>
<li>Send a reply to a state transition (ASK_PROFILE and ASK_LOCATION)</li>
</ul>
<p>Example Input: <code>CookieNew()</code></p>
<p>Example Output: <code>5</code></p>
<h2 id="cookiereply">CookieReply<a class="headerlink" href="#cookiereply" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func CookieReply(c C.uintptr_t, data *C.char) *C.char
</code></pre>
<p>CookieReply replies to a state transition using the cookie.</p>
<ul>
<li><code>c</code> is the Cookie</li>
<li><code>data</code> is the data to send, e.g. a profile ID</li>
</ul>
<p>Example Input: <code>CookieReply(myCookie, "split-tunnel-profile")</code></p>
<p>Example Output: <code>null</code></p>
<h2 id="currentserver">CurrentServer<a class="headerlink" href="#currentserver" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func CurrentServer() (*C.char, *C.char)
</code></pre>
<p>CurrentServer gets the current server from eduvpn-common</p>
<p>In eduvpn-common, a server is marked as ‘current’ if you have gotten a VPN
configuration for it</p>
<p>It returns the server as JSON, defined in <code>types/server/server.go Current</code>.</p>
<p>If there is no current server or some other, e.g. there is no current state,
an error is returned with a nil string.</p>
<p>Example Input: <code>CurrentServer()</code></p>
<p>Example Output:</p>
<pre><code>{
"institute_access_server": {
"display_name": {
"en": "Demo"
},
"identifier": "https://demo.eduvpn.nl/",
"profiles": {
"map": {
"internet": {
"display_name": {
"en": "Internet"
},
"supported_protocols": [
1,
2
]
},
"internet-split": {
"display_name": {
"en": "No rfc1918 routes"
},
"supported_protocols": [
1,
2
]
}
},
"current": "internet"
},
"support_contacts": [
"mailto:eduvpn@surf.nl"
],
"delisted": false
},
"server_type": 1
}, null
</code></pre>
<h2 id="deregister">Deregister<a class="headerlink" href="#deregister" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func Deregister() *C.char
</code></pre>
<p>Deregister cleans up the state for the client.</p>
<p>This function SHOULD be called when the application exits such that the
configuration file is saved correctly. Note that saving of the configuration
file also happens in other cases, such as after getting a VPN configuration.
Thus it is often not problematic if this function cannot be called due to a
client crash.</p>
<p>If no client is available or deregistering fails, it returns an error.</p>
<p>Example Input: <code>Deregister()</code></p>
<p>Example Output:</p>
<pre><code>{
"message": {
"en": "failed to deregister"
},
"misc": false
}
</code></pre>
<h2 id="discoorganizations">DiscoOrganizations<a class="headerlink" href="#discoorganizations" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func DiscoOrganizations(c C.uintptr_t, cache C.int, search *C.char) (*C.char, *C.char)
</code></pre>
<p>DiscoOrganizations gets the organizations from discovery, returned as
<code>types/discovery/discovery.go Organizations</code> marshalled as JSON.</p>
<ul>
<li><code>c</code> is the Cookie that needs to be passed. Create a new Cookie using
<code>CookieNew</code></li>
<li><code>cache</code> indicates whether or not the cache should only be used, meaning
no network call</li>
<li><code>search</code> is the search string for filtering the list.</li>
</ul>
<p>If any of the words in the <code>search</code> query is not contained in
any of the display names or keywords, the candidate is filtered.
Otherwise they are ranked based on the levenshtein distance: <a href="https://en.wikipedia.org/wiki/Levenshtein_distance">Levenshtein
Wikipedia</a>. If <code>search</code>
is empty it returns ALL organizations currently known in common</p>
<p>If it was unsuccessful, it returns an error. Note that when the lib was
built in release mode the data is almost always non-nil, even when an error
has occurred This means it has just returned the cached list, the error
should then not be handled in a fatal way. E.g. show the returned cache list
but log the error or show the error with a warning.</p>
<p>Example Input: <code>DiscoOrganizations(myCookie, "")</code></p>
<p>Example Output:</p>
<pre><code>{
"organization_list": [
{
"display_name": {
"en": "Academic Network of Albania - RASH"
},
"org_id": "https://idp.rash.al/simplesaml/saml2/idp/metadata.php",
},
{
"display_name": {
"da": "Dansk Sprognævn",
"en": "Danish Language Council"
},
"org_id": "http://idp.dsn.dk/adfs/services/trust",
},
{
"display_name": {
"da": "Erhvervsakademi Aarhus",
"en": "Business Academy Aarhus"
},
"org_id": "http://adfs.eaaa.dk/adfs/services/trust",
}, null
</code></pre>
<p>Example Input: <code>DiscoOrganizations(myCookie, "rash")</code></p>
<p>Example Output:</p>
<pre><code> {
"organization_list": [
{
"display_name": {
"en": "Academic Network of Albania - RASH"
},
"org_id": "https://idp.rash.al/simplesaml/saml2/idp/metadata.php",
},
]
}, null
</code></pre>
<h2 id="discoservers">DiscoServers<a class="headerlink" href="#discoservers" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func DiscoServers(c C.uintptr_t, cache C.int, search *C.char) (*C.char, *C.char)
</code></pre>
<p>DiscoServers gets the servers from discovery, returned as
<code>types/discovery/discovery.go Servers</code> marshalled as JSON</p>
<ul>
<li><code>c</code> is the Cookie that needs to be passed. Create a new Cookie using
<code>CookieNew</code></li>
<li><code>cache</code> indicates whether or not the cache should only be used, meaning
no network call</li>
<li><code>search</code> is the search string for filtering the list.</li>
</ul>
<p>If any of the words in the search query is not contained in any of
the display names or keywords, the candidate is filtered. Otherwise
they are ranked based on the levenshtein distance: <a href="https://en.wikipedia.org/wiki/Levenshtein_distance">Levenshtein
Wikipedia</a>. If <code>search</code>
is empty it returns ALL servers currently known in common</p>
<p>If it was unsuccessful, it returns an error. Note that when the lib was
built in release mode the data is almost always non-nil, even when an error
has occurred. This means it has just returned the cached list, the error
should then not be handled in a fatal way. E.g. show the returned cache list
but log the error or show the error with a warning.</p>
<p>Example Input: <code>DiscoServers(myCookie, "")</code></p>
<p>Example Output:</p>
<pre><code> {
"server_list": [
{
"base_url": "https://eduvpn.rash.al/",
"country_code": "AL",
"server_type": "secure_internet",
},
{
"base_url": "https://eduvpn.deic.dk/",
"country_code": "DK",
"server_type": "secure_internet",
} , null
</code></pre>
<p>Example Input: <code>DiscoServers(myCookie, "heanet")</code></p>
<p>Example Output:</p>
<pre><code> {
"server_list": [
{
"base_url": "https://eduvpn.heanet.ie/",
"display_name": {
"en": "HEAnet Staff"
},
"server_type": "institute_access",
},
]
} , null
</code></pre>
<h2 id="expirytimes">ExpiryTimes<a class="headerlink" href="#expirytimes" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func ExpiryTimes() (*C.char, *C.char)
</code></pre>
<p>ExpiryTimes gets the expiry times for the current server</p>
<p>Expiry times are just fields that represent unix timestamps at which to
do certain events regarding expiry, e.g. when to show the renew button,
when to show expiry notifications</p>
<p>The expiry times structure is defined in <code>types/server/server.go Expiry</code> If
some error occurs, it is returned as <code>types/error/error.go Error</code></p>
<p>Example Input: <code>ExpiryTimes()</code></p>
<p>Example Output (1…4 are unix timestamps):</p>
<pre><code>{
"start_time": 1,
"end_time": 2,
"button_time": 3,
"countdown_time": 4,
"notification_times": [
1,
2,
],
}, null
</code></pre>
<h2 id="freestring">FreeString<a class="headerlink" href="#freestring" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func FreeString(addr *C.char)
</code></pre>
<p>FreeString frees a string that was allocated by the eduvpn-common Go
library.</p>
<p>This happens when we return strings, such as errors from the Go lib back to
the client. The client MUST thus ensure that this memory is freed using this
function. Simply pass the pointer to the string in here.</p>
<p>Example Input: <code>FreeString(strPtr)</code></p>
<h2 id="getconfig">GetConfig<a class="headerlink" href="#getconfig" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func GetConfig(c C.uintptr_t, _type C.int, id *C.char, pTCP C.int, startup C.int) (*C.char, *C.char)
</code></pre>
<p>GetConfig gets a configuration for the server.</p>
<p><code>c</code> is the cookie that is used for cancellation. Create a cookie first with
CookieNew, this same cookie is also used for replying to state transitions</p>
<p><code>_type</code> is the type of server that needs to be added. This type is defined
in <code>types/server/server.go Type</code></p>
<p><code>id</code> is the identifier of the string</p>
<ul>
<li>In case of secure internet: The organization ID</li>
<li>In case of custom server: The base URL</li>
<li>In case of institute access: The base URL</li>
</ul>
<p><code>pTCP</code> is if we prefer TCP or not to get the configuration, non-zero means
yes</p>
<p><code>startup</code> is if the client is just starting up, set this to true (non-zero)
if you autoconnect to a server on startup. If this startup value is true
(non-zero) then any authorization or other callacks (profile/location) are
not triggered</p>
<p>After getting a configuration, the FSM moves to the GOT_CONFIG state
The return data is the configuration, marshalled as JSON and defined in
<code>types/server/server.go Configuration</code></p>
<p>If the config cannot be retrieved it returns an error as
<code>types/error/error.go Error</code>.</p>
<p>The current state callbacks MUST be handled:</p>
<h3 id="ask_profile">ASK_PROFILE<a class="headerlink" href="#ask_profile" title="Permanent link">#</a></h3>
<p>This asks the client for profile.</p>
<p>This is called when the user/client has not set a profile for this server
before, or the current profile is invalid</p>
<p>When the user has selected a profile, reply with the choice using the
<code>CookieReply</code> function and the profile ID e.g. CookieReply(cookie,
“wireguard”). CookieReply can be done in the background as the Go library
waits for a reply</p>
<p>The data for this transition is defined in <code>types/server/server.go
RequiredAskTransition</code> with embedded data <code>Profiles</code> in
<code>types/server/server.go</code>. Note that <code>RequiredAskTransition</code> contains the
cookie to be used for the <code>CookieReply</code>.</p>
<p>So a client would:</p>
<ul>
<li>Parse the data to get the cookie and data</li>
<li>get the cookie</li>
<li>get the profiles from the data</li>
<li>show it in the UI and then reply with CookieReply using the choice</li>
</ul>
<h3 id="ask_location">ASK_LOCATION<a class="headerlink" href="#ask_location" title="Permanent link">#</a></h3>
<p>This asks the client for a location. Note that under normal circumstances,
this callback is not actually called as the home organization for the
secure internet server is set as the current if for some reason, an invalid
location has been configured, the library will ask the client for a new one</p>
<p>When the user has selected a location, reply with the choice using the
<code>CookieReply</code> function and the location ID e.g. CookieReply(cookie, “nl”)</p>
<p>CookieReply can be done in the background as the Go library waits for a
reply The data for this transition is defined in <code>types/server/server.go
RequiredAskTransition</code> with embedded data a list of strings (<code>[]string</code>)</p>
<p>Note that <code>RequiredAskTransition</code> contains the cookie to be used for the
<code>CookieReply</code> function,</p>
<p>So a client would:</p>
<ul>
<li>Parse the data to get the cookie and data</li>
<li>get the cookie</li>
<li>get the list of locations from the data</li>
<li>show it in the UI and then reply with CookieReply using the choice</li>
</ul>
<h3 id="oauth_started">OAUTH_STARTED<a class="headerlink" href="#oauth_started" title="Permanent link">#</a></h3>
<ul>
<li>OAUTH_STARTED: This indicates that the OAuth procedure has been started,
it returns the URL as the data. The client should open the webbrowser
with this URL and continue the authorization process. Note: For mobile
platforms this returns a Cookie and data (json: <code>{"cookie": x, "data":
url}</code>). This <code>url</code> should also be opened in the browser like desktop
platforms. But these platforms also need to reply to the library to give
back the full authorization code URI with <code>CookieReply(x, uri)</code>. E.g.
<code>CookieReply(x, "/callback?code=...&state=...&iss=...")</code> this is the
path of the request that the apps get back when the user clicks approve.
For this, apps need to register an app url or sorts. For the valid
values for app URLs, see the redirect URIs for mobile platforms here
https://git.sr.ht/~fkooman/vpn-user-portal/tree/v3/item/src/OAuth/VpnClientDb.php</li>
</ul>
<p>The client should open the webbrowser with this URL and continue the
authorization process. This is only called if authorization needs to be
retriggered</p>
<p>Example Input (3=custom server): <code>GetConfig(myCookie, 3,
"https://demo.eduvpn.nl/", 0, 0)</code></p>
<p>Example Output (2=WireGuard):</p>
<pre><code>{
"config": "[Interface]\nPrivateKey = ...\nAddress = ...\nDNS = ...\n\n[Peer]\nPublicKey = ...=\nAllowedIPs = 0.0.0.0/0,::/0\nEndpoint = ...",
"protocol": 2,
"default_gateway": true,
"should_failover": true, <- whether or not the failover procedure should happen
}
</code></pre>
<h2 id="instate">InState<a class="headerlink" href="#instate" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func InState(fsmState C.int) (C.int, *C.char)
</code></pre>
<p>InState checks if the FSM is in <code>fsmState</code>.</p>
<p>Example Input: <code>InState(5)</code></p>
<p>Example Output: <code>1, null</code></p>
<h2 id="newproxyguard">NewProxyguard<a class="headerlink" href="#newproxyguard" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func NewProxyguard(c C.uintptr_t, lp C.int, tcpsp C.int, peer *C.char, proxySetup C.ProxySetup) (C.uintptr_t, *C.char)
</code></pre>
<p>NewProxyguard creates the ‘proxyguard’ procedure in eduvpn-common. If the
proxy cannot be created it returns an error.</p>
<p>This function proxies WireGuard UDP connections over HTTP: <a href="https://codeberg.org/eduvpn/proxyguard">ProxyGuard on
Codeberg</a>.</p>
<p>These input variables can be gotten from the configuration that is retrieved
using the <code>proxy</code> JSON key</p>
<ul>
<li><code>c</code> is the cookie. Note that if you cancel/delete the cookie,
ProxyGuard gets cleaned up. Common automatically cleans up ProxyGuard
when <code>Cleanup</code> is called, but it is good to cleanup yourself too.</li>
<li><code>lp</code> is the <code>port</code> of the local udp ProxyGuard connection, this is what
is set to the WireGuard endpoint</li>
<li><code>tcpsp</code> is the TCP source port. Pass 0 if you do not route based on
source port, so far only the Linux client has to pass non-zero.</li>
<li><code>peer</code> is the <code>ip:port</code> of the remote server</li>
<li><code>proxySetup</code> is a callback which is called when the socket is setting
up, this can be used for configuring routing in the client. It takes
two arguments: the file descriptor (integer) and a JSON list of IPs the
client connects to</li>
</ul>
<p>Example Input: <code>NewProxyguard(myCookie, 1337, 0, "5.5.5.5:51820",
proxySetupCB)</code></p>
<p>Example Output: <code>null</code></p>
<h2 id="proxyguardpeerips">ProxyguardPeerIPs<a class="headerlink" href="#proxyguardpeerips" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func ProxyguardPeerIPs(proxyH C.uintptr_t) (*C.char, *C.char)
</code></pre>
<p>ProxyguardPeerIPs gets the Peer IPs configured by ProxyGuard Example Input:
<code>ProxyguardPeerIPs(handle)</code></p>
<p>Example Output: <code>["1.1.1.1"], null</code></p>
<h2 id="proxyguardrestart">ProxyguardRestart<a class="headerlink" href="#proxyguardrestart" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func ProxyguardRestart(proxyH C.uintptr_t) *C.char
</code></pre>
<p>ProxyguardRestart restarts ProxyGuard, call this when a network change
happens</p>
<p>Example Input: <code>ProxyguardRestart(proxyHandle)</code></p>
<p>Example Output: <code>"failed restarting ProxyGuard"</code></p>
<h2 id="proxyguardtunnel">ProxyguardTunnel<a class="headerlink" href="#proxyguardtunnel" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func ProxyguardTunnel(c C.uintptr_t, proxyH C.uintptr_t, wglisten C.int) *C.char
</code></pre>
<p>ProxyguardTunnel starts the tunneling for ProxyGuard <code>c</code> is the cookie
<code>proxyH</code> is the proxy handle <code>wglisten</code> is the port WireGuard is listening
on</p>
<h2 id="register">Register<a class="headerlink" href="#register" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func Register(
name *C.char,
version *C.char,
configDirectory *C.char,
cb C.StateCB,
) *C.char
</code></pre>
<p>Register creates a new client and also registers the FSM to go to the
initial state</p>
<p><code>Name</code> is the name of the client, must be a valid client ID.</p>
<p><code>Version</code> is the version of the client. This version field is used for the
user agent in all HTTP requests.</p>
<p><code>cb</code> is the state callback. It takes three arguments: The old state, the new
state and the data for the state as JSON.</p>
<ul>
<li>
<p>Note that the states are defined in client/fsm.go, e.g. <code>Main</code> (in Go:
<code>StateMain</code>), <code>ASK_PROFILE</code> (in Go: <code>StateAskProfile</code>)</p>
</li>
<li>
<p>This callback returns non-zero if the state transition is handled.
This is used to check if the client handles the needed transitions</p>
</li>
</ul>
<p>After registering, the FSM is initialized and the state transition <code>MAIN</code>
should have been completed If some error occurs during registering, it is
returned as a <code>types/error/error.go Error</code></p>
<p>Example Input: <code>Register("org.eduvpn.app.linux", "0.0.1",
"/tmp/eduvpn-common", myCallbackFunc, 1)</code></p>
<p>Example Output:</p>
<pre><code>{
"message": {
"en": "failed to register, a VPN state is already present"
},
"misc": false
}
</code></pre>
<h2 id="removeserver">RemoveServer<a class="headerlink" href="#removeserver" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func RemoveServer(_type C.int, id *C.char) *C.char
</code></pre>
<p>RemoveServer removes a server from the eduvpn-common server list</p>
<p><code>_type</code> is the type of server that needs to be added. This type is defined
in <code>types/server/server.go Type</code></p>
<p><code>id</code> is the identifier of the string:</p>
<ul>
<li>In case of secure internet: The organization ID</li>
<li>In case of custom server: The base URL</li>
<li>In case of institute access: The base URL</li>
</ul>
<p>If the server cannot be removed it returns the error <code>types/error/error.go
Error</code>.</p>
<p>Example Input (3=custom server): <code>RemoveServer(3, "bogus")</code></p>
<p>Example Output:</p>
<pre><code>{
"message": {
"en": "failed to remove server"
},
"misc": false
}
</code></pre>
<h2 id="renewsession">RenewSession<a class="headerlink" href="#renewsession" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func RenewSession(c C.uintptr_t) *C.char
</code></pre>
<p>RenewSession renews the session of the VPN</p>
<p>This essentially means that the OAuth tokens are deleted. And it also
possibly re-runs every state callback you need when getting a config.
So least you MUST handle the OAuth started transition</p>
<p>It returns an error if unsuccessful. Example Input:
<code>RenewSession(myCookie)</code></p>
<p>Example Output:</p>
<pre><code>{
"message": {
"en": "could not renew session"
},
"misc": false
}
</code></pre>
<h2 id="serverlist">ServerList<a class="headerlink" href="#serverlist" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func ServerList() (*C.char, *C.char)
</code></pre>
<p>ServerList gets the list of servers that are currently added</p>
<p>This is NOT the discovery list, but the servers that have previously been
added with <code>AddServer</code>.</p>
<p>It returns the server list as a JSON string defined in
<code>types/server/server.go List</code>. If the server list cannot be retrieved it
returns a nil string and an error.</p>
<p>Example Input: <code>ServerList()</code></p>
<p>Example Output (current profile here is empty as none has been chosen yet):</p>
<pre><code>{
"institute_access_servers": [
{
"display_name": {
"en": "Demo"
},
"identifier": "https://demo.eduvpn.nl/",
"profiles": {
"current": ""
},
"support_contacts": [
"mailto:eduvpn@surf.nl"
],
"delisted": false
}
]
}, null
</code></pre>
<h2 id="setprofileid">SetProfileID<a class="headerlink" href="#setprofileid" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func SetProfileID(data *C.char) *C.char
</code></pre>
<p>SetProfileID sets the profile ID of the current serrver.</p>
<p>This MUST only be called if the user/client wishes to manually set a profile
instead of the common lib asking for one using a transition.</p>
<ul>
<li><code>data</code> is the profile ID.</li>
</ul>
<p>It returns an error if unsuccessful. Example Input:
<code>SetProfileID("splittunnel")</code></p>
<p>Example Output:</p>
<pre><code>{
"message": {
"en": "profile does not exist"
},
"misc": false
}
</code></pre>
<h2 id="setsecurelocation">SetSecureLocation<a class="headerlink" href="#setsecurelocation" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func SetSecureLocation(orgID *C.char, cc *C.char) *C.char
</code></pre>
<p>SetSecureLocation sets the location for the secure internet server if it
exists.</p>
<p>This MUST only be called if the user/client wishes to manually set a
location instead of the common lib asking for one using a transition.</p>
<ul>
<li><code>orgID</code> is the organisation ID for the secure internet server</li>
<li><code>cc</code> is the location ID/country code</li>
</ul>
<p>It returns an error if unsuccessful. Example Input:
<code>SetSecureLocation("http://idp.geant.org/", "nl")</code></p>
<p>Example Output:</p>
<pre><code>{
"message": {
"en": "location does not exist"
},
"misc": false
}
</code></pre>
<h2 id="setstate">SetState<a class="headerlink" href="#setstate" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func SetState(fsmState C.int) *C.char
</code></pre>
<p>SetState sets the state of the state machine.</p>
<p>Note: this transitions the FSM into the new state without passing any data
to it. Example Input: <code>SetState(5)</code></p>
<p>Example Output: <code>null</code></p>
<h2 id="settokenhandler">SetTokenHandler<a class="headerlink" href="#settokenhandler" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func SetTokenHandler(getter C.TokenGetter, setter C.TokenSetter) *C.char
</code></pre>
<p>SetTokenHandler sets the token getters and token setters for OAuth.</p>
<p>Because the data that is saved does not contain OAuth tokens for server,
the common lib asks and sets the tokens using these callback functions.
The client can thus pass callbacks to this function so that the tokens can
be securely stored in a keyring.</p>
<p>The client must pass two callback arguments to this function:</p>
<ol>
<li>
<p><code>getter</code> is the void function that gets tokens from the client. It takes
three arguments:
- The <code>server</code> for which to get the tokens for, marshalled as JSON and
defined in <code>types/server/server.go Current</code>
- The <code>output</code> buffer
- The <code>length</code> of the output buffer. This ‘output buffer’ must contain the
tokens, marshalled as JSON that is defined in <code>types/server/server.go
Tokens</code></p>
</li>
<li>
<p><code>setter</code> is the void function that sets tokens. It takes two arguments:</p>
</li>
</ol>
<ul>
<li>The <code>server</code> for which to get the tokens for, marshalled as JSON and
defined in <code>types/server/server.go Current</code></li>
<li>The <code>tokens</code>, defined in <code>types/server/server.go Tokens</code> marshalled as
JSON</li>
</ul>
<p>It returns an error when the tokens cannot be set. Example Input:
<code>SetTokenHandler(getterFunc, setterFunc)</code></p>
<p>Example Output: <code>null</code></p>
<h2 id="startfailover">StartFailover<a class="headerlink" href="#startfailover" title="Permanent link">#</a></h2>
<p>Signature:</p>
<pre><code class="language-go">func StartFailover(c C.uintptr_t, gateway *C.char, mtu C.int, readRxBytes C.ReadRxBytes) (C.int, *C.char)
</code></pre>
<p>StartFailover starts the ‘failover’ procedure in eduvpn-common.</p>
<p>Failover has one primary goal: check if the VPN can reach the gateway.
This can be used to check whether or not the client needs to ‘failover’ to
prefer TCP (if currently using UDP). Which is useful to go from a broken
WireGuard connection to OpenVPN over TCP.</p>
<ul>
<li><code>c</code> is the cookie that is passed for cancellation. To create a cookie,
use the <code>CookieNew</code> function</li>
<li><code>gateway</code> is the gateway IP of the VPN. You MAY calculate this with the
<code>CalculateGateway</code> function</li>
<li><code>readRxBytes</code> is a function that returns the current rx bytes of the VPN
interface, this should return a <code>long long int</code> in c</li>
</ul>
<p>It returns a boolean whether or not the common lib has determined
that it cannot reach the gateway. Non-zero=dropped, zero=not dropped.
It also returns an error, if it fails to indicate if it has dropped or not.
In this case, dropped is also set to zero.</p>
<p>Example Input: <code>StartFailover(myCookie, "10.10.10.1", 1400,
myRxBytesReader)</code></p>
<p>Example Output: <code>1, null</code></p>
</main>
<footer>
<p>Documentation - eduVPN for Linux</p>
</footer>
</body>
</html>
|
