Asterisk IAX Authentication

This page attempts to document the process that Asterisk uses to authenticate incoming and outgoing IAX2 connections. To go directly to setup instructions, see instead "configuring IAX clients". Reference to "type=user" in the text below should be assumed to include "type=friend' as well, since a friend can act as a user. The same assumption holds for "type=peer" references below.

Incoming Connections

When Asterisk receives an incoming IAX connection, the initial call information can include a username (the IAX2 USERNAME Information Element) or not. In addition, the incoming connection has a source IP address that Asterisk can use for authentication as well.

If a USERNAME is supplied, Asterisk does the following:

1. Searches iax.conf for a "type=user" section with a section name identical to the USERNAME supplied by the call. If found, that section will be used. (For example, if the USERNAME IE contains "johndoe", the "[johndoe]" section will be used. Note: Any and all username= lines in type=user sections are totally ignored.) If no matching section is found, the call will be rejected.
2. If the section chosen has allow and/or deny directives, Asterisk compares the IP address of the caller to the address class specified in each, in the order the directives are specified. If the calling address ends up being disallowed, the call will be rejected.
3. Performs the desired secret checking (plaintext, md5, or rsa). If the secret supplied by the caller does not pass this check, the call will be rejected.
4. If the incoming call specifies a destination context, Asterisk searches the matching section for a context= line with that name. If a context= line is found with that name, the call will be sent to the specified context and extension.
5. If the call does not specify a destination context, the call will be sent to the specified extension in the context named by the first context= line listed in the section.
6. Note that this incoming context should best specify a catch-all extension pattern of "_X." during debugging, since otherwise you - like about 40000 other Google hits - may easily fall prey to Asterisk not being able to locate the given extension in this context and putting out an unhelpful "No such context/extension" IAX2 debug error while remaining terribly silent about this error otherwise.

If a USERNAME is not supplied, Asterisk does the following:

1. Searches iax.conf for a "type=user" section which does not specify a secret, but specifies "allow" and/or "deny" restrictions which do not restrict the caller from connecting. If such a section is found, the call will be accepted, and the name of the section found will be used as the connecting username.
2. Searches iax.conf for a "type=user" section which has neither any secret specified nor any "allow" or "deny" directives at all. If such a section is found, the call will be accepted, and the name of the section found will be used as the connecting username.
3. Searches iax.conf for a "type=user" section which specifies both a secret (or RSA key) and "allow" and/or "deny" restrictions which do not restrict the caller from connecting. If such a section is found, and the call can be authenticated using the specified secret or key, then the call will be accepted, and the name of the section found will be used as the connecting username.
4. Searches iax.conf for a "type=user" section with a secret (or RSA key) specified, but no "allow" and/or "deny" directives at all. If such a section is found, and the call can be authenticated using the specified secret or key, then the call will be accepted, and the name of the section found will be used as the connecting username.
5. Rejects the call.

Suppose, for example, that your iax.conf file has the following entries:

[guest]
type=user
context=guest

[iaxtel]
type=user
context=incoming
auth=rsa
inkeys=iaxtel

[iax-gateway]
type=friend
permit=192.168.0.1
context=incoming
host=192.168.0.1

[iax-friend]
type=user
secret=this_is_secret
auth=md5
context=incoming

If an incoming call has a specified username of:

• guest
• iaxtel
• iax-gateway
• iax-friend

then Asterisk will attempt to authenticate the connection using only the section with the identical name. If any other username is specified, the call will be rejected.

If no username or secret is specified, Asterisk will authenticate the call as either "guest" or "iax-gateway", depending on the caller's IP address. If the caller's IP address is 192.168.0.1, the call will authenticate as the user "iax-gateway". If the caller's IP address is anything else, the call will authenticate as the user "guest".

If every type=user section in your iax.conf file specifies a secret, or all of your type=user sections without secrets have "permit" and/or "deny" directives which restrict the caller from connecting, then the caller can specify the secret associated with any other IAX user for which the caller is not IP-restricted, and the caller will be successfully authenticated as that user. In the example above, if the caller happens to specify "this_is_secret" as their secret, they will be authenticated as the user "iax-friend", without having actually supplied that username during the authentication process. If you have a large number of IAX "user" sections with secrets, if these sections have fairly open or absent IP constraints, and if every IAX "user" section without a secret is IP-restricted, you will have a large number of "guessable" secrets that anyone can use to connect to your system.

One way to mitigate this problem is to use RSA keys as your secrets. Because RSA challenge responses are more evenly distributed and have a mandatory minimum length, they will be harder to guess. Additionally, if you specify the delayreject= directive in the [general] section of your iax.conf, Asterisk will delay after failed authentication attempts, slowing down potential dictionary attacks. Yet another way to mitigate this problem is using IP address restrictions on as many of your "user" sections as you can manage. The problem can be avoided altogether, however, by including a type=user section in iax.conf with no secret and open or absent IP constraints. Users such as these are referred to as guest or anonymous users. If your IAX contfiguration contains an anonymous user section, and an IAX call placed to your server specifies a secret but no username, the call will safely be directed to the anonymous user, without exposing secrets from any other users in iax.conf.

Outgoing Connections

Outgoing Asterisk connections can gather their authentication information from:

• the IAX2 channel description passed to the Dial command (see Asterisk IAX channels)
• a "type=peer" or "type=friend" entry in iax.conf
• a combination of these two sources

Suppose your iax.conf file has the following entries:

[iaxtel-outbound]
type=peer
username=iaxtel_username
secret=iaxtel_secret
host=iaxtel.com

[iax-gateway]
type=friend
permit=192.168.0.1
context=incoming
host=192.168.0.1

Then:

 Dial(IAX2/iaxtel-outbound/1234)

would connect to host "iaxtel.com", specifying the iax.conf-supplied username and secret for authentication.

 Dial(IAX2/user2:secret2@iaxtel-outbound/1234)

would also connect to host "iaxtel.com", but would specify "user2" and "secret2", overriding the entries in iax.conf.

 Dial(IAX2/iaxtel.com/1234)

Again, connection would be made to host "iaxtel.com", but no username or secret would be specified, as none were included in the IAX2 channel description and "iaxtel.com" does not match the names of any iax.conf "type=peer" entries (even though it matches a hostname specified within one of those entries).

 Dial(IAX2/iax-gateway/5678)

would connect to host 192.168.0.1, specifying no username at all, and if the host requests a secret, no secret will be supplied. Presumably this type of entry would be used for connections between very well trusted hosts.

See Also:

• Asterisk IAX channels
• Asterisk config iax.conf
• Asterisk No authority found

---

• Asterisk | Asterisk FAQ | Channels