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
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>s6-networking: the sbearssl library interface</title>
<meta name="Description" content="s6-networking: the sbearssl interface" />
<meta name="Keywords" content="s6-networking net sbearssl library TLS SSL BearSSL libbearssl" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="../">s6-networking</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>sbearssl</tt> library interface </h1>
<h2> General information </h2>
<p>
<tt>libsbearssl</tt> is a support library for the
<a href="../s6-tlsc.html">s6-tlsc</a> and
<a href="../s6-tlsd.html">s6-tlsd</a> executables when they're built
against the <a href="https://bearssl.org/">BearSSL</a>
backend. Among other things, it offers interfaces to read private
keys and certificates from a Unix filesystem, which BearSSL does
not provide on its own.
</p>
<h2> Compiling </h2>
<ul>
<li> Make sure the s6-networking headers, as well as the skalibs headers,
and the <tt>bearssl.h</tt> header, are visible in your header search path. </li>
<li> Use <tt>#include <s6-networking/sbearssl.h></tt> </li>
</ul>
<h2> Linking </h2>
<ul>
<li> Make sure the s6-networking libraries, as well as the skalibs
libraries, and the BearSSL libraries, are visible in your library search path. </li>
<li> Link against <tt>-lsbearssl</tt>, <tt>-lskarnet</tt>, <tt>-lbearssl</tt>,
<tt>`cat $sysdeps/socket.lib`</tt>, <tt>`cat $sysdeps/spawn.lib`</tt>, and
<tt>`cat $sysdeps/sysclock.lib`</tt>, where <tt>$sysdeps</tt> is your skalibs
sysdeps directory. </li>
</ul>
<h2> Programming </h2>
<h3> General concepts </h3>
<p>
<a href="https://bearssl.org/">BearSSL</a> provides engines
to decode PEM objects and X.509 certificates, and to run a
TLS/SSL connection. However, it does not store such objects:
it never allocates memory, and does not interact with the
filesystem. <tt>sbearssl</tt> provides functions to
address this.
</p>
<p>
When reading an object into memory, <tt>sbearssl</tt> stores all
the bytes of the object in a
<a href="//skarnet.org/software/skalibs/libstddjb/stralloc.html">stralloc</a>,
and the <tt>sbearssl_*</tt> structures contain indices of bytes in that
stralloc. That allows the structures to remain valid even when the stralloc
contents get reallocated and move to some other place in the heap. After
you have finished adding data to the stralloc and are sure its contents
will not move again, you can use the
<tt>sbearssl_*_to</tt> functions to convert <tt>sbearssl_*</tt> structures
to the corresponding <tt>br_*</tt> structures (native BearSSL), which
contain pointers to memory.
</p>
<h3> Private keys (typically for servers) </h3>
<p>
BearSSL handles two types of private keys: RSA keys and
EC keys (i.e. points on an elliptic curve). <tt>sbearssl</tt>
adds some generic functions to handle keys no matter their
type.
</p>
<h4> <code> int sbearssl_rsa_skey_from (sbearssl_rsa_skey *l, br_rsa_private_key const *k, stralloc *sa) </code> </h4>
<p>
Converts the RSA private key from BearSSL format (reading from a structure pointed to by <em>k</em>)
to <tt>sbearssl</tt> format (writing to a structure pointed to by <em>l</em>).
The data from *<em>k</em>'s contents are copied into the stralloc in *<em>sa</em>.
The function returns 1 on success and 0 (and sets errno) on failure.
</p>
<h4> <code> void sbearssl_rsa_skey_to (sbearssl_rsa_skey const *l, br_rsa_private_key *k, char *s) </code> </h4>
<p>
Converts the RSA private key from <tt>sbearssl</tt> format (reading from a structure pointed to by <em>l</em>)
to BearSSL format (writing to a structure pointed to by <em>k</em>).
The indices in <em>l</em> must refer to data stored in the string <em>s</em>.
</p>
<h4> <code> int sbearssl_ec_skey_from (sbearssl_ec_skey *l, br_ec_private_key const *k, stralloc *sa) </code> </h4>
<p>
Converts the EC private key from BearSSL format (reading from a structure pointed to by <em>k</em>)
to <tt>sbearssl</tt> format (writing to a structure pointed to by <em>l</em>).
The data from *<em>k</em>'s contents are copied into the stralloc in *<em>sa</em>.
The function returns 1 on success and 0 (and sets errno) on failure.
</p>
<h4> <code> void sbearssl_ec_skey_to (sbearssl_ec_skey const *l, br_ec_private_key *k, char *s) </code> </h4>
<p>
Converts the EC private key from <tt>sbearssl</tt> format (reading from a structure pointed to by <em>l</em>)
to BearSSL format (writing to a structure pointed to by <em>k</em>).
The indices in <em>l</em> must refer to data stored in the string <em>s</em>.
</p>
<h4> <code> int sbearssl_skey_from (sbearssl_skey *l, br_skey const *k, stralloc *sa) </code> </h4>
<p>
Converts the private key from BearSSL format (reading from a structure pointed to by <em>k</em>)
to <tt>sbearssl</tt> format (writing to a structure pointed to by <em>l</em>).
The data from *<em>k</em>'s contents are copied into the stralloc in *<em>sa</em>.
The function returns 1 on success and 0 (and sets errno) on failure.
</p>
<h4> <code> void sbearssl_skey_to (sbearssl_skey const *l, br_skey *k, char *s) </code> </h4>
<p>
Converts the private key from <tt>sbearssl</tt> format (reading from a structure pointed to by <em>l</em>)
to BearSSL format (writing to a structure pointed to by <em>k</em>).
The indices in <em>l</em> must refer to data stored in the string <em>s</em>.
</p>
<h4> <code> int sbearssl_skey_readfile (char const *fn, sbearssl_skey *key, stralloc *sa) </code> </h4>
<p>
Reads a private key from the file named <em>fn</em> and stores it
in <tt>sbearssl</tt> format into the structure in *<em>key</em>,
the bytes of the key being added to the stralloc in *<em>sa</em>.
</p>
<p>
The private key in <em>fn</em> can be either DER-encoded (binary format)
or PEM-encoded (text format).
</p>
<p>
The function returns 0 on success. It returns a negative value in
case of a system error, in which case <tt>errno</tt> identifies the
error. It returns a positive value in case of an error returned by
a BearSSL decoder, in which case an appropriate message can be
obtained with the <tt>sbearssl_error_str()</tt> function.
</p>
<h3> Public keys </h3>
<p>
BearSSL handles two types of public keys: RSA keys and
EC keys (i.e. points on an elliptic curve). <tt>sbearssl</tt>
adds some generic functions to handle keys no matter their
type.
</p>
<p>
You normally should not handle public keys directly;
you should handle x509 certificate chains instead.
</p>
<h4> <code> int sbearssl_rsa_pkey_from (sbearssl_rsa_pkey *l, br_rsa_public_key const *k, stralloc *sa) </code> </h4>
<p>
Converts the RSA public key from BearSSL format (reading from a structure pointed to by <em>k</em>)
to <tt>sbearssl</tt> format (writing to a structure pointed to by <em>l</em>).
The data from *<em>k</em>'s contents are copied into the stralloc in *<em>sa</em>.
The function returns 1 on success and 0 (and sets errno) on failure.
</p>
<h4> <code> void sbearssl_rsa_pkey_to (sbearssl_rsa_pkey const *l, br_rsa_public_key *k, char *s) </code> </h4>
<p>
Converts the RSA public key from <tt>sbearssl</tt> format (reading from a structure pointed to by <em>l</em>)
to BearSSL format (writing to a structure pointed to by <em>k</em>).
The indices in <em>l</em> must refer to data stored in the string <em>s</em>.
</p>
<h4> <code> int sbearssl_ec_pkey_from (sbearssl_ec_skey *l, br_ec_public_key const *k, stralloc *sa) </code> </h4>
<p>
Converts the EC public key from BearSSL format (reading from a structure pointed to by <em>k</em>)
to <tt>sbearssl</tt> format (writing to a structure pointed to by <em>l</em>).
The data from *<em>k</em>'s contents are copied into the stralloc in *<em>sa</em>.
The function returns 1 on success and 0 (and sets errno) on failure.
</p>
<h4> <code> void sbearssl_ec_pkey_to (sbearssl_ec_pkey const *l, br_ec_public_key *k, char *s) </code> </h4>
<p>
Converts the EC public key from <tt>sbearssl</tt> format (reading from a structure pointed to by <em>l</em>)
to BearSSL format (writing to a structure pointed to by <em>k</em>).
The indices in <em>l</em> must refer to data stored in the string <em>s</em>.
</p>
<h4> <code> int sbearssl_pkey_from (sbearssl_pkey *l, br_x509_pkey const *k, stralloc *sa) </code> </h4>
<p>
Converts the public key from BearSSL format (reading from a structure pointed to by <em>k</em>)
to <tt>sbearssl</tt> format (writing to a structure pointed to by <em>l</em>).
The data from *<em>k</em>'s contents are copied into the stralloc in *<em>sa</em>.
The function returns 1 on success and 0 (and sets errno) on failure.
</p>
<h4> <code> void sbearssl_pkey_to (sbearssl_pkey const *l, br_x509_pkey *k, char *s) </code> </h4>
<p>
Converts the public key from <tt>sbearssl</tt> format (reading from a structure pointed to by <em>l</em>)
to BearSSL format (writing to a structure pointed to by <em>k</em>).
The indices in <em>l</em> must refer to data stored in the string <em>s</em>.
</p>
<h3> Generic PEM objects </h3>
<p>
You normally should not have to call these functions
directly. Instead, you should use the higher-level functions for
private keys, X509 certificate chains and trust anchors, which
will perform the PEM decoding for you.
</p>
<h4> <code> int sbearssl_pem_decode_from_buffer (buffer *b, genalloc *list, stralloc *sa) </code> </h4>
<p>
Decodes a PEM object, reading from the
<a href="//skarnet.org/software/skalibs/libstddjb/buffer.html">buffer</a>
in *<em>b</em>. The decoded bytes are appended to *<em>sa</em>.
<em>list</em> points to a
<a href="//skarnet.org/software/skalibs/libstddjb/genalloc.html">genalloc</a>
containing objects of type <tt>sbearssl_pemobject</tt>.
One <tt>sbearssl_pemobject</tt> is appended to the genalloc per PEM entity
decoded from the byte stream read from the buffer.
</p>
<p>
The function returns 0 on success. It returns a negative value in
case of a system error, in which case <tt>errno</tt> identifies the
error. It returns a positive value in case of an error returned by
a BearSSL decoder, in which case an appropriate message can be
obtained with the <tt>sbearssl_error_str()</tt> function.
</p>
<h4> <code> int sbearssl_pem_decode_from_string (char const *s, size_t len, genalloc *list, stralloc *sa) </code> </h4>
<p>
Decodes a PEM object from the <em>len</em> bytes pointed to by <em>s</em>.
The decoded bytes are appended to *<em>sa</em>.
<em>list</em> points to a
<a href="//skarnet.org/software/skalibs/libstddjb/genalloc.html">genalloc</a>
containing objects of type <tt>sbearssl_pemobject</tt>.
One <tt>sbearssl_pemobject</tt> is appended to the genalloc per PEM entity
found in the bytes in <em>s</em>.
</p>
<p>
The function returns 0 on success. It returns a negative value in
case of a system error, in which case <tt>errno</tt> identifies the
error. It returns a positive value in case of an error returned by
a BearSSL decoder, in which case an appropriate message can be
obtained with the <tt>sbearssl_error_str()</tt> function.
</p>
<h3> X.509 certificates (typically for servers) </h3>
<h4> <code> int sbearssl_cert_from (sbearssl_cert *l, br_x509_certificate const *k, stralloc *sa) </code> </h4>
<p>
Converts a certificate from BearSSL format (reading from a structure pointed to by <em>k</em>)
to <tt>sbearssl</tt> format (writing to a structure pointed to by <em>l</em>).
The data from *<em>k</em>'s contents are copied into the stralloc in *<em>sa</em>.
The function returns 1 on success and 0 (and sets errno) on failure.
</p>
<h4> <code> void sbearssl_cert_to (sbearssl_cert const *l, br_x509_certificate *k, char *s) </code> </h4>
<p>
Converts a certificate from <tt>sbearssl</tt> format (reading from a structure pointed to by <em>l</em>)
to BearSSL format (writing to a structure pointed to by <em>k</em>).
The indices in <em>l</em> must refer to data stored in the string <em>s</em>.
</p>
<h4> <code> int sbearssl_cert_readfile (char const *fn, genalloc *list, stralloc *sa) </code> </h4>
<p>
Reads one or more certificates from the file named <em>fn</em> and appends
them to the <a href="//skarnet.org/software/skalibs/libstddjb/genalloc.html">genalloc</a>
in *<em>list</em>, which is a dynamically growing list of
<tt>sbearssl_cert</tt> structures. The bytes of the
(maybe PEM-decoded, but still DER-encoded) certificate are
appended to the stralloc in *<em>sa</em>.
</p>
<p>
The <em>fn</em> file can be either DER-encoded (binary format)
or PEM-encoded (text format). If it is DER-encoded, it must
contain exactly one X.509 certificate. If it is PEM-encoded,
it may contain a chain of certificates as long as the PEM
file fits within the size limits.
</p>
<p>
<em>fn</em> must not be bigger than SBEARSSL_MAXCERTFILESIZE,
which is 8 kB. This function is meant to read individual
certificates, not files containing large certificate chains or
sets of trust anchors. To do that, use
<tt>sbearssl_cert_readbigpem()</tt> instead.
</p>
<p>
The function returns 0 on success. It returns a negative value in
case of a system error, in which case <tt>errno</tt> identifies the
error. It returns a positive value in case of an error returned by
a BearSSL decoder, in which case an appropriate message can be
obtained with the <tt>sbearssl_error_str()</tt> function.
</p>
<h4> <code> int sbearssl_cert_readbigpem (char const *fn, genalloc *, stralloc *sa) </code> </h4>
<p>
Reads one or more PEM-encoded certificates from the file named
<em>fn</em> and appends them to the
<a href="//skarnet.org/software/skalibs/libstddjb/genalloc.html">genalloc</a>
in *<em>list</em>, which is a dynamically growing list of
<tt>sbearssl_cert</tt> structures. The bytes of the PEM-decoded (but
still DER-encoded) certificates are appended to the stralloc
in *<em>sa</em>.
</p>
<p>
The function will refuse to read a file that is not valid PEM.
Inside the file, It will ignore PEM objects that are
not X.509 certificates.
</p>
<p>
The function returns 0 on success. It returns a negative value in
case of a system error, in which case <tt>errno</tt> identifies the
error. It returns a positive value in case of an error returned by
a BearSSL decoder, in which case an appropriate message can be
obtained with the <tt>sbearssl_error_str()</tt> function.
</p>
<h3> Trust anchors (typically for clients) </h3>
<p>
BearSSL clients do not use X.509-encoded certificates,
they use sets of <em>trust anchors</em>, i.e. structures
decoded from certificates representing (intermediate or)
root CAs.
</p>
<h4> <code> int sbearssl_ta_from (sbearssl_ta *l, br_x509_trust_anchor const *k, stralloc *sa) </code> </h4>
<p>
Converts a trust anchor from BearSSL format (reading from a structure pointed to by <em>k</em>)
to <tt>sbearssl</tt> format (writing to a structure pointed to by <em>l</em>).
The data from *<em>k</em>'s contents are copied into the stralloc in *<em>sa</em>.
The function returns 1 on success and 0 (and sets errno) on failure.
</p>
<h4> <code> void sbearssl_ta_to (sbearssl_ta const *l, br_x509_trust_anchor *k, char *s) </code> </h4>
<p>
Converts a trust anchor from <tt>sbearssl</tt> format (reading from a structure pointed to by <em>l</em>)
to BearSSL format (writing to a structure pointed to by <em>k</em>).
The indices in <em>l</em> must refer to data stored in the string <em>s</em>.
</p>
<h4> <code> int sbearssl_ta_readfile (char const *fn, genalloc *list, stralloc *sa) </code> </h4>
<p>
Reads a set of trust anchors from a PEM file named <em>fn</em>
which must contain a list of (intermediate or) root CA certificates.
The trust anchors are appended to the
<a href="//skarnet.org/software/skalibs/libstddjb/genalloc.html">genalloc</a>
in *<em>list</em>, which is a dynamically growing list of
<tt>sbearssl_ta</tt> structures. The contents of the trust anchors
are appended to *<em>sa</em>, which is a
<a href="//skarnet.org/software/skalibs/libstddjb/stralloc.html">stralloc</a>
used for storage.
</p>
<p>
The function returns 0 on success. It returns a negative value in
case of a system error, in which case <tt>errno</tt> identifies the
error. It returns a positive value in case of an error returned by
a BearSSL decoder, in which case an appropriate message can be
obtained with the <tt>sbearssl_error_str()</tt> function.
</p>
<h4> <code> int sbearssl_ta_readdir (char const *dir, genalloc *list, stralloc *sa) </code> </h4>
<p>
Reads a set of trust anchors from a directory named <em>dir</em>,
which must contain a list of (intermediate or) root CA certificates
stored as individual DER- or PEM-encoded files.
The trust anchors are appended to the
<a href="//skarnet.org/software/skalibs/libstddjb/genalloc.html">genalloc</a>
in *<em>list</em>, which is a dynamically growing list of
<tt>sbearssl_ta</tt> structures. The contents of the trust anchors
are appended to *<em>sa</em>, which is a
<a href="//skarnet.org/software/skalibs/libstddjb/stralloc.html">stralloc</a>
used for storage.
</p>
<p>
The function ignores files that do not contain valid DER
or PEM objects containing X.509 certificates representing
certification authorities.
</p>
<p>
The function returns 0 on success. It returns a negative value in
case of a system error, in which case <tt>errno</tt> identifies the
error. It returns a positive value in case of an error returned by
a BearSSL decoder, in which case an appropriate message can be
obtained with the <tt>sbearssl_error_str()</tt> function.
</p>
<h3> Miscellaneous utilities </h3>
<p>
You probably shouldn't need to call any of these functions
directly, except for the first one.
</p>
<h4> <code> char const *sbearssl_error_str (int err) </code> </h4>
<p>
Returns a fixed string containing an error message corresponding
to the <em>err</em> code, which must be non-negative. The return
value from a few <tt>sbearssl</tt> functions, if positive, can be
interpreted via this function.
</p>
<h4> <code> int sbearssl_isder (unsigned char const *s, size_t len) </code> </h4>
<p>
Tests whether the array of <em>len</em> bytes pointed to by <em>s</em>
looks like a DER-encoded object. Returns 1 if it does and 0 otherwise.
</p>
<h4> <code> int sbearssl_x509_minimal_set_tai (br_x509_minimal_context *ctx, tai_t t) </code> </h4>
<p>
Sets the validation time for the X.509 context in *<em>ctx</em> to
the absolute time contained in *<em>t</em>, which is a
<a href="//skarnet.org/software/skalibs/libstddjb/tai.html">tai_t</a>.
Returns 1 if it succeeds, or 0 if it fails - probably
because *<em>t</em> does not represent a valid time.
</p>
<h4> <code> int sbearssl_x509_minimal_set_tain (br_x509_minimal_context *ctx, tain_t a) </code> </h4>
<p>
Same as the above function, except the time is given as a
<a href="//skarnet.org/software/skalibs/libstddjb/tai.html">tain_t</a>,
i.e. a <tt>tai_t</tt> plus nanoseconds (which are simply ignored).
</p>
<h4> <code> void sbearssl_drop () </code> </h4>
<p>
If the process is running as root, then this function drops its privileges
(else it does nothing).
The gid to drop to is read from the TLS_GID environment variable; the uid to
drop to is read from the TLS_UID environment variable. If those variables
are not given, then the uid, or gid, or both, are not changed. If they
contain something else than numerical uid/gids, the process exits 111 with
an error message.
</p>
<h3> Running the TLS/SSL engine (internal function for both clients and servers) </h3>
<h4> <code> void sbearssl_run (br_ssl_engine_context *ctx, int *fds, tain_t const *tto, uint32_t options, unsigned int verbosity, sbearssl_handshake_cb_t_ref cb, sbearssl_handshake_cb_context_t *cbarg) </code> </h4>
<p>
This function runs a full-duplex TLS/SSL engine, reading/writing
clear text from/to two file descriptors, and writing/reading
ciphertext to/from two other file descriptors, until the
connection is closed both ways (either with a SSL close, or
with EOF). It does not return.
</p>
<ul>
<li> <em>ctx</em> is a pointer to a fully initialized context,
connected to <em>fds</em>[2] and <em>fds</em>[3]. The
TLS/SSL handshake does not have to be completed. </li>
<li> <em>fds</em> is an array of 4 file descriptors, in this
order: fd reading clear text, fd writing clear text, fd reading
ciphertext, fd writing ciphertext. </li>
<li> <em>tto</em> is a pointer to a
<a href="//skarnet.org/software/skalibs/libstddjb/tai.html">tain_t</a>
containing a relative time (i.e. a timeout) If *<em>tto</em> time elapses
with no application data being exchanged, the engine will forcibly close the
connection (with the method defined by <tt><em>options</em> & 1</tt>).
You can use <tt>&tain_infinite_relative</tt> as a value for <em>tto</em>
if you don't want the engine to ever timeout. </li>
<li> <em>options</em> is a bitfield.
<ul>
<li> bit 0 tells the engine how to behave when
the local application closes the connection (i.e. when the engine
reads EOF on <em>fds</em>[0]). If the bit is clear, then the
engine will perform as SSL close: it will send a SSL close_notify,
and stop processing incoming records, waiting for a peer
acknowledgement of the close_notify. If the bit is set, then the
engine will not send a close_notify but simply transmit EOF to
the peer, while continuing to process incoming records until it
gets EOF back. close_notify is secure when handling protocols that
are not auto-terminated (such as HTTP 0.9), but it does not permit
separate closing of both ways. EOF allows full-duplex until the
very end, but is insecure if the application protocol does not
know in advance how many bytes it should get. Modern application
protocols should all work with EOF. </li>
</ul> </li>
<li> <em>verbosity</em> defines the engine's verbosity: the
higher the more verbose. This parameter is currently ignored. </li>
<li> <em>cb</em> is a pointer to a callback function that will be called
once after the TLS handshake is performed. This function is called with
two arguments: <em>ctx</em> (a pointer to the current bearssl context),
and <em>cbarg</em> (a pointer to a caller-provided structure). </li>
<li> <em>cbarg</em> is a pointer to a structure provided by the caller.
It will be passed as a second argument to <em>cb</em> when the TLS
handshake has successfully completed. </li>
</ul>
<p>
<tt>sbearssl_run</tt> will make the process die with an appropriate error
message if it encounters an unrecoverable error. If there were no problems and the
SSL/TLS connection closed cleanly, the process exits 0.
</p>
<h3> Initializing and running the engine </h3>
<h4> <code> void sbearssl_client_init_and_run (int *fds, tain_t const *tto, uint32_t preoptions, uint32_t options, unsigned int verbosity, char const *servername, sbearssl_handshake_cb_t_ref cb, unsigned int notif) </code> </h4>
<p>
This function initializes a TLS context for a client-side connection,
then runs the TLS engine via a call to <tt>sbearssl_run()</tt>. The
function does not return.
If the context cannot be initialized, the process exits 96 with an
appropriate error message.
</p>
<p>
If the <tt>CADIR</tt> environment variable is set, then it must contain
the path of a directory containing the hashed names of the public
certificates identifying the trust anchors. Else, if the <tt>CAFILE</tt>
environment variable is set, then it must contain the path to a PEM file
containing all the certificates for the trust anchors. Else, the process
exits 100 with an error message.
</p>
<p>
The arguments are as follows:
</p>
<ul>
<li> <tt>fds</tt> : an array of 4 file descriptors, that are in this
order: the fd reading from the application (cleartext), the fd writing to the
application (cleartext), the fd reading from the network, the fd writing to
the network. </li>
<li> <tt>preoptions : a bitfield.
<ul>
<li> Bit 0: if clear, no client authentication is performed. If set,
the <tt>CERTFILE</tt> and <tt>KEYFILE</tt> environment variables are read,
they must contain the path to a valid client certificate and private key
(else the process exits 96); this certificate is then provided to the
server for client authentication. <strong>This feature is currently
unsupported and will not work; leave that bit clear for now.</strong> </li>
</ul> </li>
<li> <tt>options : a bitfield, which will be passed to
<tt>sbearssl_run()</tt>.
<ul>
<li> Bit 0: if clear, no close_notify is performed and the engine
will transmit EOF as received. If set, close_notify will be performed to
end the TLS connection. </li>
</ul> </li>
<li> <em>verbosity</em> defines the engine's verbosity: the
higher the more verbose. This parameter is currently ignored. </li>
<li> <tt>servername</tt> : the server name used for SNI. If NULL, then
no SNI is performed, which may be a security risk. </li>
<li> <tt>cb</tt> : a pointer to a callback function, that will be
passed as is to <tt>sbearssl_run()</tt>. </li>
<li> <tt>notif</tt> : an unsigned integer that will be embedded into
the <em>cbarg</em> structure that will be passed to <tt>sbearssl_run()</tt>.
It is used by <a href="../s6-tlsc-io.html">s6-tlsc-io</a> to identify a
valid fd on which to write SSL data information once the handshake has
completed. </li>
</ul>
<h4> <code> void sbearssl_server_init_and_run (int *fds, tain_t const *tto, uint32_t preoptions, uint32_t options, unsigned int verbosity, sbearssl_handshake_cb_t_ref cb, unsigned int notif) </code> </h4>
<p>
Same as the previous function, but on the server side. No <em>servername</em>
argument is required. The <tt>CERTFILE</tt> and <tt>KEYFILE</tt> environment
variables are mandatory, they point to the server's certificate and private
key. It is only necessary to set <tt>CADIR</tt> or <tt>CAFILE</tt> when bit
0 of <em>preoptions</em> is set <strong>(this functionality <em>is</em> supported server-side)</strong>,
in which case client authentication will be
requested, and a list of trust anchors (read from either the directory
in <tt>CADIR</tt> or the PEM file in <tt>CAFILE</tt>) will be used to verify
the client certificate.
</p>
</body>
</html>
|
