aboutsummaryrefslogtreecommitdiffstats
path: root/doc/IAX2-security.txt
blob: 536320d6a6c2cfe58d83b3ff012c145cbd364456 (plain)
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
                                 IAX2 Security

                       Copyright (c) 2009 - Digium, Inc.

                              All Rights Reserved.

                              Document Version 1.0

                                    09/03/09

              Asterisk Development Team <asteriskteam@digium.com>

   Table of Contents

   1. Introduction 3

   1.1. Overview 3

   2. User Guide 3

   2.1. Configuration 3

   2.1.1. Quick Start 3

   2.1.2. Controlled Networks 4

   2.1.2.1. Full Upgrade 4

   2.1.2.2. Partial Upgrade 4

   2.1.3. Public Networks 4

   2.1.3.1. Full Upgrade 4

   2.1.3.2. Partial Upgrade 5

   2.1.3.3. Guest Access 5

   2.2. CLI Commands 6

   2.2.1. iax2 show callnumber usage 6

   2.2.2. iax2 show peer 6

   3. Protocol Modification 6

   3.1. Overview 6

   3.2. Call Token Validation 7

   3.3. Example Message Exchanges 8

   3.3.1. Call Setup 8

   3.3.2. Call Setup, client does not support CALLTOKEN 8

   3.3.3. Call Setup, client supports CALLTOKEN, server does not 9

   3.3.4. Call Setup from client that sends invalid token 9

   4. Asterisk Implementation 9

   4.1. CALLTOKEN IE Payload 9

                                1. Introduction

1.1. Overview

   A change has been made to the IAX2 protocol to help mitigate denial of
   service attacks. This change is referred to as call token validation. This
   change affects how messages are exchanged and is not backwards compatible
   for an older client connecting to an updated server, so a number of
   options have been provided to disable call token validation as needed for
   compatibility purposes.

   In addition to call token validation, Asterisk can now also limit the
   number of connections allowed per IP address to disallow one host from
   preventing other hosts from making successful connections. These options
   are referred to as call number limits.

   For additional details about the configuration options referenced in this
   document, see the sample configuration file, iax.conf.sample. For
   information regarding the details of the call token validation protocol
   modification, see section 3 (Protocol Modification) of this document.

                                 2. User Guide

2.1. Configuration

  2.1.1. Quick Start

   We strongly recommend that administrators leave the IAX2 security
   enhancements in place where possible. However, to bypass the security
   enhancements completely and have Asterisk work exactly as it did before,
   the following options can be specified in the [general] section of
   iax.conf:

   [general]

   ...

   calltokenoptional = 0.0.0.0/0.0.0.0

   maxcallnumbers = 16382

   ...

  2.1.2. Controlled Networks

   This section discusses what needs to be done for an Asterisk server on a
   network where no unsolicited traffic will reach the IAX2 service.

    2.1.2.1. Full Upgrade

   If all IAX2 endpoints have been upgraded, then no changes to configuration
   need to be made.

    2.1.2.2. Partial Upgrade

   If only some of the IAX2 endpoints have been upgraded, then some
   configuration changes will need to be made for interoperability. Since
   this is for a controlled network, the easiest thing to do is to disable
   call token validation completely, as described in section 2.1.1.

  2.1.3. Public Networks

   This section discusses the use of the IAX2 security functionality on
   public networks where it is possible to receive unsolicited IAX2 traffic.

    2.1.3.1. Full Upgrade

   If all IAX2 endpoints have been upgraded to support call token validation,
   then no changes need to be made. However, for enhanced security, the
   administrator may adjust call number limits to further reduce the
   potential impact of malicious call number consumption. The following
   configuration will allow known peers to consume more call numbers than
   unknown source IP addresses:

   [general]

   ; By default, restrict call number usage to a low number.

   maxcallnumbers = 16

   ...

   [callnumberlimits]

   ; For peers with known IP addresses, call number limits can

   ; be set in this section. This limit is per IP address for

   ; addresses that fall in the specified range.

   ; <IP>/<mask> = <limit>

   192.168.1.0/255.255.255.0 = 1024

   ...

   [peerA]

   ; Since we won't know the IP address of a dynamic peer until

   ; they register, a max call number limit can be set in a

   ; dynamic peer configuration section.

   Type = peer

   host = dynamic

   maxcallnumbers = 1024

   ...

    2.1.3.2. Partial Upgrade

   If only some IAX2 endpoints have been upgraded, or the status of an IAX2
   endpoint is unknown, then call token validation must be disabled to ensure
   interoperability. To reduce the potential impact of disabling call token
   validation, it should only be disabled for a specific peer or user as
   needed. By using the auto option, call token validation will be changed to
   required as soon as we determine that the peer supports it.

   [friendA]

   requirecalltoken = auto

   ...

   Note that there are some cases where auto should not be used. For example,
   if multiple peers use the same authentication details, and they have not
   all upgraded to support call token validation, then the ones that do not
   support it will get locked out. Once an upgraded client successfully
   completes an authenticated call setup using call token validation,
   Asterisk will require it from then on. In that case, it would be better to
   set the requirecalltoken option to no.

    2.1.3.3. Guest Access

   Guest access via IAX2 requires special attention. Given the number of
   existing IAX2 endpoints that do not support call token validation, most
   systems that allow guest access should do so without requiring call token
   validation.

   [guest]

   ; Note that the name "guest" is special here. When the code

   ; tries to determine if call token validation is required, it

   ; will look for a user by the username specified in the

   ; request. Guest calls can be sent without a username. In

   ; that case, we will look for a defined user called "guest" to

   ; determine if call token validation is required or not.

   type = user

   requirecalltoken = no

   ...

   Since disabling call token validation for the guest account allows a huge
   hole for malicious call number consumption, an option has been provided to
   segregate the call numbers consumed by connections not using call token
   validation from those that do. That way, there are resources dedicated to
   the more secure connections to ensure that service is not interrupted for
   them.

   [general]

   maxcallnumbers_nonvalidated = 2048

2.2. CLI Commands

  2.2.1. iax2 show callnumber usage

   Usage: iax2 show callnumber usage [IP address]

   Show current IP addresses which are consuming IAX2 call numbers.

  2.2.2. iax2 show peer

   This command will now also show the configured call number limit and
   whether or not call token validation is required for this peer.

                            3. Protocol Modification

   This section discusses the modification that has been made to the IAX2
   protocol. This information would be most useful to implementors of IAX2.

3.1. Overview

   The IAX2 protocol uses a call number to associate messages with which call
   they belong to. The available amount of call numbers is finite as defined
   by the protocol. Because of this, it is important to prevent attackers
   from maliciously consuming call numbers. To achieve this, an enhancement
   to the IAX2 protocol has been made which is referred to as call token
   validation.

   Call token validation ensures that an IAX2 connection is not coming from a
   spoofed IP address. In addition to using call token validation, Asterisk
   will also limit how many call numbers may be consumed by a given remote IP
   address. These limits have defaults that will usually not need to be
   changed, but can be modified for a specific need.

   The combination of call token validation and call number limits is used to
   mitigate a denial of service attack to consume all available IAX2 call
   numbers. An alternative approach to securing IAX2 would be to use a
   security layer on top of IAX2, such as DTLS [RFC4347] or IPsec [RFC4301].

3.2. Call Token Validation

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119.

   For this section, when the word "request" is used, it is referring to the
   command that starts an IAX2 dialog.

   This modification adds a new IAX2 frame type, and a new information
   element be defined.

   Frame Type: CALLTOKEN --- 0x28 (40)

   IE: CALLTOKEN --- 0x36 (54)

   When a request is initially sent, it SHOULD include the CALLTOKEN IE with
   a zero-length payload to indicate that this client supports the CALLTOKEN
   exchange. When a server receives this request, it MUST respond with the
   IAX2 message CALLTOKEN. The CALLTOKEN message MUST be sent with a source
   call number of 0, as a call number will not yet be allocated for this
   call.

   For the sake of backwards compatibility with clients that do not support
   token validation, server implementations MAY process requests that do not
   indicate CALLTOKEN support in their initial request. However, this SHOULD
   NOT be the default behavior, as it gives up the security benefits gained
   by CALLTOKEN validation.

   After a client sends a request with an empty CALLTOKEN IE, it MUST be
   prepared to receive a CALLTOKEN response, or to receive a response that
   would be given in the case of a valid CALLTOKEN. This is how a client must
   behave to inter operate with IAX2 server implementations that do not yet
   support CALLTOKEN validation.

   When an IAX2 client receives a CALLTOKEN response, it MUST send its
   initial request again. This request MUST include the CALLTOKEN IE with a
   copy of the value of the CALLTOKEN IE received in the CALLTOKEN response.
   The IE value is an opaque value. Clients MUST be able to accept a
   CALLTOKEN payload of any length, up to the maximum length allowed in an
   IAX2 IE.

   The value of the payload in the CALLTOKEN IE is an implementation detail.
   It is left to the implementor to decide how sophisticated it should be.
   However, it MUST be enough such that when the CALLTOKEN IE is sent back,
   it can be used to verify that the source IP address and port number has
   not been spoofed.

   If a server receives a request with an invalid CALLTOKEN IE value, then it
   MUST drop it and not respond.

3.3. Example Message Exchanges

  3.3.1. Call Setup

   Client Server

   -------- --------

   ------------- NEW ----------->

   (with empty CALLTOKEN IE)

   <---------- CALLTOKEN ------------

   (client must ignore

   source call number

   from this message)

   ------------- NEW ----------->

   (with received token)

   <---------- AUTHREQ ----------

   ... continue as normal ...

  3.3.2. Call Setup, client does not support CALLTOKEN

   Client Server

   -------- --------

   ------------- NEW ----------->

   (with no CALLTOKEN IE)

   <----------- REJECT ----------

   (sent without allocating

   a call number)

   ------------- ACK ----------->

  3.3.3. Call Setup, client supports CALLTOKEN, server does not

   Client Server

   -------- --------

   ------------- NEW ----------->

   (with empty CALLTOKEN IE)

   <----------- AUTHREQ ---------

   (sent without allocating

   a call number)

   ... continue as normal ...

  3.3.4. Call Setup from client that sends invalid token

   Client Server

   -------- --------

   ------------- NEW ----------->

   (with invalid CALLTOKEN IE)

   ... dropped ...

                           4. Asterisk Implementation

   This section includes some additional details on the implementation of
   these changes in Asterisk.

4.1. CALLTOKEN IE Payload

   For Asterisk, we will encode the payload of the CALLTOKEN IE such that the
   server is able to validate a received token without having to store any
   information after transmitting the CALLTOKEN response. The CALLTOKEN IE
   payload will contain:

     * A timestamp (epoch based)

     * SHA1 hash of the remote IP address and port, the timestamp, as well
       some random data generated when Asterisk starts.

   When a CALLTOKEN IE is received, its validity will be determined by
   recalculating the SHA1 hash. If it is a valid token, the timestamp is
   checked to determine if the token is expired. The token timeout will be
   hard coded at 10 seconds for now. However, it may be made configurable at
   some point if it seems to be a useful addition. If the server determines
   that a received token is expired, it will treat it as an invalid token and
   not respond to the request.

   By using this method, we require no additional memory to be allocated for
   a dialog, other than what is on the stack for processing the initial
   request, until token validation is complete.

   However, one thing to note with this CALLTOKEN IE encoding is that a token
   would be considered valid by Asterisk every time a client sent it until we
   considered it an expired token. However, with use of the "maxcallnumbers"
   option, this is not actually a problem. It just means that an attacker
   could hit their call number limit a bit quicker since they would only have
   to acquire a single token per timeout period, instead of a token per
   request.

                                    10 of 10