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
|
<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 stls library interface</title>
<meta name="Description" content="s6-networking: the stls library interface" />
<meta name="Keywords" content="s6-networking net stls library TLS SSL LibreSSL OpenSSL libtls" />
<!-- <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>stls</tt> library interface </h1>
<h2> General information </h2>
<p>
<tt>libstls</tt> is a small 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://www.libressl.org/">LibreSSL</a>
backend. You can use it in your own programs, but since
<a href="https://man.openbsd.org/OpenBSD-current/man3/tls_init.3">libtls</a>
is already relatively high-level, it's probably not very useful.
</p>
<h2> Compiling </h2>
<ul>
<li> Make sure the s6-networking headers, as well as the skalibs headers,
and the <tt>tls.h</tt> header, are visible in your header search path. </li>
<li> Use <tt>#include <s6-networking/stls.h></tt> </li>
</ul>
<h2> Linking </h2>
<ul>
<li> Make sure the s6-networking libraries, as well as the skalibs
libraries, and the LibreSSL libraries, are visible in your library search path. </li>
<li> Link against <tt>-lstls</tt>, <tt>-lskarnet</tt>, <tt>-ltls</tt>,
<tt>-lssl</tt>, <tt>-lcrypto</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> Running the TLS/SSL engine </h3>
<h4> <code> int stls_run (struct tls *ctx, int *fds, pid_t pid, unsigned int verbosity, uint32_t options, tain_t const *tto) </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) or a given subprocess dies.
</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
handshake must already be completed. </li>
<li> <em>fds</em> is an array of 5 file descriptors, in this
order: fd reading clear text, fd writing clear text, fd reading
ciphertext, fd writing ciphertext, selfpipe. </li>
<li> <em>pid</em> is the pid of the application subprocess.
When a SIGCHLD is detected on the selfpipe, the newly deceased
process is reaped, and if it was <em>pid</em>, then the function
returns as soon as it doesn't have anything left to write to
the network peer. </li>
<li> <em>verbosity</em> defines the engine's verbosity: the
higher the more verbose. This parameter is currently ignored. </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>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>
</ul>
<p>
<tt>stls_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, it returns -1. If the application
subprocess dies early, <tt>stls_run</tt> returns the <em>wstat</em>
for that subprocess, i.e. the integer containing the information about
its exit code or crash signal. No matter how <tt>stls_run</tt> returns,
the first four descriptors in <em>fds</em> are closed, but the
selfpipe is untouched and the caller should free <em>ctx</em> itself.
</p>
<h4> <code> int stls_s6tlsc (char const *const *argv, char const *const *envp, tain_t const *tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity, char const *servername, int *sfd) </code> </h4>
<p>
This function implements <a href="../s6-tlsc.html">s6-tlsc</a> on top of LibreSSL.
It has no other practical purpose; you're better off directly invoking
<a href="../s6-tlsc.html">s6-tlsc</a>.
</p>
<h4> <code> int stls_s6tlsd (char const *const *argv, char const *const *envp, tain_t const *tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity) </code> </h4>
<p>
This function implements <a href="../s6-tlsd.html">s6-tlsd</a> on top of LibreSSL.
It has no other practical purpose; you're better off directly invoking
<a href="../s6-tlsd.html">s6-tlsd</a>.
</p>
</body>
</html>
|
