3 Copyright (c) 2009 - Digium, Inc.
11 Asterisk Development Team <asteriskteam@digium.com>
25 2.1.2. Controlled Networks 4
27 2.1.2.1. Full Upgrade 4
29 2.1.2.2. Partial Upgrade 4
31 2.1.3. Public Networks 4
33 2.1.3.1. Full Upgrade 4
35 2.1.3.2. Partial Upgrade 5
37 2.1.3.3. Guest Access 5
41 2.2.1. iax2 show callnumber usage 6
43 2.2.2. iax2 show peer 6
45 3. Protocol Modification 6
49 3.2. Call Token Validation 7
51 3.3. Example Message Exchanges 8
55 3.3.2. Call Setup, client does not support CALLTOKEN 8
57 3.3.3. Call Setup, client supports CALLTOKEN, server does not 9
59 3.3.4. Call Setup from client that sends invalid token 9
61 4. Asterisk Implementation 9
63 4.1. CALLTOKEN IE Payload 9
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.
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.
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.
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
102 calltokenoptional = 0.0.0.0/0.0.0.0
104 maxcallnumbers = 16382
108 2.1.2. Controlled Networks
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.
113 2.1.2.1. Full Upgrade
115 If all IAX2 endpoints have been upgraded, then no changes to configuration
118 2.1.2.2. Partial Upgrade
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.
125 2.1.3. Public Networks
127 This section discusses the use of the IAX2 security functionality on
128 public networks where it is possible to receive unsolicited IAX2 traffic.
130 2.1.3.1. Full Upgrade
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:
141 ; By default, restrict call number usage to a low number.
149 ; For peers with known IP addresses, call number limits can
151 ; be set in this section. This limit is per IP address for
153 ; addresses that fall in the specified range.
155 ; <IP>/<mask> = <limit>
157 192.168.1.0/255.255.255.0 = 1024
163 ; Since we won't know the IP address of a dynamic peer until
165 ; they register, a max call number limit can be set in a
167 ; dynamic peer configuration section.
173 maxcallnumbers = 1024
177 2.1.3.2. Partial Upgrade
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.
188 requirecalltoken = auto
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.
200 2.1.3.3. Guest Access
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
209 ; Note that the name "guest" is special here. When the code
211 ; tries to determine if call token validation is required, it
213 ; will look for a user by the username specified in the
215 ; request. Guest calls can be sent without a username. In
217 ; that case, we will look for a defined user called "guest" to
219 ; determine if call token validation is required or not.
223 requirecalltoken = no
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
236 maxcallnumbers_nonvalidated = 2048
240 2.2.1. iax2 show callnumber usage
242 Usage: iax2 show callnumber usage [IP address]
244 Show current IP addresses which are consuming IAX2 call numbers.
246 2.2.2. iax2 show peer
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.
251 3. Protocol Modification
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.
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
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.
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].
276 3.2. Call Token Validation
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.
282 For this section, when the word "request" is used, it is referring to the
283 command that starts an IAX2 dialog.
285 This modification adds a new IAX2 frame type, and a new information
288 Frame Type: CALLTOKEN --- 0x28 (40)
290 IE: CALLTOKEN --- 0x36 (54)
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
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.
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.
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
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
324 If a server receives a request with an invalid CALLTOKEN IE value, then it
325 MUST drop it and not respond.
327 3.3. Example Message Exchanges
335 ------------- NEW ----------->
337 (with empty CALLTOKEN IE)
339 <---------- CALLTOKEN ------------
347 ------------- NEW ----------->
349 (with received token)
351 <---------- AUTHREQ ----------
353 ... continue as normal ...
355 3.3.2. Call Setup, client does not support CALLTOKEN
361 ------------- NEW ----------->
363 (with no CALLTOKEN IE)
365 <----------- REJECT ----------
367 (sent without allocating
371 ------------- ACK ----------->
373 3.3.3. Call Setup, client supports CALLTOKEN, server does not
379 ------------- NEW ----------->
381 (with empty CALLTOKEN IE)
383 <----------- AUTHREQ ---------
385 (sent without allocating
389 ... continue as normal ...
391 3.3.4. Call Setup from client that sends invalid token
397 ------------- NEW ----------->
399 (with invalid CALLTOKEN IE)
403 4. Asterisk Implementation
405 This section includes some additional details on the implementation of
406 these changes in Asterisk.
408 4.1. CALLTOKEN IE Payload
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:
415 * A timestamp (epoch based)
417 * SHA1 hash of the remote IP address and port, the timestamp, as well
418 some random data generated when Asterisk starts.
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.
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.
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