Merged revisions 243258 via svnmerge from
[asterisk/asterisk.git] / doc / IAX2-security.txt
1                                  IAX2 Security
2
3                        Copyright (c) 2009 - Digium, Inc.
4
5                               All Rights Reserved.
6
7                               Document Version 1.0
8
9                                     09/03/09
10
11               Asterisk Development Team <asteriskteam@digium.com>
12
13    Table of Contents
14
15    1. Introduction 3
16
17    1.1. Overview 3
18
19    2. User Guide 3
20
21    2.1. Configuration 3
22
23    2.1.1. Quick Start 3
24
25    2.1.2. Controlled Networks 4
26
27    2.1.2.1. Full Upgrade 4
28
29    2.1.2.2. Partial Upgrade 4
30
31    2.1.3. Public Networks 4
32
33    2.1.3.1. Full Upgrade 4
34
35    2.1.3.2. Partial Upgrade 5
36
37    2.1.3.3. Guest Access 5
38
39    2.2. CLI Commands 6
40
41    2.2.1. iax2 show callnumber usage 6
42
43    2.2.2. iax2 show peer 6
44
45    3. Protocol Modification 6
46
47    3.1. Overview 6
48
49    3.2. Call Token Validation 7
50
51    3.3. Example Message Exchanges 8
52
53    3.3.1. Call Setup 8
54
55    3.3.2. Call Setup, client does not support CALLTOKEN 8
56
57    3.3.3. Call Setup, client supports CALLTOKEN, server does not 9
58
59    3.3.4. Call Setup from client that sends invalid token 9
60
61    4. Asterisk Implementation 9
62
63    4.1. CALLTOKEN IE Payload 9
64
65                                 1. Introduction
66
67 1.1. Overview
68
69    A change has been made to the IAX2 protocol to help mitigate denial of
70    service attacks. This change is referred to as call token validation. This
71    change affects how messages are exchanged and is not backwards compatible
72    for an older client connecting to an updated server, so a number of
73    options have been provided to disable call token validation as needed for
74    compatibility purposes.
75
76    In addition to call token validation, Asterisk can now also limit the
77    number of connections allowed per IP address to disallow one host from
78    preventing other hosts from making successful connections. These options
79    are referred to as call number limits.
80
81    For additional details about the configuration options referenced in this
82    document, see the sample configuration file, iax.conf.sample. For
83    information regarding the details of the call token validation protocol
84    modification, see section 3 (Protocol Modification) of this document.
85
86                                  2. User Guide
87
88 2.1. Configuration
89
90   2.1.1. Quick Start
91
92    We strongly recommend that administrators leave the IAX2 security
93    enhancements in place where possible. However, to bypass the security
94    enhancements completely and have Asterisk work exactly as it did before,
95    the following options can be specified in the [general] section of
96    iax.conf:
97
98    [general]
99
100    ...
101
102    calltokenoptional = 0.0.0.0/0.0.0.0
103
104    maxcallnumbers = 16382
105
106    ...
107
108   2.1.2. Controlled Networks
109
110    This section discusses what needs to be done for an Asterisk server on a
111    network where no unsolicited traffic will reach the IAX2 service.
112
113     2.1.2.1. Full Upgrade
114
115    If all IAX2 endpoints have been upgraded, then no changes to configuration
116    need to be made.
117
118     2.1.2.2. Partial Upgrade
119
120    If only some of the IAX2 endpoints have been upgraded, then some
121    configuration changes will need to be made for interoperability. Since
122    this is for a controlled network, the easiest thing to do is to disable
123    call token validation completely, as described in section 2.1.1.
124
125   2.1.3. Public Networks
126
127    This section discusses the use of the IAX2 security functionality on
128    public networks where it is possible to receive unsolicited IAX2 traffic.
129
130     2.1.3.1. Full Upgrade
131
132    If all IAX2 endpoints have been upgraded to support call token validation,
133    then no changes need to be made. However, for enhanced security, the
134    administrator may adjust call number limits to further reduce the
135    potential impact of malicious call number consumption. The following
136    configuration will allow known peers to consume more call numbers than
137    unknown source IP addresses:
138
139    [general]
140
141    ; By default, restrict call number usage to a low number.
142
143    maxcallnumbers = 16
144
145    ...
146
147    [callnumberlimits]
148
149    ; For peers with known IP addresses, call number limits can
150
151    ; be set in this section. This limit is per IP address for
152
153    ; addresses that fall in the specified range.
154
155    ; <IP>/<mask> = <limit>
156
157    192.168.1.0/255.255.255.0 = 1024
158
159    ...
160
161    [peerA]
162
163    ; Since we won't know the IP address of a dynamic peer until
164
165    ; they register, a max call number limit can be set in a
166
167    ; dynamic peer configuration section.
168
169    Type = peer
170
171    host = dynamic
172
173    maxcallnumbers = 1024
174
175    ...
176
177     2.1.3.2. Partial Upgrade
178
179    If only some IAX2 endpoints have been upgraded, or the status of an IAX2
180    endpoint is unknown, then call token validation must be disabled to ensure
181    interoperability. To reduce the potential impact of disabling call token
182    validation, it should only be disabled for a specific peer or user as
183    needed. By using the auto option, call token validation will be changed to
184    required as soon as we determine that the peer supports it.
185
186    [friendA]
187
188    requirecalltoken = auto
189
190    ...
191
192    Note that there are some cases where auto should not be used. For example,
193    if multiple peers use the same authentication details, and they have not
194    all upgraded to support call token validation, then the ones that do not
195    support it will get locked out. Once an upgraded client successfully
196    completes an authenticated call setup using call token validation,
197    Asterisk will require it from then on. In that case, it would be better to
198    set the requirecalltoken option to no.
199
200     2.1.3.3. Guest Access
201
202    Guest access via IAX2 requires special attention. Given the number of
203    existing IAX2 endpoints that do not support call token validation, most
204    systems that allow guest access should do so without requiring call token
205    validation.
206
207    [guest]
208
209    ; Note that the name "guest" is special here. When the code
210
211    ; tries to determine if call token validation is required, it
212
213    ; will look for a user by the username specified in the
214
215    ; request. Guest calls can be sent without a username. In
216
217    ; that case, we will look for a defined user called "guest" to
218
219    ; determine if call token validation is required or not.
220
221    type = user
222
223    requirecalltoken = no
224
225    ...
226
227    Since disabling call token validation for the guest account allows a huge
228    hole for malicious call number consumption, an option has been provided to
229    segregate the call numbers consumed by connections not using call token
230    validation from those that do. That way, there are resources dedicated to
231    the more secure connections to ensure that service is not interrupted for
232    them.
233
234    [general]
235
236    maxcallnumbers_nonvalidated = 2048
237
238 2.2. CLI Commands
239
240   2.2.1. iax2 show callnumber usage
241
242    Usage: iax2 show callnumber usage [IP address]
243
244    Show current IP addresses which are consuming IAX2 call numbers.
245
246   2.2.2. iax2 show peer
247
248    This command will now also show the configured call number limit and
249    whether or not call token validation is required for this peer.
250
251                             3. Protocol Modification
252
253    This section discusses the modification that has been made to the IAX2
254    protocol. This information would be most useful to implementors of IAX2.
255
256 3.1. Overview
257
258    The IAX2 protocol uses a call number to associate messages with which call
259    they belong to. The available amount of call numbers is finite as defined
260    by the protocol. Because of this, it is important to prevent attackers
261    from maliciously consuming call numbers. To achieve this, an enhancement
262    to the IAX2 protocol has been made which is referred to as call token
263    validation.
264
265    Call token validation ensures that an IAX2 connection is not coming from a
266    spoofed IP address. In addition to using call token validation, Asterisk
267    will also limit how many call numbers may be consumed by a given remote IP
268    address. These limits have defaults that will usually not need to be
269    changed, but can be modified for a specific need.
270
271    The combination of call token validation and call number limits is used to
272    mitigate a denial of service attack to consume all available IAX2 call
273    numbers. An alternative approach to securing IAX2 would be to use a
274    security layer on top of IAX2, such as DTLS [RFC4347] or IPsec [RFC4301].
275
276 3.2. Call Token Validation
277
278    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
279    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
280    document are to be interpreted as described in RFC 2119.
281
282    For this section, when the word "request" is used, it is referring to the
283    command that starts an IAX2 dialog.
284
285    This modification adds a new IAX2 frame type, and a new information
286    element be defined.
287
288    Frame Type: CALLTOKEN --- 0x28 (40)
289
290    IE: CALLTOKEN --- 0x36 (54)
291
292    When a request is initially sent, it SHOULD include the CALLTOKEN IE with
293    a zero-length payload to indicate that this client supports the CALLTOKEN
294    exchange. When a server receives this request, it MUST respond with the
295    IAX2 message CALLTOKEN. The CALLTOKEN message MUST be sent with a source
296    call number of 0, as a call number will not yet be allocated for this
297    call.
298
299    For the sake of backwards compatibility with clients that do not support
300    token validation, server implementations MAY process requests that do not
301    indicate CALLTOKEN support in their initial request. However, this SHOULD
302    NOT be the default behavior, as it gives up the security benefits gained
303    by CALLTOKEN validation.
304
305    After a client sends a request with an empty CALLTOKEN IE, it MUST be
306    prepared to receive a CALLTOKEN response, or to receive a response that
307    would be given in the case of a valid CALLTOKEN. This is how a client must
308    behave to inter operate with IAX2 server implementations that do not yet
309    support CALLTOKEN validation.
310
311    When an IAX2 client receives a CALLTOKEN response, it MUST send its
312    initial request again. This request MUST include the CALLTOKEN IE with a
313    copy of the value of the CALLTOKEN IE received in the CALLTOKEN response.
314    The IE value is an opaque value. Clients MUST be able to accept a
315    CALLTOKEN payload of any length, up to the maximum length allowed in an
316    IAX2 IE.
317
318    The value of the payload in the CALLTOKEN IE is an implementation detail.
319    It is left to the implementor to decide how sophisticated it should be.
320    However, it MUST be enough such that when the CALLTOKEN IE is sent back,
321    it can be used to verify that the source IP address and port number has
322    not been spoofed.
323
324    If a server receives a request with an invalid CALLTOKEN IE value, then it
325    MUST drop it and not respond.
326
327 3.3. Example Message Exchanges
328
329   3.3.1. Call Setup
330
331    Client Server
332
333    -------- --------
334
335    ------------- NEW ----------->
336
337    (with empty CALLTOKEN IE)
338
339    <---------- CALLTOKEN ------------
340
341    (client must ignore
342
343    source call number
344
345    from this message)
346
347    ------------- NEW ----------->
348
349    (with received token)
350
351    <---------- AUTHREQ ----------
352
353    ... continue as normal ...
354
355   3.3.2. Call Setup, client does not support CALLTOKEN
356
357    Client Server
358
359    -------- --------
360
361    ------------- NEW ----------->
362
363    (with no CALLTOKEN IE)
364
365    <----------- REJECT ----------
366
367    (sent without allocating
368
369    a call number)
370
371    ------------- ACK ----------->
372
373   3.3.3. Call Setup, client supports CALLTOKEN, server does not
374
375    Client Server
376
377    -------- --------
378
379    ------------- NEW ----------->
380
381    (with empty CALLTOKEN IE)
382
383    <----------- AUTHREQ ---------
384
385    (sent without allocating
386
387    a call number)
388
389    ... continue as normal ...
390
391   3.3.4. Call Setup from client that sends invalid token
392
393    Client Server
394
395    -------- --------
396
397    ------------- NEW ----------->
398
399    (with invalid CALLTOKEN IE)
400
401    ... dropped ...
402
403                            4. Asterisk Implementation
404
405    This section includes some additional details on the implementation of
406    these changes in Asterisk.
407
408 4.1. CALLTOKEN IE Payload
409
410    For Asterisk, we will encode the payload of the CALLTOKEN IE such that the
411    server is able to validate a received token without having to store any
412    information after transmitting the CALLTOKEN response. The CALLTOKEN IE
413    payload will contain:
414
415      * A timestamp (epoch based)
416
417      * SHA1 hash of the remote IP address and port, the timestamp, as well
418        some random data generated when Asterisk starts.
419
420    When a CALLTOKEN IE is received, its validity will be determined by
421    recalculating the SHA1 hash. If it is a valid token, the timestamp is
422    checked to determine if the token is expired. The token timeout will be
423    hard coded at 10 seconds for now. However, it may be made configurable at
424    some point if it seems to be a useful addition. If the server determines
425    that a received token is expired, it will treat it as an invalid token and
426    not respond to the request.
427
428    By using this method, we require no additional memory to be allocated for
429    a dialog, other than what is on the stack for processing the initial
430    request, until token validation is complete.
431
432    However, one thing to note with this CALLTOKEN IE encoding is that a token
433    would be considered valid by Asterisk every time a client sent it until we
434    considered it an expired token. However, with use of the "maxcallnumbers"
435    option, this is not actually a problem. It just means that an attacker
436    could hit their call number limit a bit quicker since they would only have
437    to acquire a single token per timeout period, instead of a token per
438    request.
439
440                                     10 of 10