<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2171/18/9/_/styles/combined.css?spaceKey=AST&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/AST/IAX2+Security">IAX2 Security</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~seanbright">Sean Bright</a>
</h4>
<br/>
<h4>Changes (1)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-added-lines" style="background-color: #dfd;">{gliffy:name=IAX2 Call Setup - Call Token Support|align=left|size=L|version=1} <br></td></tr>
<tr><td class="diff-unchanged" >h1. IAX2 Security <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<div class="error"><span class="error">Error formatting macro: gliffy: java.lang.ClassCastException: com.atlassian.confluence.util.ConfluenceMockServletRequest cannot be cast to javax.servlet.http.HttpServletRequest</span> </div>
<h1><a name="IAX2Security-IAX2Security"></a>IAX2 Security</h1>
<p>Copyright (c) 2009 - Digium, Inc.<br/>
All Rights Reserved.<br/>
Document Version 1.0<br/>
09/03/09<br/>
Asterisk Development Team <asteriskteam@digium.com></p>
<div>
<ul>
<li><span class='TOCOutline'>1</span> <a href='#IAX2Security-Introduction'>Introduction</a></li>
<ul>
<li><span class='TOCOutline'>1.1</span> <a href='#IAX2Security-Overview'>Overview</a></li>
</ul>
<li><span class='TOCOutline'>2</span> <a href='#IAX2Security-UserGuide'>User Guide</a></li>
<ul>
<li><span class='TOCOutline'>2.1</span> <a href='#IAX2Security-Configuration'>Configuration</a></li>
<ul>
<li><span class='TOCOutline'>2.1.1</span> <a href='#IAX2Security-QuickStart'>Quick Start</a></li>
<li><span class='TOCOutline'>2.1.2</span> <a href='#IAX2Security-ControlledNetworks'>Controlled Networks</a></li>
<ul>
<li><span class='TOCOutline'>2.1.2.1</span> <a href='#IAX2Security-FullUpgrade'>Full Upgrade</a></li>
<li><span class='TOCOutline'>2.1.2.2</span> <a href='#IAX2Security-PartialUpgrade'>Partial Upgrade</a></li>
</ul>
<li><span class='TOCOutline'>2.1.3</span> <a href='#IAX2Security-PublicNetworks'>Public Networks</a></li>
<ul>
<li><span class='TOCOutline'>2.1.3.1</span> <a href='#IAX2Security-FullUpgrade'>Full Upgrade</a></li>
<li><span class='TOCOutline'>2.1.3.2</span> <a href='#IAX2Security-PartialUpgrade'>Partial Upgrade</a></li>
<li><span class='TOCOutline'>2.1.3.3</span> <a href='#IAX2Security-GuestAccess'>Guest Access</a></li>
</ul>
</ul>
<li><span class='TOCOutline'>2.2</span> <a href='#IAX2Security-CLICommands'>CLI Commands</a></li>
<ul>
<li><span class='TOCOutline'>2.2.1</span> <a href='#IAX2Security-%7B%7Biax2showcallnumberusage%7D%7D'> <tt>iax2 show callnumber usage</tt></a></li>
<li><span class='TOCOutline'>2.2.2</span> <a href='#IAX2Security-%7B%7Biax2showpeer%7D%7D'> <tt>iax2 show peer</tt></a></li>
</ul>
</ul>
<li><span class='TOCOutline'>3</span> <a href='#IAX2Security-ProtocolModification'>Protocol Modification</a></li>
<ul>
<li><span class='TOCOutline'>3.1</span> <a href='#IAX2Security-Overview'>Overview</a></li>
<li><span class='TOCOutline'>3.2</span> <a href='#IAX2Security-CallTokenValidation'>Call Token Validation</a></li>
<li><span class='TOCOutline'>3.3</span> <a href='#IAX2Security-ExampleMessageExchanges'>Example Message Exchanges</a></li>
<ul>
<li><span class='TOCOutline'>3.3.1</span> <a href='#IAX2Security-CallSetup'>Call Setup</a></li>
<li><span class='TOCOutline'>3.3.2</span> <a href='#IAX2Security-CallSetup%2CclientdoesnotsupportCALLTOKEN'>Call Setup, client does not support CALLTOKEN</a></li>
<li><span class='TOCOutline'>3.3.3</span> <a href='#IAX2Security-CallSetup%2CclientsupportsCALLTOKEN%2Cserverdoesnot'>Call Setup, client supports CALLTOKEN, server does not</a></li>
<li><span class='TOCOutline'>3.3.4</span> <a href='#IAX2Security-CallSetupfromclientthatsendsinvalidtoken'>Call Setup from client that sends invalid token</a></li>
</ul>
</ul>
<li><span class='TOCOutline'>4</span> <a href='#IAX2Security-AsteriskImplementation'>Asterisk Implementation</a></li>
<ul>
<li><span class='TOCOutline'>4.1</span> <a href='#IAX2Security-CALLTOKENIEPayload'>CALLTOKEN IE Payload</a></li>
</ul>
</ul></div>
<h2><a name="IAX2Security-Introduction"></a>Introduction</h2>
<h3><a name="IAX2Security-Overview"></a>Overview</h3>
<p>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.</p>
<p>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.</p>
<p>For additional details about the configuration options referenced in this document, see the sample configuration file, <tt>iax.conf.sample</tt>. For information regarding the details of the call token validation protocol modification, see <a href="#IAX2Security-ProtocolModification">Protocol Modification</a>.</p>
<h2><a name="IAX2Security-UserGuide"></a>User Guide</h2>
<h3><a name="IAX2Security-Configuration"></a>Configuration</h3>
<h4><a name="IAX2Security-QuickStart"></a>Quick Start</h4>
<p>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 <tt>[general]</tt> section of <tt>iax.conf</tt>:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>iax.conf</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: plain; gutter: false">[general]
...
calltokenoptional = 0.0.0.0/0.0.0.0
maxcallnumbers = 16382
...</pre>
</div></div>
<h4><a name="IAX2Security-ControlledNetworks"></a>Controlled Networks</h4>
<p>This section discusses what needs to be done for an Asterisk server on a network where no unsolicited traffic will reach the IAX2 service.</p>
<h5><a name="IAX2Security-FullUpgrade"></a>Full Upgrade</h5>
<p>If all IAX2 endpoints have been upgraded, then no changes to configuration need to be made.</p>
<h5><a name="IAX2Security-PartialUpgrade"></a>Partial Upgrade</h5>
<p>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 under <a href="#IAX2Security-QuickStart">Quick Start</a>.</p>
<h4><a name="IAX2Security-PublicNetworks"></a>Public Networks</h4>
<p>This section discusses the use of the IAX2 security functionality on public networks where it is possible to receive unsolicited IAX2 traffic.</p>
<h5><a name="IAX2Security-FullUpgrade"></a>Full Upgrade</h5>
<p>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:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>iax.conf</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: plain; gutter: false">[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
...</pre>
</div></div>
<h5><a name="IAX2Security-PartialUpgrade"></a>Partial Upgrade</h5>
<p>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<br/>
required as soon as we determine that the peer supports it.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>iax.conf</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: plain; gutter: false">[friendA]
requirecalltoken = auto
...</pre>
</div></div>
<p>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,<br/>
Asterisk will require it from then on. In that case, it would be better to set the requirecalltoken option to no.</p>
<h5><a name="IAX2Security-GuestAccess"></a>Guest Access</h5>
<p>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.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>iax.conf</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: plain; gutter: false">[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
...</pre>
</div></div>
<p>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.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>iax.conf</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: plain; gutter: false">[general]
maxcallnumbers_nonvalidated = 2048
...</pre>
</div></div>
<h3><a name="IAX2Security-CLICommands"></a>CLI Commands</h3>
<h4><a name="IAX2Security-%7B%7Biax2showcallnumberusage%7D%7D"></a><tt>iax2 show callnumber usage</tt></h4>
<p>Usage: <tt>iax2 show callnumber usage [IP address]</tt></p>
<p>Show current IP addresses which are consuming IAX2 call numbers.</p>
<h4><a name="IAX2Security-%7B%7Biax2showpeer%7D%7D"></a><tt>iax2 show peer</tt></h4>
<p>This command will now also show the configured call number limit and whether or not call token validation is required for this peer.</p>
<h2><a name="IAX2Security-ProtocolModification"></a>Protocol Modification</h2>
<p>This section discusses the modification that has been made to the IAX2 protocol. This information would be most useful to implementors of IAX2.</p>
<h3><a name="IAX2Security-Overview"></a>Overview</h3>
<p>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.</p>
<p>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.</p>
<p>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 <a href="http://www.ietf.org/rfc/rfc4347" class="external-link" rel="nofollow">RFC 4347</a> or IPsec <a href="http://www.ietf.org/rfc/rfc4301" class="external-link" rel="nofollow">RFC 4301</a>.</p>
<h3><a name="IAX2Security-CallTokenValidation"></a>Call Token Validation</h3>
<p>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.</p>
<p>For this section, when the word "request" is used, it is referring to the command that starts an IAX2 dialog.</p>
<p>This modification adds a new IAX2 frame type, and a new information element be defined.</p>
<p>Frame Type: CALLTOKEN — 0x28 (40)</p>
<p>IE: CALLTOKEN — 0x36 (54)</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>If a server receives a request with an invalid CALLTOKEN IE value, then it MUST drop it and not respond.</p>
<h3><a name="IAX2Security-ExampleMessageExchanges"></a>Example Message Exchanges</h3>
<h4><a name="IAX2Security-CallSetup"></a>Call Setup</h4>
<p><span class="image-wrap" style=""><img src="/wiki/download/attachments/4259943/call-setup.png?version=1&modificationDate=1336495038604" style="border: 0px solid black" /></span></p>
<h4><a name="IAX2Security-CallSetup%2CclientdoesnotsupportCALLTOKEN"></a>Call Setup, client does not support CALLTOKEN</h4>
<div class="error"><span class="error">Error formatting macro: gliffy: java.lang.ClassCastException: com.atlassian.confluence.util.ConfluenceMockServletRequest cannot be cast to javax.servlet.http.HttpServletRequest</span> </div>
<h4><a name="IAX2Security-CallSetup%2CclientsupportsCALLTOKEN%2Cserverdoesnot"></a>Call Setup, client supports CALLTOKEN, server does not</h4>
<div class="error"><span class="error">Error formatting macro: gliffy: java.lang.ClassCastException: com.atlassian.confluence.util.ConfluenceMockServletRequest cannot be cast to javax.servlet.http.HttpServletRequest</span> </div>
<h4><a name="IAX2Security-CallSetupfromclientthatsendsinvalidtoken"></a>Call Setup from client that sends invalid token</h4>
<div class="error"><span class="error">Error formatting macro: gliffy: java.lang.ClassCastException: com.atlassian.confluence.util.ConfluenceMockServletRequest cannot be cast to javax.servlet.http.HttpServletRequest</span> </div>
<h2><a name="IAX2Security-AsteriskImplementation"></a>Asterisk Implementation</h2>
<p>This section includes some additional details on the implementation of these changes in Asterisk.</p>
<h3><a name="IAX2Security-CALLTOKENIEPayload"></a>CALLTOKEN IE Payload</h3>
<p>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:</p>
<ul>
<li>A timestamp (epoch based)</li>
</ul>
<ul>
<li>SHA1 hash of the remote IP address and port, the timestamp, as well some random data generated when Asterisk starts.</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=AST">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/AST/IAX2+Security">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=4259943&revisedVersion=27&originalVersion=26">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/IAX2+Security?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>