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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual is last updated 4 March 2015 for version
3.4.9 of GnuTLS.
Copyright (C) 2001-2015 Free Software Foundation, Inc.\\
Copyright (C) 2001-2015 Nikos Mavrogiannopoulos
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled "GNU Free
Documentation License". -->
<!-- Created by GNU Texinfo 6.0, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GnuTLS 3.4.9: Setting up the transport layer</title>
<meta name="description" content="GnuTLS 3.4.9: Setting up the transport layer">
<meta name="keywords" content="GnuTLS 3.4.9: Setting up the transport layer">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Function-and-Data-Index.html#Function-and-Data-Index" rel="index" title="Function and Data Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="How-to-use-GnuTLS-in-applications.html#How-to-use-GnuTLS-in-applications" rel="up" title="How to use GnuTLS in applications">
<link href="Asynchronous-operation.html#Asynchronous-operation" rel="next" title="Asynchronous operation">
<link href="Anonymous-credentials.html#Anonymous-credentials" rel="prev" title="Anonymous credentials">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space: nowrap}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: serif; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
body {
margin: 2%;
padding: 0 5%;
background: #ffffff;
}
h1,h2,h3,h4,h5 {
font-weight: bold;
padding: 5px 5px 5px 5px;
background-color: #c2e0ff;
color: #336699;
}
h1 {
padding: 2em 2em 2em 5%;
color: white;
background: #336699;
text-align: center;
letter-spacing: 3px;
}
h2 { text-decoration: underline; }
pre {
margin: 0 5%;
padding: 0.5em;
}
pre.example,pre.verbatim {
padding-bottom: 1em;
border: solid #c2e0ff;
background: #f0faff;
border-width: 1px 1px 1px 5px;
margin: 1em auto;
width: 90%;
}
div.node {
margin: 0 -5% 0 -2%;
padding: 0.5em 0.5em;
margin-top: 0.5em;
margin-bottom: 0.5em;
font-weight: bold;
}
dd, li {
padding-top: 0.1em;
padding-bottom: 0.1em;
}
div.float {
margin-bottom: 0.5em;
text-align: center;
}
table {
text-align: left;
margin-left:auto;
margin-right:auto;
border-spacing: 7px;
width: 50%;
}
th {
padding: 0;
color: #336699;
background-color: #c2e0ff;
border: solid #000000;
border-width: 0px;
margin: 1em auto;
text-align: center;
margin-left:auto;
margin-right:auto;
}
td {
padding: 0;
border: solid #000000;
background-color: #f0faff;
border-width: 0px;
margin: 1em auto;
text-align: left;
margin-left:auto;
margin-right:auto;
padding-left: 1em;
}
dl {
text-align: left;
margin-left:auto;
margin-right:auto;
width: 50%;
padding-left: 1em;
border: solid #c2e0ff;
background: #f0faff;
border-width: 5px 1px 1px 1px;
margin: 1em auto;
}
-->
</style>
</head>
<body lang="en">
<a name="Setting-up-the-transport-layer"></a>
<div class="header">
<p>
Next: <a href="TLS-handshake.html#TLS-handshake" accesskey="n" rel="next">TLS handshake</a>, Previous: <a href="Associating-the-credentials.html#Associating-the-credentials" accesskey="p" rel="prev">Associating the credentials</a>, Up: <a href="How-to-use-GnuTLS-in-applications.html#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Function-and-Data-Index.html#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Setting-up-the-transport-layer-1"></a>
<h3 class="section">6.5 Setting up the transport layer</h3>
<p>The next step is to setup the underlying transport layer details. The
Berkeley sockets are implicitly used by GnuTLS, thus a
call to <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005fint">gnutls_transport_set_int</a> would be sufficient to
specify the socket descriptor.
</p>
<dl compact="compact">
<dt><code><var>void</var> <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005fint">gnutls_transport_set_int</a> (gnutls_session_t <var>session</var>, int <var>i</var>)</code></dt>
<dt><code><var>void</var> <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005fint2">gnutls_transport_set_int2</a> (gnutls_session_t <var>session</var>, int <var>recv_int</var>, int <var>send_int</var>)</code></dt>
</dl>
<p>If however another transport layer than TCP is selected, then
a pointer should be used instead to express the parameter to be
passed to custom functions. In that case the following functions should
be used instead.
</p>
<dl compact="compact">
<dt><code><var>void</var> <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005fptr">gnutls_transport_set_ptr</a> (gnutls_session_t <var>session</var>, gnutls_transport_ptr_t <var>ptr</var>)</code></dt>
<dt><code><var>void</var> <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005fptr2">gnutls_transport_set_ptr2</a> (gnutls_session_t <var>session</var>, gnutls_transport_ptr_t <var>recv_ptr</var>, gnutls_transport_ptr_t <var>send_ptr</var>)</code></dt>
</dl>
<p>Moreover all of the following push and pull callbacks should be set.
</p>
<dl>
<dt><a name="index-gnutls_005ftransport_005fset_005fpush_005ffunction"></a>Function: <em>void</em> <strong>gnutls_transport_set_push_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_push_func <var>push_func</var>)</em></dt>
<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type.
</p>
<p><var>push_func</var>: a callback function similar to <code>write()</code>
</p>
<p>This is the function where you set a push function for gnutls to
use in order to send data. If you are going to use berkeley style
sockets, you do not need to use this function since the default
send(2) will probably be ok. Otherwise you should specify this
function for gnutls to be able to send data.
The callback should return a positive number indicating the
bytes sent, and -1 on error.
</p>
<p><code>push_func</code> is of the form,
ssize_t (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t);
</p></dd></dl>
<dl>
<dt><a name="index-gnutls_005ftransport_005fset_005fvec_005fpush_005ffunction"></a>Function: <em>void</em> <strong>gnutls_transport_set_vec_push_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_vec_push_func <var>vec_func</var>)</em></dt>
<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type.
</p>
<p><var>vec_func</var>: a callback function similar to <code>writev()</code>
</p>
<p>Using this function you can override the default writev(2)
function for gnutls to send data. Setting this callback
instead of <code>gnutls_transport_set_push_function()</code> is recommended
since it introduces less overhead in the TLS handshake process.
</p>
<p><code>vec_func</code> is of the form,
ssize_t (*gnutls_vec_push_func) (gnutls_transport_ptr_t, const giovec_t * iov, int iovcnt);
</p>
<p><strong>Since:</strong> 2.12.0
</p></dd></dl>
<dl>
<dt><a name="index-gnutls_005ftransport_005fset_005fpull_005ffunction"></a>Function: <em>void</em> <strong>gnutls_transport_set_pull_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_pull_func <var>pull_func</var>)</em></dt>
<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type.
</p>
<p><var>pull_func</var>: a callback function similar to <code>read()</code>
</p>
<p>This is the function where you set a function for gnutls to receive
data. Normally, if you use berkeley style sockets, do not need to
use this function since the default recv(2) will probably be ok.
The callback should return 0 on connection termination, a positive
number indicating the number of bytes received, and -1 on error.
</p>
<p><code>gnutls_pull_func</code> is of the form,
ssize_t (*gnutls_pull_func)(gnutls_transport_ptr_t, void*, size_t);
</p></dd></dl>
<dl>
<dt><a name="index-gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction"></a>Function: <em>void</em> <strong>gnutls_transport_set_pull_timeout_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_pull_timeout_func <var>func</var>)</em></dt>
<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type.
</p>
<p><var>func</var>: a callback function
</p>
<p>This is the function where you set a function for gnutls to know
whether data are ready to be received. It should wait for data a
given time frame in milliseconds. The callback should return 0 on
timeout, a positive number if data can be received, and -1 on error.
You’ll need to override this function if <code>select()</code> is not suitable
for the provided transport calls.
</p>
<p>As with <code>select()</code> , if the timeout value is zero the callback should return
zero if no data are immediately available.
</p>
<p><code>gnutls_pull_timeout_func</code> is of the form,
int (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int ms);
</p>
<p>This callback is necessary when <code>gnutls_handshake_set_timeout()</code> or
<code>gnutls_record_set_timeout()</code> are set. It will not be used when
non-blocking sockets are in use. That is, this function will
not operate when <code>GNUTLS_NONBLOCK</code> is specified in <code>gnutls_init()</code> ,
or a custom pull function is registered without updating the
pull timeout function.
</p>
<p>The helper function <code>gnutls_system_recv_timeout()</code> is provided to
simplify writing callbacks.
</p>
<p><strong>Since:</strong> 3.0
</p></dd></dl>
<p>The functions above accept a callback function which
should return the number of bytes written, or -1 on
error and should set <code>errno</code> appropriately.
In some environments, setting <code>errno</code> is unreliable. For example
Windows have several errno variables in different CRTs, or in other
systems it may be a non thread-local variable. If this is a concern to
you, call <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005ferrno">gnutls_transport_set_errno</a> with the intended errno
value instead of setting <code>errno</code> directly.
</p>
<dl>
<dt><a name="index-gnutls_005ftransport_005fset_005ferrno"></a>Function: <em>void</em> <strong>gnutls_transport_set_errno</strong> <em>(gnutls_session_t <var>session</var>, int <var>err</var>)</em></dt>
<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type.
</p>
<p><var>err</var>: error value to store in session-specific errno variable.
</p>
<p>Store <code>err</code> in the session-specific errno variable. Useful values
for <code>err</code> are EINTR, EAGAIN and EMSGSIZE, other values are treated will be
treated as real errors in the push/pull function.
</p>
<p>This function is useful in replacement push and pull functions set by
<code>gnutls_transport_set_push_function()</code> and
<code>gnutls_transport_set_pull_function()</code> under Windows, where the
replacements may not have access to the same <code>errno</code> variable that is used by GnuTLS (e.g., the application is linked to
msvcr71.dll and gnutls is linked to msvcrt.dll).
</p></dd></dl>
<p><acronym>GnuTLS</acronym> currently only interprets the EINTR, EAGAIN and EMSGSIZE errno
values and returns the corresponding <acronym>GnuTLS</acronym> error codes:
</p><ul>
<li> <code>GNUTLS_E_INTERRUPTED</code>
</li><li> <code>GNUTLS_E_AGAIN</code>
</li><li> <code>GNUTLS_E_LARGE_PACKET</code>
</li></ul>
<p>The EINTR and EAGAIN values are returned by interrupted system calls,
or when non blocking IO is used. All <acronym>GnuTLS</acronym> functions can be
resumed (called again), if any of the above error codes is returned. The
EMSGSIZE value is returned when attempting to send a large datagram.
</p>
<p>In the case of DTLS it is also desirable to override the generic
transport functions with functions that emulate the operation
of <code>recvfrom</code> and <code>sendto</code>. In addition
<acronym>DTLS</acronym> requires timers during the receive of a handshake
message, set using the <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction">gnutls_transport_set_pull_timeout_function</a>
function. To check the retransmission timers the function
<a href="Datagram-TLS-API.html#gnutls_005fdtls_005fget_005ftimeout">gnutls_dtls_get_timeout</a> is provided, which returns the time
remaining until the next retransmission, or better the time until
<a href="Core-TLS-API.html#gnutls_005fhandshake">gnutls_handshake</a> should be called again.
</p>
<dl>
<dt><a name="index-gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction-1"></a>Function: <em>void</em> <strong>gnutls_transport_set_pull_timeout_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_pull_timeout_func <var>func</var>)</em></dt>
<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type.
</p>
<p><var>func</var>: a callback function
</p>
<p>This is the function where you set a function for gnutls to know
whether data are ready to be received. It should wait for data a
given time frame in milliseconds. The callback should return 0 on
timeout, a positive number if data can be received, and -1 on error.
You’ll need to override this function if <code>select()</code> is not suitable
for the provided transport calls.
</p>
<p>As with <code>select()</code> , if the timeout value is zero the callback should return
zero if no data are immediately available.
</p>
<p><code>gnutls_pull_timeout_func</code> is of the form,
int (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int ms);
</p>
<p>This callback is necessary when <code>gnutls_handshake_set_timeout()</code> or
<code>gnutls_record_set_timeout()</code> are set. It will not be used when
non-blocking sockets are in use. That is, this function will
not operate when <code>GNUTLS_NONBLOCK</code> is specified in <code>gnutls_init()</code> ,
or a custom pull function is registered without updating the
pull timeout function.
</p>
<p>The helper function <code>gnutls_system_recv_timeout()</code> is provided to
simplify writing callbacks.
</p>
<p><strong>Since:</strong> 3.0
</p></dd></dl>
<dl>
<dt><a name="index-gnutls_005fdtls_005fget_005ftimeout"></a>Function: <em>unsigned int</em> <strong>gnutls_dtls_get_timeout</strong> <em>(gnutls_session_t <var>session</var>)</em></dt>
<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type.
</p>
<p>This function will return the milliseconds remaining
for a retransmission of the previously sent handshake
message. This function is useful when DTLS is used in
non-blocking mode, to estimate when to call <code>gnutls_handshake()</code>
if no packets have been received.
</p>
<p><strong>Returns:</strong> the remaining time in milliseconds.
</p>
<p><strong>Since:</strong> 3.0
</p></dd></dl>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="Asynchronous-operation.html#Asynchronous-operation" accesskey="1">Asynchronous operation</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="DTLS-sessions.html#DTLS-sessions" accesskey="2">DTLS sessions</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<div class="header">
<p>
Next: <a href="TLS-handshake.html#TLS-handshake" accesskey="n" rel="next">TLS handshake</a>, Previous: <a href="Associating-the-credentials.html#Associating-the-credentials" accesskey="p" rel="prev">Associating the credentials</a>, Up: <a href="How-to-use-GnuTLS-in-applications.html#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Function-and-Data-Index.html#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
