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
|
<!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.5.3 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.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GnuTLS 3.5.3: Data transfer and termination</title>
<meta name="description" content="GnuTLS 3.5.3: Data transfer and termination">
<meta name="keywords" content="GnuTLS 3.5.3: Data transfer and termination">
<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="Buffered-data-transfer.html#Buffered-data-transfer" rel="next" title="Buffered data transfer">
<link href="TLS-handshake.html#TLS-handshake" rel="prev" title="TLS handshake">
<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.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; 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="Data-transfer-and-termination"></a>
<div class="header">
<p>
Next: <a href="Buffered-data-transfer.html#Buffered-data-transfer" accesskey="n" rel="next">Buffered data transfer</a>, Previous: <a href="TLS-handshake.html#TLS-handshake" accesskey="p" rel="prev">TLS handshake</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="Data-transfer-and-termination-1"></a>
<h3 class="section">6.7 Data transfer and termination</h3>
<p>Once the handshake is complete and peer’s identity
has been verified data can be exchanged. The available
functions resemble the POSIX <code>recv</code> and <code>send</code>
functions. It is suggested to use <a href="Core-TLS-API.html#gnutls_005ferror_005fis_005ffatal">gnutls_error_is_fatal</a>
to check whether the error codes returned by these functions are
fatal for the protocol or can be ignored.
</p>
<dl>
<dt><a name="index-gnutls_005frecord_005fsend"></a>Function: <em>ssize_t</em> <strong>gnutls_record_send</strong> <em>(gnutls_session_t <var>session</var>, const void * <var>data</var>, size_t <var>data_size</var>)</em></dt>
<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type.
</p>
<p><var>data</var>: contains the data to send
</p>
<p><var>data_size</var>: is the length of the data
</p>
<p>This function has the similar semantics with <code>send()</code> . The only
difference is that it accepts a GnuTLS session, and uses different
error codes.
Note that if the send buffer is full, <code>send()</code> will block this
function. See the <code>send()</code> documentation for more information.
</p>
<p>You can replace the default push function which is <code>send()</code> , by using
<code>gnutls_transport_set_push_function()</code> .
</p>
<p>If the EINTR is returned by the internal push function
then <code>GNUTLS_E_INTERRUPTED</code> will be returned. If
<code>GNUTLS_E_INTERRUPTED</code> or <code>GNUTLS_E_AGAIN</code> is returned, you must
call this function again, with the exact same parameters; alternatively
you could provide a <code>NULL</code> pointer for data, and 0 for
size. cf. <code>gnutls_record_get_direction()</code> .
</p>
<p>Note that in DTLS this function will return the <code>GNUTLS_E_LARGE_PACKET</code>
error code if the send data exceed the data MTU value - as returned
by <code>gnutls_dtls_get_data_mtu()</code> . The errno value EMSGSIZE
also maps to <code>GNUTLS_E_LARGE_PACKET</code> .
Note that since 3.2.13 this function can be called under cork in DTLS
mode, and will refuse to send data over the MTU size by returning
<code>GNUTLS_E_LARGE_PACKET</code> .
</p>
<p><strong>Returns:</strong> The number of bytes sent, or a negative error code. The
number of bytes sent might be less than <code>data_size</code> . The maximum
number of bytes this function can send in a single call depends
on the negotiated maximum record size.
</p></dd></dl>
<dl>
<dt><a name="index-gnutls_005frecord_005frecv"></a>Function: <em>ssize_t</em> <strong>gnutls_record_recv</strong> <em>(gnutls_session_t <var>session</var>, void * <var>data</var>, size_t <var>data_size</var>)</em></dt>
<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type.
</p>
<p><var>data</var>: the buffer that the data will be read into
</p>
<p><var>data_size</var>: the number of requested bytes
</p>
<p>This function has the similar semantics with <code>recv()</code> . The only
difference is that it accepts a GnuTLS session, and uses different
error codes.
In the special case that the peer requests a renegotiation, the
caller will receive an error code of <code>GNUTLS_E_REHANDSHAKE</code> . In case
of a client, this message may be simply ignored, replied with an alert
<code>GNUTLS_A_NO_RENEGOTIATION</code> , or replied with a new handshake,
depending on the client’s will. A server receiving this error code
can only initiate a new handshake or terminate the session.
</p>
<p>If <code>EINTR</code> is returned by the internal push function (the default
is <code>recv()</code> ) then <code>GNUTLS_E_INTERRUPTED</code> will be returned. If
<code>GNUTLS_E_INTERRUPTED</code> or <code>GNUTLS_E_AGAIN</code> is returned, you must
call this function again to get the data. See also
<code>gnutls_record_get_direction()</code> .
</p>
<p><strong>Returns:</strong> The number of bytes received and zero on EOF (for stream
connections). A negative error code is returned in case of an error.
The number of bytes received might be less than the requested <code>data_size</code> .
</p></dd></dl>
<dl>
<dt><a name="index-gnutls_005ferror_005fis_005ffatal"></a>Function: <em>int</em> <strong>gnutls_error_is_fatal</strong> <em>(int <var>error</var>)</em></dt>
<dd><p><var>error</var>: is a GnuTLS error code, a negative error code
</p>
<p>If a GnuTLS function returns a negative error code you may feed that
value to this function to see if the error condition is fatal to
a TLS session (i.e., must be terminated).
</p>
<p>Note that you may also want to check the error code manually, since some
non-fatal errors to the protocol (such as a warning alert or
a rehandshake request) may be fatal for your program.
</p>
<p>This function is only useful if you are dealing with errors from
functions that relate to a TLS session (e.g., record layer or handshake
layer handling functions).
</p>
<p><strong>Returns:</strong> Non-zero value on fatal errors or zero on non-fatal.
</p></dd></dl>
<p>Although, in the TLS protocol the receive function can be called
at any time, when DTLS is used the GnuTLS receive functions must be
called once a message is available for reading, even if no data are
expected. This is because in DTLS various (internal) actions
may be required due to retransmission timers. Moreover,
an extended receive function is shown below, which allows the extraction
of the message’s sequence number. Due to the unreliable nature of the
protocol, this field allows distinguishing out-of-order messages.
</p>
<dl>
<dt><a name="index-gnutls_005frecord_005frecv_005fseq"></a>Function: <em>ssize_t</em> <strong>gnutls_record_recv_seq</strong> <em>(gnutls_session_t <var>session</var>, void * <var>data</var>, size_t <var>data_size</var>, unsigned char * <var>seq</var>)</em></dt>
<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type.
</p>
<p><var>data</var>: the buffer that the data will be read into
</p>
<p><var>data_size</var>: the number of requested bytes
</p>
<p><var>seq</var>: is the packet’s 64-bit sequence number. Should have space for 8 bytes.
</p>
<p>This function is the same as <code>gnutls_record_recv()</code> , except that
it returns in addition to data, the sequence number of the data.
This is useful in DTLS where record packets might be received
out-of-order. The returned 8-byte sequence number is an
integer in big-endian format and should be
treated as a unique message identification.
</p>
<p><strong>Returns:</strong> The number of bytes received and zero on EOF. A negative
error code is returned in case of an error. The number of bytes
received might be less than <code>data_size</code> .
</p>
<p><strong>Since:</strong> 3.0
</p></dd></dl>
<p>The <a href="Core-TLS-API.html#gnutls_005frecord_005fcheck_005fpending">gnutls_record_check_pending</a> helper function is available to
allow checking whether data are available to be read in a <acronym>GnuTLS</acronym> session
buffers. Note that this function complements but does not replace <code>poll</code>,
i.e., <a href="Core-TLS-API.html#gnutls_005frecord_005fcheck_005fpending">gnutls_record_check_pending</a> reports no data to be read, <code>poll</code>
should be called to check for data in the network buffers.
</p>
<dl>
<dt><a name="index-gnutls_005frecord_005fcheck_005fpending"></a>Function: <em>size_t</em> <strong>gnutls_record_check_pending</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 checks if there are unread data
in the gnutls buffers. If the return value is
non-zero the next call to <code>gnutls_record_recv()</code>
is guaranteed not to block.
</p>
<p><strong>Returns:</strong> Returns the size of the data or zero.
</p></dd></dl>
<dl compact="compact">
<dt><code><var>int</var> <a href="Core-TLS-API.html#gnutls_005frecord_005fget_005fdirection">gnutls_record_get_direction</a> (gnutls_session_t <var>session</var>)</code></dt>
</dl>
<p>Once a TLS or DTLS session is no longer needed, it is
recommended to use <a href="Core-TLS-API.html#gnutls_005fbye">gnutls_bye</a> to terminate the
session. That way the peer is notified securely about the
intention of termination, which allows distinguishing it
from a malicious connection termination.
A session can be deinitialized with the <a href="Core-TLS-API.html#gnutls_005fdeinit">gnutls_deinit</a> function.
</p>
<dl>
<dt><a name="index-gnutls_005fbye"></a>Function: <em>int</em> <strong>gnutls_bye</strong> <em>(gnutls_session_t <var>session</var>, gnutls_close_request_t <var>how</var>)</em></dt>
<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type.
</p>
<p><var>how</var>: is an integer
</p>
<p>Terminates the current TLS/SSL connection. The connection should
have been initiated using <code>gnutls_handshake()</code> . <code>how</code> should be one
of <code>GNUTLS_SHUT_RDWR</code> , <code>GNUTLS_SHUT_WR</code> .
</p>
<p>In case of <code>GNUTLS_SHUT_RDWR</code> the TLS session gets
terminated and further receives and sends will be disallowed. If
the return value is zero you may continue using the underlying
transport layer. <code>GNUTLS_SHUT_RDWR</code> sends an alert containing a close
request and waits for the peer to reply with the same message.
</p>
<p>In case of <code>GNUTLS_SHUT_WR</code> the TLS session gets terminated
and further sends will be disallowed. In order to reuse the
connection you should wait for an EOF from the peer.
<code>GNUTLS_SHUT_WR</code> sends an alert containing a close request.
</p>
<p>Note that not all implementations will properly terminate a TLS
connection. Some of them, usually for performance reasons, will
terminate only the underlying transport layer, and thus not
distinguishing between a malicious party prematurely terminating
the connection and normal termination.
</p>
<p>This function may also return <code>GNUTLS_E_AGAIN</code> or
<code>GNUTLS_E_INTERRUPTED</code> ; cf. <code>gnutls_record_get_direction()</code> .
</p>
<p><strong>Returns:</strong> <code>GNUTLS_E_SUCCESS</code> on success, or an error code, see
function documentation for entire semantics.
</p></dd></dl>
<dl>
<dt><a name="index-gnutls_005fdeinit"></a>Function: <em>void</em> <strong>gnutls_deinit</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 clears all buffers associated with the <code>session</code> .
This function will also remove session data from the session
database if the session was terminated abnormally.
</p></dd></dl>
<hr>
<div class="header">
<p>
Next: <a href="Buffered-data-transfer.html#Buffered-data-transfer" accesskey="n" rel="next">Buffered data transfer</a>, Previous: <a href="TLS-handshake.html#TLS-handshake" accesskey="p" rel="prev">TLS handshake</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>
|
