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
|
<!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.8 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.8: TLS Extension Handling</title>
<meta name="description" content="GnuTLS 3.4.8: TLS Extension Handling">
<meta name="keywords" content="GnuTLS 3.4.8: TLS Extension Handling">
<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="Internal-architecture-of-GnuTLS.html#Internal-architecture-of-GnuTLS" rel="up" title="Internal architecture of GnuTLS">
<link href="Cryptographic-Backend.html#Cryptographic-Backend" rel="next" title="Cryptographic Backend">
<link href="TLS-Authentication-Methods.html#TLS-Authentication-Methods" rel="prev" title="TLS Authentication Methods">
<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="TLS-Extension-Handling"></a>
<div class="header">
<p>
Next: <a href="Cryptographic-Backend.html#Cryptographic-Backend" accesskey="n" rel="next">Cryptographic Backend</a>, Previous: <a href="TLS-Authentication-Methods.html#TLS-Authentication-Methods" accesskey="p" rel="prev">TLS Authentication Methods</a>, Up: <a href="Internal-architecture-of-GnuTLS.html#Internal-architecture-of-GnuTLS" accesskey="u" rel="up">Internal architecture of GnuTLS</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="TLS-Extension-Handling-1"></a>
<h3 class="section">10.4 TLS Extension Handling</h3>
<p>As with authentication methods, the TLS extensions handlers can be
implemented using the interface shown below.
</p>
<pre class="verbatim">typedef int (*gnutls_ext_recv_func) (gnutls_session_t session,
const unsigned char *data, size_t len);
typedef int (*gnutls_ext_send_func) (gnutls_session_t session,
gnutls_buffer_st *extdata);
</pre>
<p>Here there are two functions, one for receiving the extension data
and one for sending. These functions have to check internally whether
they operate in client or server side.
</p>
<p>A simple example of an extension handler can be seen in
<code>ext/srp.c</code> in GnuTLS’ source code. After implementing these functions,
together with the extension number they handle, they have to be registered
using <code>_gnutls_ext_register</code> in
<code>gnutls_extensions.c</code> typically within <code>_gnutls_ext_init</code>.
</p>
<a name="Adding-a-new-TLS-extension"></a>
<h4 class="subheading">Adding a new TLS extension</h4>
<p>Adding support for a new TLS extension is done from time to time, and
the process to do so is not difficult. Here are the steps you need to
follow if you wish to do this yourself. For sake of discussion, let’s
consider adding support for the hypothetical TLS extension
<code>foobar</code>. The following section is about adding an extension to GnuTLS,
for custom application extensions you should check the exported function
<a href="Core-TLS-API.html#gnutls_005fext_005fregister">gnutls_ext_register</a>.
</p>
<a name="Add-configure-option-like-_002d_002denable_002dfoobar-or-_002d_002ddisable_002dfoobar_002e"></a>
<h4 class="subsubheading">Add <code>configure</code> option like <code>--enable-foobar</code> or <code>--disable-foobar</code>.</h4>
<p>This step is useful when the extension code is large and it might be desirable
to disable the extension under some circumstances. Otherwise it can be safely
skipped.
</p>
<p>Whether to chose enable or disable depends on whether you intend to make the extension be
enabled by default. Look at existing checks (i.e., SRP, authz) for
how to model the code. For example:
</p>
<div class="example">
<pre class="example">AC_MSG_CHECKING([whether to disable foobar support])
AC_ARG_ENABLE(foobar,
AS_HELP_STRING([--disable-foobar],
[disable foobar support]),
ac_enable_foobar=no)
if test x$ac_enable_foobar != xno; then
AC_MSG_RESULT(no)
AC_DEFINE(ENABLE_FOOBAR, 1, [enable foobar])
else
ac_full=0
AC_MSG_RESULT(yes)
fi
AM_CONDITIONAL(ENABLE_FOOBAR, test "$ac_enable_foobar" != "no")
</pre></div>
<p>These lines should go in <code>m4/hooks.m4</code>.
</p>
<a name="Add-IANA-extension-value-to-extensions_005ft-in-gnutls_005fint_002eh_002e"></a>
<h4 class="subsubheading">Add IANA extension value to <code>extensions_t</code> in <code>gnutls_int.h</code>.</h4>
<p>A good name for the value would be GNUTLS_EXTENSION_FOOBAR. Check
with <a href="http://www.iana.org/assignments/tls-extensiontype-values">http://www.iana.org/assignments/tls-extensiontype-values</a>
for allocated values. For experiments, you could pick a number but
remember that some consider it a bad idea to deploy such modified
version since it will lead to interoperability problems in the future
when the IANA allocates that number to someone else, or when the
foobar protocol is allocated another number.
</p>
<a name="Add-an-entry-to-_005fgnutls_005fextensions-in-gnutls_005fextensions_002ec_002e"></a>
<h4 class="subsubheading">Add an entry to <code>_gnutls_extensions</code> in <code>gnutls_extensions.c</code>.</h4>
<p>A typical entry would be:
</p>
<div class="example">
<pre class="example"> int ret;
#if ENABLE_FOOBAR
ret = _gnutls_ext_register (&foobar_ext);
if (ret != GNUTLS_E_SUCCESS)
return ret;
#endif
</pre></div>
<p>Most likely you’ll need to add an <code>#include "ext/foobar.h"</code>, that
will contain something like
like:
</p><div class="example">
<pre class="example"> extension_entry_st foobar_ext = {
.name = "FOOBAR",
.type = GNUTLS_EXTENSION_FOOBAR,
.parse_type = GNUTLS_EXT_TLS,
.recv_func = _foobar_recv_params,
.send_func = _foobar_send_params,
.pack_func = _foobar_pack,
.unpack_func = _foobar_unpack,
.deinit_func = NULL
}
</pre></div>
<p>The GNUTLS_EXTENSION_FOOBAR is the integer value you added to
<code>gnutls_int.h</code> earlier. In this structure you specify the
functions to read the extension from the hello message, the function
to send the reply to, and two more functions to pack and unpack from
stored session data (e.g. when resumming a session). The <code>deinit</code> function
will be called to deinitialize the extension’s private parameters, if any.
</p>
<p>Note that the conditional <code>ENABLE_FOOBAR</code> definition should only be
used if step 1 with the <code>configure</code> options has taken place.
</p>
<a name="Add-new-files-that-implement-the-extension_002e"></a>
<h4 class="subsubheading">Add new files that implement the extension.</h4>
<p>The functions you are responsible to add are those mentioned in the
previous step. They should be added in a file such as <code>ext/foobar.c</code>
and headers should be placed in <code>ext/foobar.h</code>.
As a starter, you could add this:
</p>
<div class="example">
<pre class="example">int
_foobar_recv_params (gnutls_session_t session, const opaque * data,
size_t data_size)
{
return 0;
}
int
_foobar_send_params (gnutls_session_t session, gnutls_buffer_st* data)
{
return 0;
}
int
_foobar_pack (extension_priv_data_t epriv, gnutls_buffer_st * ps)
{
/* Append the extension's internal state to buffer */
return 0;
}
int
_foobar_unpack (gnutls_buffer_st * ps, extension_priv_data_t * epriv)
{
/* Read the internal state from buffer */
return 0;
}
</pre></div>
<p>The <code>_foobar_recv_params</code> function is responsible for
parsing incoming extension data (both in the client and server).
</p>
<p>The <code>_foobar_send_params</code> function is responsible for
sending extension data (both in the client and server).
</p>
<p>If you receive length fields that don’t match, return
<code>GNUTLS_E_UNEXPECTED_PACKET_LENGTH</code>. If you receive invalid
data, return <code>GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER</code>. You can use
other error codes from the list in <a href="Error-codes.html#Error-codes">Error codes</a>. Return 0 on success.
</p>
<p>An extension typically stores private information in the <code>session</code>
data for later usage. That can be done using the functions
<code>_gnutls_ext_set_session_data</code> and
<code>_gnutls_ext_get_session_data</code>. You can check simple examples
at <code>ext/max_record.c</code> and <code>ext/server_name.c</code> extensions.
That private information can be saved and restored across session
resumption if the following functions are set:
</p>
<p>The <code>_foobar_pack</code> function is responsible for packing
internal extension data to save them in the session resumption storage.
</p>
<p>The <code>_foobar_unpack</code> function is responsible for
restoring session data from the session resumption storage.
</p>
<p>Recall that both the client and server, send and receive
parameters, and your code most likely will need to do different things
depending on which mode it is in. It may be useful to make this
distinction explicit in the code. Thus, for example, a better
template than above would be:
</p>
<div class="example">
<pre class="example">int
_gnutls_foobar_recv_params (gnutls_session_t session,
const opaque * data,
size_t data_size)
{
if (session->security_parameters.entity == GNUTLS_CLIENT)
return foobar_recv_client (session, data, data_size);
else
return foobar_recv_server (session, data, data_size);
}
int
_gnutls_foobar_send_params (gnutls_session_t session,
gnutls_buffer_st * data)
{
if (session->security_parameters.entity == GNUTLS_CLIENT)
return foobar_send_client (session, data);
else
return foobar_send_server (session, data);
}
</pre></div>
<p>The functions used would be declared as <code>static</code> functions, of
the appropriate prototype, in the same file.
When adding the files, you’ll need to add them to <code>ext/Makefile.am</code>
as well, for example:
</p>
<div class="example">
<pre class="example">if ENABLE_FOOBAR
libgnutls_ext_la_SOURCES += ext/foobar.c ext/foobar.h
endif
</pre></div>
<a name="Add-API-functions-to-enable_002fdisable-the-extension_002e"></a>
<h4 class="subsubheading">Add API functions to enable/disable the extension.</h4>
<p>It might be desirable to allow users of the extension to
request use of the extension, or set extension specific data.
This can be implemented by adding extension specific function calls
that can be added to <code>includes/gnutls/gnutls.h</code>,
as long as the LGPLv2.1+ applies.
The implementation of the function should lie in the <code>ext/foobar.c</code> file.
</p>
<p>To make the API available in the shared library you need to add the
symbol in <code>lib/libgnutls.map</code>, so that the symbol
is exported properly.
</p>
<p>When writing GTK-DOC style documentation for your new APIs, don’t
forget to add <code>Since:</code> tags to indicate the GnuTLS version the
API was introduced in.
</p>
<a name="Heartbeat-extension_002e"></a>
<h4 class="subsubheading">Heartbeat extension.</h4>
<p>One such extension is HeartBeat protocol (RFC6520:
<a href="https://tools.ietf.org/html/rfc6520">https://tools.ietf.org/html/rfc6520</a>) implementation. To enable
it use option –heartbeat with example client and server supplied with
gnutls:
</p>
<div class="example">
<pre class="example">./doc/credentials/gnutls-http-serv --priority "NORMAL:-CIPHER-ALL:+NULL" -d 100 \
--heartbeat --echo
./src/gnutls-cli --priority "NORMAL:-CIPHER-ALL:+NULL" -d 100 localhost -p 5556 \
--insecure --heartbeat
</pre></div>
<p>After that pasting
</p><div class="example">
<pre class="example">**HEARTBEAT**
</pre></div>
<p>command into gnutls-cli will trigger corresponding command on the server and it will send HeartBeat Request with random length to client.
</p>
<p>Another way is to run capabilities check with:
</p>
<div class="example">
<pre class="example">./doc/credentials/gnutls-http-serv -d 100 --heartbeat
./src/gnutls-cli-debug localhost -p 5556
</pre></div>
<a name="Adding-a-new-Supplemental-Data-Handshake-Message"></a>
<h4 class="subheading">Adding a new Supplemental Data Handshake Message</h4>
<p>TLS handshake extensions allow to send so called supplemental data
handshake messages [<em>RFC4680</em>]. This short section explains how to
implement a supplemental data handshake message for a given TLS extension.
</p>
<p>First of all, modify your extension <code>foobar</code> in the way, to instruct
the handshake process to send and receive supplemental data, as shown below.
</p>
<div class="example">
<pre class="example">int
_gnutls_foobar_recv_params (gnutls_session_t session, const opaque * data,
size_t _data_size)
{
...
gnutls_supplemental_recv(session, 1);
...
}
int
_gnutls_foobar_send_params (gnutls_session_t session, gnutls_buffer_st *extdata)
{
...
gnutls_supplemental_send(session, 1);
...
}
</pre></div>
<p>Furthermore you’ll need two new functions <code>_foobar_supp_recv_params</code>
and <code>_foobar_supp_send_params</code>, which must conform to the following
prototypes.
</p>
<div class="example">
<pre class="example">typedef int (*gnutls_supp_recv_func)(gnutls_session_t session,
const unsigned char *data,
size_t data_size);
typedef int (*gnutls_supp_send_func)(gnutls_session_t session,
gnutls_buffer_t buf);
</pre></div>
<p>The following example code shows how to send a
“Hello World” string in the supplemental data handshake message.
</p>
<div class="example">
<pre class="example">int
_foobar_supp_recv_params(gnutls_session_t session, const opaque *data, size_t _data_size)
{
uint8_t len = _data_size;
unsigned char *msg;
msg = gnutls_malloc(len);
if (msg == NULL) return GNUTLS_E_MEMORY_ERROR;
memcpy(msg, data, len);
msg[len]='\0';
/* do something with msg */
gnutls_free(msg);
return len;
}
int
_foobar_supp_send_params(gnutls_session_t session, gnutls_buffer_t buf)
{
unsigned char *msg = "hello world";
int len = strlen(msg);
if (gnutls_buffer_append_data(buf, msg, len) < 0)
abort();
return len;
}
</pre></div>
<p>Afterwards, register the new supplemental data using <a href="Core-TLS-API.html#gnutls_005fsupplemental_005fregister">gnutls_supplemental_register</a>,
at some point in your program.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Cryptographic-Backend.html#Cryptographic-Backend" accesskey="n" rel="next">Cryptographic Backend</a>, Previous: <a href="TLS-Authentication-Methods.html#TLS-Authentication-Methods" accesskey="p" rel="prev">TLS Authentication Methods</a>, Up: <a href="Internal-architecture-of-GnuTLS.html#Internal-architecture-of-GnuTLS" accesskey="u" rel="up">Internal architecture of GnuTLS</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>
|
