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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual is last updated 10 February 2013 for version
3.2.6 of GnuTLS.
Copyright (C) 2001-2013 Free Software Foundation, Inc.\\
Copyright (C) 2001-2013 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 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GnuTLS 3.2.6: Priority Strings</title>
<meta name="description" content="GnuTLS 3.2.6: Priority Strings">
<meta name="keywords" content="GnuTLS 3.2.6: Priority Strings">
<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="Selecting-cryptographic-key-sizes.html#Selecting-cryptographic-key-sizes" rel="next" title="Selecting cryptographic key sizes">
<link href="Handling-alerts.html#Handling-alerts" rel="prev" title="Handling alerts">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
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;
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" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Priority-Strings"></a>
<div class="header">
<p>
Next: <a href="Selecting-cryptographic-key-sizes.html#Selecting-cryptographic-key-sizes" accesskey="n" rel="next">Selecting cryptographic key sizes</a>, Previous: <a href="Handling-alerts.html#Handling-alerts" accesskey="p" rel="prev">Handling alerts</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="Priority-strings"></a>
<h3 class="section">6.10 Priority strings</h3>
<a name="index-Priority-strings"></a>
<p>In order to specify cipher suite preferences on a TLS session
there are priority functions that accept a string
specifying the enabled for the handshake algorithms.
That string may contain a single initial keyword such as
in <a href="#tab_003aprio_002dkeywords">Table 6.2</a> and may be followed by
additional algorithm or special keywords.
</p>
<dl compact="compact">
<dt><code><var>int</var> <a href="Core-TLS-API.html#gnutls_005fpriority_005fset_005fdirect">gnutls_priority_set_direct</a> (gnutls_session_t <var>session</var>, const char * <var>priorities</var>, const char ** <var>err_pos</var>)</code></dt>
<dt><code><var>int</var> <a href="Core-TLS-API.html#gnutls_005fpriority_005fset">gnutls_priority_set</a> (gnutls_session_t <var>session</var>, gnutls_priority_t <var>priority</var>)</code></dt>
</dl>
<div class="float"><a name="tab_003aprio_002dkeywords"></a>
<table>
<thead><tr><th width="20%">Keyword</th><th width="70%">Description</th></tr></thead>
<tr><td width="20%">PERFORMANCE</td><td width="70%">All the known to be secure ciphersuites are enabled,
limited to 128 bit ciphers and sorted by terms of speed
performance. The message authenticity security level is of 64 bits or more.</td></tr>
<tr><td width="20%">NORMAL</td><td width="70%">Means all the known to be secure ciphersuites. The ciphers are sorted by security
margin, although the 256-bit ciphers are included as a fallback only.
The message authenticity security level is of 64 bits or more.</td></tr>
<tr><td width="20%">PFS</td><td width="70%">Means all the known to be secure ciphersuites that support perfect forward
secrecy. The ciphers are sorted by security
margin, although the 256-bit ciphers are included as a fallback only.
The message authenticity security level is of 64 bits or more. This
option is available since 3.2.4 or later.</td></tr>
<tr><td width="20%">SECURE128</td><td width="70%">Means all known to be secure ciphersuites that offer a
security level 128-bit or more and a message authenticity
security level of 80 bits or more.</td></tr>
<tr><td width="20%">SECURE192</td><td width="70%">Means all the known to be secure ciphersuites that offer a
security level 192-bit or more and a message authenticity
security level of 128 bits or more.</td></tr>
<tr><td width="20%">SECURE256</td><td width="70%">Currently alias for SECURE192.</td></tr>
<tr><td width="20%">SUITEB128</td><td width="70%">Means all the NSA Suite B cryptography (RFC5430) ciphersuites
with an 128 bit security level.</td></tr>
<tr><td width="20%">SUITEB192</td><td width="70%">Means all the NSA Suite B cryptography (RFC5430) ciphersuites
with an 192 bit security level.</td></tr>
<tr><td width="20%">EXPORT</td><td width="70%">Means all ciphersuites are enabled, including the
low-security 40 bit ciphers.</td></tr>
<tr><td width="20%">NONE</td><td width="70%">Means nothing is enabled. This disables even protocols and
compression methods. It should be followed by the
algorithms to be enabled.</td></tr>
</table>
<div class="float-caption"><p><strong>Table 6.2: </strong>Supported initial keywords.</p></div></div>
<p>Unless the initial keyword is "NONE" the defaults (in preference
order) are for TLS protocols TLS 1.2, TLS1.1, TLS1.0, SSL3.0; for
compression NULL; for certificate types X.509.
In key exchange algorithms when in NORMAL or SECURE levels the
perfect forward secrecy algorithms take precedence of the other
protocols. In all cases all the supported key exchange algorithms
are enabled.
</p>
<p>Note that the SECURE levels distinguish between overall security level and
message authenticity security level. That is because the message
authenticity security level requires the adversary to break
the algorithms at real-time during the protocol run, whilst
the overall security level refers to off-line adversaries
(e.g. adversaries breaking the ciphertext years after it was captured).
</p>
<p>The NONE keyword, if used, must followed by keywords specifying
the algorithms and protocols to be enabled. The other initial keywords
do not require, but may be followed by such keywords. All level keywords
can be combined, and for example a level of "SECURE256:+SECURE128" is
allowed.
</p>
<p>The order with which every algorithm or protocol
is specified is significant. Algorithms specified before others
will take precedence. The supported algorithms and protocols
are shown in <a href="#tab_003aprio_002dalgorithms">Table 6.3</a>.
To avoid collisions in order to specify a compression algorithm in
the priority string you have to prefix it with "COMP-", protocol versions
with "VERS-", signature algorithms with "SIGN-" and certificate types with "CTYPE-".
All other algorithms don’t need a prefix. Each specified keyword can
be prefixed with any of the following characters.
</p>
<dl compact="compact">
<dt>’!’ or ’-’</dt>
<dd><p>appended with an algorithm will remove this algorithm.
</p></dd>
<dt>"+"</dt>
<dd><p>appended with an algorithm will add this algorithm.
</p></dd>
</dl>
<div class="float"><a name="tab_003aprio_002dalgorithms"></a>
<table>
<thead><tr><th width="20%">Type</th><th width="70%">Keywords</th></tr></thead>
<tr><td width="20%">Ciphers</td><td width="70%">AES-128-CBC, AES-256-CBC, AES-128-GCM, CAMELLIA-128-CBC,
CAMELLIA-256-CBC, ARCFOUR-128, 3DES-CBC ARCFOUR-40. Catch all
name is CIPHER-ALL which will add all the algorithms from NORMAL
priority.</td></tr>
<tr><td width="20%">Key exchange</td><td width="70%">RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS,
PSK, DHE-PSK, ECDHE-RSA, ANON-ECDH, ANON-DH. The
Catch all name is KX-ALL which will add all the algorithms from NORMAL
priority.</td></tr>
<tr><td width="20%">MAC</td><td width="70%">MD5, SHA1, SHA256, AEAD (used with
GCM ciphers only). All algorithms from NORMAL priority can be accessed with MAC-ALL.</td></tr>
<tr><td width="20%">Compression algorithms</td><td width="70%">COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.</td></tr>
<tr><td width="20%">TLS versions</td><td width="70%">VERS-SSL3.0, VERS-TLS1.0, VERS-TLS1.1,
VERS-TLS1.2, VERS-DTLS1.2, VERS-DTLS1.0.
Catch all is VERS-TLS-ALL and VERS-DTLS-ALL.</td></tr>
<tr><td width="20%">Signature algorithms</td><td width="70%">SIGN-RSA-SHA1, SIGN-RSA-SHA224,
SIGN-RSA-SHA256, SIGN-RSA-SHA384, SIGN-RSA-SHA512, SIGN-DSA-SHA1,
SIGN-DSA-SHA224, SIGN-DSA-SHA256, SIGN-RSA-MD5. Catch all
is SIGN-ALL. This is only valid for TLS 1.2 and later.</td></tr>
<tr><td width="20%">Elliptic curves</td><td width="70%">CURVE-SECP192R1, CURVE-SECP224R1, CURVE-SECP256R1, CURVE-SECP384R1, CURVE-SECP521R1. Catch all is CURVE-ALL.</td></tr>
</table>
<div class="float-caption"><p><strong>Table 6.3: </strong>The supported algorithm keywords in priority strings.</p></div></div>
<p>Note that the DHE key exchange methods are generally
slower<a name="DOCF11" href="#FOOT11"><sup>11</sup></a> than their elliptic curves counterpart
(ECDHE). Moreover the plain Diffie-Hellman key exchange
requires parameters to be generated and associated with a credentials
structure by the server (see <a href="Parameter-generation.html#Parameter-generation">Parameter generation</a>).
</p>
<p>The available special keywords are shown in <a href="#tab_003aprio_002dspecial1">Table 6.4</a>
and <a href="#tab_003aprio_002dspecial2">Table 6.5</a>.
</p>
<div class="float"><a name="tab_003aprio_002dspecial1"></a>
<table>
<thead><tr><th width="45%">Keyword</th><th width="45%">Description</th></tr></thead>
<tr><td width="45%">%COMPAT</td><td width="45%">will enable compatibility mode. It might mean that violations
of the protocols are allowed as long as maximum compatibility with
problematic clients and servers is achieved. More specifically this
string would disable TLS record random padding and tolerate packets
over the maximum allowed TLS record.</td></tr>
<tr><td width="45%">%NO_EXTENSIONS</td><td width="45%">will prevent the sending of any TLS extensions in client side. Note
that TLS 1.2 requires extensions to be used, as well as safe
renegotiation thus this option must be used with care.</td></tr>
<tr><td width="45%">%SERVER_PRECEDENCE</td><td width="45%">The ciphersuite will be selected according to server priorities
and not the client’s.</td></tr>
<tr><td width="45%">%SSL3_RECORD_VERSION</td><td width="45%">will use SSL3.0 record version in client hello.
This is the default.</td></tr>
<tr><td width="45%">%LATEST_RECORD_VERSION</td><td width="45%">will use the latest TLS version record version in client hello.</td></tr>
<tr><td width="45%">%NEW_PADDING</td><td width="45%">will enable the new padding extension negotiation. If the new padding extension
is negotiated, GnuTLS will use a more efficient length-hiding mechanism.
Use <a href="Core-TLS-API.html#gnutls_005frecord_005fcan_005fuse_005flength_005fhiding">gnutls_record_can_use_length_hiding</a> to check whether length-hiding
can be used in the current session. This is a GnuTLS extension to the protocol.</td></tr>
</table>
<div class="float-caption"><p><strong>Table 6.4: </strong>Special priority string keywords.</p></div></div>
<div class="float"><a name="tab_003aprio_002dspecial2"></a>
<table>
<thead><tr><th width="45%">Keyword</th><th width="45%">Description</th></tr></thead>
<tr><td width="45%">%STATELESS_COMPRESSION</td><td width="45%">will disable keeping state across records when compressing. This may
help to mitigate attacks when compression is used but an attacker
is in control of input data. This has to be used only when the
data that are possibly controlled by an attacker are placed in
separate records.</td></tr>
<tr><td width="45%">%DISABLE_SAFE_RENEGOTIATION</td><td width="45%">will completely disable safe renegotiation
completely. Do not use unless you know what you are doing.</td></tr>
<tr><td width="45%">%UNSAFE_RENEGOTIATION</td><td width="45%">will allow handshakes and re-handshakes
without the safe renegotiation extension. Note that for clients
this mode is insecure (you may be under attack), and for servers it
will allow insecure clients to connect (which could be fooled by an
attacker). Do not use unless you know what you are doing and want
maximum compatibility.</td></tr>
<tr><td width="45%">%PARTIAL_RENEGOTIATION</td><td width="45%">will allow initial handshakes to proceed,
but not re-handshakes. This leaves the client vulnerable to attack,
and servers will be compatible with non-upgraded clients for
initial handshakes. This is currently the default for clients and
servers, for compatibility reasons.</td></tr>
<tr><td width="45%">%SAFE_RENEGOTIATION</td><td width="45%">will enforce safe renegotiation. Clients and
servers will refuse to talk to an insecure peer. Currently this
causes interoperability problems, but is required for full protection.</td></tr>
<tr><td width="45%">%VERIFY_ALLOW_SIGN_RSA_MD5</td><td width="45%">will allow RSA-MD5 signatures in certificate chains.</td></tr>
<tr><td width="45%">%VERIFY_DISABLE_CRL_CHECKS</td><td width="45%">will disable CRL or OCSP checks in the verification of the certificate chain.</td></tr>
<tr><td width="45%">%VERIFY_ALLOW_X509_V1_CA_CRT</td><td width="45%">will allow V1 CAs in chains.</td></tr>
</table>
<div class="float-caption"><p><strong>Table 6.5: </strong>More priority string keywords.</p></div></div>
<p>Finally the ciphersuites enabled by any priority string can be
listed using the <code>gnutls-cli</code> application (see <a href="gnutls_002dcli-Invocation.html#gnutls_002dcli-Invocation">gnutls-cli Invocation</a>),
or by using the priority functions as in <a href="Listing-the-ciphersuites-in-a-priority-string.html#Listing-the-ciphersuites-in-a-priority-string">Listing the ciphersuites in a priority string</a>.
</p>
<p>Example priority strings are:
</p><div class="example">
<pre class="example">The default priority without the HMAC-MD5:
"NORMAL:-MD5"
Specifying RSA with AES-128-CBC:
"NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL"
Specifying the defaults except ARCFOUR-128:
"NORMAL:-ARCFOUR-128"
Enabling the 128-bit secure ciphers, while disabling SSL 3.0 and enabling compression:
"SECURE128:-VERS-SSL3.0:+COMP-DEFLATE"
Enabling the 128-bit and 192-bit secure ciphers, while disabling all TLS versions
except TLS 1.2:
"SECURE128:+SECURE192:-VERS-TLS-ALL:+VERS-TLS1.2"
</pre></div>
<div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>
<h3><a name="FOOT11" href="#DOCF11">(11)</a></h3>
<p>It depends on the group used. Primes with
lesser bits are always faster, but also easier to break. See <a href="Selecting-cryptographic-key-sizes.html#Selecting-cryptographic-key-sizes">Selecting cryptographic key sizes</a>
for the acceptable security levels.</p>
</div>
<hr>
<div class="header">
<p>
Next: <a href="Selecting-cryptographic-key-sizes.html#Selecting-cryptographic-key-sizes" accesskey="n" rel="next">Selecting cryptographic key sizes</a>, Previous: <a href="Handling-alerts.html#Handling-alerts" accesskey="p" rel="prev">Handling alerts</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>
|
