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
|
<!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.4 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.4: Asynchronous operation</title>
<meta name="description" content="GnuTLS 3.5.4: Asynchronous operation">
<meta name="keywords" content="GnuTLS 3.5.4: Asynchronous operation">
<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="Setting-up-the-transport-layer.html#Setting-up-the-transport-layer" rel="up" title="Setting up the transport layer">
<link href="Reducing-round_002dtrips.html#Reducing-round_002dtrips" rel="next" title="Reducing round-trips">
<link href="Setting-up-the-transport-layer.html#Setting-up-the-transport-layer" rel="prev" title="Setting up the transport layer">
<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="Asynchronous-operation"></a>
<div class="header">
<p>
Next: <a href="Reducing-round_002dtrips.html#Reducing-round_002dtrips" accesskey="n" rel="next">Reducing round-trips</a>, Up: <a href="Setting-up-the-transport-layer.html#Setting-up-the-transport-layer" accesskey="u" rel="up">Setting up the transport layer</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="Asynchronous-operation-1"></a>
<h4 class="subsection">6.5.1 Asynchronous operation</h4>
<p><acronym>GnuTLS</acronym> can be used with asynchronous socket or event-driven programming.
The approach is similar to using Berkeley sockets under such an environment.
The blocking, due to network interaction, calls such as
<a href="Core-TLS-API.html#gnutls_005fhandshake">gnutls_handshake</a>, <a href="Core-TLS-API.html#gnutls_005frecord_005frecv">gnutls_record_recv</a>,
can be set to non-blocking by setting the underlying sockets to non-blocking.
If other push and pull functions are setup, then they should behave the same
way as <code>recv</code> and <code>send</code> when used in a non-blocking
way, i.e., return -1 and set errno to <code>EAGAIN</code>. Since, during a TLS protocol session
<acronym>GnuTLS</acronym> does not block except for network interaction, the non blocking
<code>EAGAIN</code> errno will be propagated and <acronym>GnuTLS</acronym> functions
will return the <code>GNUTLS_E_AGAIN</code> error code. Such calls can be resumed the
same way as a system call would.
The only exception is <a href="Core-TLS-API.html#gnutls_005frecord_005fsend">gnutls_record_send</a>,
which if interrupted subsequent calls need not to include the data to be
sent (can be called with NULL argument).
</p>
<p>When using the <code>poll</code> or <code>select</code> system calls though, one should remember
that they only apply to the kernel sockets API. To check for any
available buffered data in a <acronym>GnuTLS</acronym> session,
utilize <a href="Core-TLS-API.html#gnutls_005frecord_005fcheck_005fpending">gnutls_record_check_pending</a>,
either before the <code>poll</code> system call, or after a call to
<a href="Core-TLS-API.html#gnutls_005frecord_005frecv">gnutls_record_recv</a>. Data queued by <a href="Core-TLS-API.html#gnutls_005frecord_005fsend">gnutls_record_send</a>
(when interrupted) can be discarded using <a href="Core-TLS-API.html#gnutls_005frecord_005fdiscard_005fqueued">gnutls_record_discard_queued</a>.
</p>
<p>An example of GnuTLS’ usage with asynchronous operation can be found
in <code>doc/examples/tlsproxy</code>.
</p>
<p>The following paragraphs describe the detailed requirements for non-blocking
operation when using the TLS or DTLS protocols.
</p>
<a name="TLS-protocol"></a>
<h4 class="subsubsection">6.5.1.1 TLS protocol</h4>
<p>There are no special requirements for the TLS protocol operation in non-blocking
mode if a non-blocking socket is used.
</p>
<p>It is recommended, however, for future compatibility, when in non-blocking mode, to
call the <a href="Core-TLS-API.html#gnutls_005finit">gnutls_init</a> function with the
<code>GNUTLS_NONBLOCK</code> flag set (see <a href="Session-initialization.html#Session-initialization">Session initialization</a>).
</p>
<a name="Datagram-TLS-protocol"></a>
<h4 class="subsubsection">6.5.1.2 Datagram TLS protocol</h4>
<p>When in non-blocking mode the function, the <a href="Core-TLS-API.html#gnutls_005finit">gnutls_init</a> function
must be called with the <code>GNUTLS_NONBLOCK</code> flag set (see <a href="Session-initialization.html#Session-initialization">Session initialization</a>).
</p>
<p>In contrast with the TLS protocol, the pull timeout function is required,
but will only be called with a timeout of zero. In that case it should indicate
whether there are data to be received or not. When not using the default pull function,
then <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction">gnutls_transport_set_pull_timeout_function</a> should be called.
</p>
<p>Although in the TLS protocol implementation each call to receive or send
function implies to restoring the same function that was interrupted, in
the DTLS protocol this requirement isn’t true.
There are cases where a retransmission is required, which are indicated by
a received message and thus <a href="Core-TLS-API.html#gnutls_005frecord_005fget_005fdirection">gnutls_record_get_direction</a> must be called
to decide which direction to check prior to restoring a function call.
</p>
<dl>
<dt><a name="index-gnutls_005frecord_005fget_005fdirection"></a>Function: <em>int</em> <strong>gnutls_record_get_direction</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 provides information about the internals of the
record protocol and is only useful if a prior gnutls function call,
e.g. <code>gnutls_handshake()</code> , was interrupted for some reason. That
is, if a function returned <code>GNUTLS_E_INTERRUPTED</code> or
<code>GNUTLS_E_AGAIN</code> . In such a case, you might want to call <code>select()</code>
or <code>poll()</code> before restoring the interrupted gnutls function.
</p>
<p>This function’s output is unreliable if you are using the same
<code>session</code> in different threads, for sending and receiving.
</p>
<p><strong>Returns:</strong> 0 if interrupted while trying to read data, or 1 while trying to write data.
</p></dd></dl>
<p>When calling <a href="Core-TLS-API.html#gnutls_005fhandshake">gnutls_handshake</a> through a multi-plexer,
to be able to handle properly the DTLS handshake retransmission timers,
the function <a href="Datagram-TLS-API.html#gnutls_005fdtls_005fget_005ftimeout">gnutls_dtls_get_timeout</a>
should be used to estimate when to call <a href="Core-TLS-API.html#gnutls_005fhandshake">gnutls_handshake</a> if
no data have been received.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Reducing-round_002dtrips.html#Reducing-round_002dtrips" accesskey="n" rel="next">Reducing round-trips</a>, Up: <a href="Setting-up-the-transport-layer.html#Setting-up-the-transport-layer" accesskey="u" rel="up">Setting up the transport layer</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>
|
