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