Independent Submission M. Spencer Request for Comments: 5456 Digium, Inc. Category: Informational B. Capouch ISSN: 2070-1721 Saint Joseph's College E. Guy, Ed. Truphone F. Miller Cornfed Systems, LLC K. Shumard February 2010 IAX: Inter-Asterisk eXchange Version 2 Abstract This document describes IAX, the Inter-Asterisk eXchange protocol, an application-layer control and media protocol for creating, modifying, and terminating multimedia sessions over Internet Protocol (IP) networks. IAX was developed by the open source community for the Asterisk Private Branch Exchange (PBX) and is targeted primarily at Voice over Internet Protocol (VoIP) call control, but it can be used with streaming video or any other type of multimedia. IAX is an "all in one" protocol for handling multimedia in IP networks. It combines both control and media services in the same protocol. In addition, IAX uses a single UDP data stream on a static port greatly simplifying Network Address Translation (NAT) gateway traversal, eliminating the need for other protocols to work around NAT, and simplifying network and firewall management. IAX employs a compact encoding that decreases bandwidth usage and is well suited for Internet telephony service. In addition, its open nature permits new payload type additions needed to support additional services. Status of This Memo This document is not an Internet Standards Track specification; it is published for informational purposes. This is a contribution to the RFC Series, independently of any other RFC stream. The RFC Editor has chosen to publish this document at its discretion and makes no statement about its value for implementation or deployment. Documents approved for publication by the RFC Editor are not a candidate for any level of Internet Standard; see Section 2 of RFC 5741. Spencer, et al. Informational [Page 1] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc5456. IESG Note This RFC is not a candidate for any level of Internet Standard. The IETF disclaims any knowledge of the fitness of this RFC for any purpose and in particular notes that the decision to publish is not based on IETF review for such things as security, congestion control, or inappropriate interaction with deployed protocols. The RFC Editor has chosen to publish this document at its discretion. Readers of this document should exercise caution in evaluating its value for implementation and deployment. See RFC 3932 for more information. The IESG thinks that this work is related to IETF work done in SIP, MMUSIC, and AVT WGs, but this does not prevent publishing. Copyright Notice Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Spencer, et al. Informational [Page 2] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 Table of Contents 1. Introduction ....................................................4 1.1. Basic Properties ...........................................4 1.2. Drawbacks ..................................................5 2. IAX Terminology .................................................6 3. Overview of IAX Protocol ........................................6 4. Naming Conventions ..............................................8 5. IAX Uniform Resource Identifiers ................................8 5.1. IAX URI Scheme Registration ................................8 5.2. URI Comparison ............................................11 6. Peer Behavior and Related Messages .............................11 6.1. Registration (OPTIONAL) ...................................12 6.2. Call Leg Management .......................................18 6.3. Call Control ..............................................24 6.4. Mid-Call Link Operations ..................................26 6.5. Call Path Optimization ....................................28 6.6. Call Tear Down ............................................33 6.7. Network Monitoring ........................................33 6.8. Digit Dialing .............................................34 6.9. Miscellaneous .............................................36 6.10. Media Messages ...........................................38 7. Message Transport ..............................................39 7.1. Trunking ..................................................40 7.2. Timers ....................................................41 7.3. NAT Considerations ........................................41 7.4. Encryption ................................................42 8. Message Encoding ...............................................42 8.1. Frame Structure ...........................................42 8.2. Frame Types ...............................................52 8.3. Control Frames Subclasses .................................55 8.4. IAX Frames ................................................56 8.5. HTML Command Subclasses ...................................58 8.6. Information Elements ......................................58 8.7. Media Formats .............................................86 9. Example Message Flows ..........................................87 9.1. Ping/Pong .................................................88 9.2. Lagrq/Lagrp ...............................................88 9.3. Registration ..............................................89 9.4. Registration Release ......................................89 9.5. Call Path Optimization ....................................90 9.6. IAX Media Call ............................................91 9.7. IAX Media Call via an IAX Device ..........................93 10. Security Considerations .......................................94 11. IANA Considerations ...........................................96 12. Implementation Notes ..........................................96 13. Acknowledgments ...............................................97 Spencer, et al. Informational [Page 3] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 14. References ....................................................97 14.1. Normative References .....................................97 14.2. Informative References ...................................99 1. Introduction Numerous protocols have been specified by the Internet community to support control or signaling of multimedia sessions, for instance, SIP [RFC3261], Media Gateway Control Protocol (MGCP) [RFC3435], and MEGACO/H.248 [RFC3525] (which has been obsoleted and made historic by [RFC5125]). In general, these protocols are designed to offer full support for many types of media transmission. This flexible approach adds some overhead to the protocol headers, but allows for the protocol use well beyond the current application. Typically, these protocols reference, but do not specify, the media transmission protocol used to carry the actual stream. SIP commonly uses Session Description Protocol (SDP) [RFC4566] to specify Real-Time Transport Protocol (RTP) [RFC3550] streams. This method allows for great flexibility, but again leads to more overhead. Furthermore, multimedia solutions that use different, perhaps dynamic, network addresses for signaling and media transmission frequently suffer from Network Address Translation (NAT) traversal and security challenges. IAX is the Inter-Asterisk eXchange protocol, which facilitates VoIP connections between servers, and between servers and clients that also use the IAX protocol. IAX was created through an open source methodology rather than through a traditional, standards-based methodology. It is an open protocol originally used by Asterisk, a dual-licensed open source and commercial PBX server from Digium. Independent IAX implementations may be open, proprietary, or licensed in anyway the author seems fit without royalty to the protocol creators. 1.1. Basic Properties IAX is a robust and full-featured, yet, simple protocol. It is general enough that it can handle most common types of media streams. However, the protocol is highly optimized for VoIP calls where low- overhead and low-bandwidth consumption are priorities. This pragmatic aspect makes IAX more efficient for VoIP than protocols that consider possibilities far beyond current needs and specify many more details than are strictly necessary to describe or transport a point-to-point call. Furthermore, because IAX is designed to be lightweight and VoIP-friendly, it consumes less bandwidth than more general approaches. IAX is a binary protocol, designed to reduce overhead, especially in regards to voice streams. Bandwidth efficiency, in some places, is sacrificed in exchange for bandwidth efficiency for individual voice calls. For example, when Spencer, et al. Informational [Page 4] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 transmitting a voice stream compressed to 8 kbit/s with a 20 ms packetization, each data packet consists of 20 bytes. IAX adds 20% overhead, 4 bytes, on the majority of voice packets while RTP adds 60% overhead with 12 additional bytes per voice packet. In addition to efficiency, IAX's single static UDP port approach makes IAX traffic easy for network managers to shape, prioritize, and pass through firewalls. IAX's basic structure is that it multiplexes signaling and multiple media streams over a single UDP stream between two computers. IAX also uses the same UDP port for both its signaling and media messages, and because all communications regarding a call are done over a the same point-to-point path, NAT traversal is much simpler for IAX than for other commonly deployed protocols. 1.2. Drawbacks While IAX is very effective, addressing many of today's communications needs, it does have a few limitations. For instance, IAX uses a point-to-point codec negotiation mechanism that limits extensibility because every IAX node in a call path must support every used codec to some degree. In addition, the codec definition is controlled by an internally defined 32-bit mask, so the codecs must be defined in the protocol, and the maximum number of simultaneous codecs is, therefore, limited. One of IAX's design strengths also presents a potential problem. The use of a single, well-known, port makes the protocol an easier target for denial-of-service attacks. Real-time systems like VoIP are particularly sensitive to these attacks. The protocol is typically deployed with all signaling and media going to a centralized server. While this combined path approach provides a great deal of control, it limits the overall system scalability. IAX now provides the ability to split the media from the signaling stream, which overcomes this limitation of earlier IAX versions. Most IAX drawbacks are due to implementation issues rather than protocol issues. Threading presents a series of problems. Many implementations have a limited number of threads available to process IAX traffic and can become overwhelmed by high use or denial-of- service attacks. Newer implementations have additional controls to minimize the impact of these challenges. Spencer, et al. Informational [Page 5] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 2. IAX Terminology 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 [RFC2119]. Additionally, this document uses the following terminology: Peer: A host or device that implements the IAX protocol. Call: A call is a relationship between two or more parties (i.e., resources such as devices, user agents, or programs) that exists for some time for the purpose of exchanging real-time media. In the context of this document, a call is an end-to-end relationship where at least the one leg of call path is implemented using the IAX protocol. Calling Party: A device or program that initiates a call. Called Party: A device or program to which a call is directed. Context: A context is a named partition of a Dialplan. Dialplan: A Dialplan is a set of rules for associating provided names and numbers with a particular called party. Frame: The atomic communication unit between two IAX peers. All IAX messages are carried within frames. Information Element (IE): A discrete data unit appended to an IAX frame that specifies user- or call-specific data. Registrant: A registrant is a peer that makes REGISTER requests in order to advertise the address of a resource, i.e., a device or program to which a call may be directed. Registrar: A registrar is a peer that processes REGISTER requests and places the information it receives in those requests into the location service. [RFC3261]. 3. Overview of IAX Protocol IAX is a peer-to-peer, VoIP-oriented protocol. IAX includes both control and media functions. It can register locations, create, modify, terminate multimedia sessions, and carry the actual media streams specified by the sessions it manages. The protocol is designed and optimized for describing and transporting multimedia Spencer, et al. Informational [Page 6] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 calls using Internet Protocol. This document describes Version 2 of IAX; Version 1, although somewhat similar in design, utilized a different port and was not widely deployed. The basic design approach for IAX multiplexes signaling and multiple media streams over a single UDP association between two hosts. This is accomplished by using the same "well-known" UDP port, 4569, for all types of IAX traffic. IAX's unified signaling and media paths achieve NAT transparency, which is an advantage of IAX over alternative media transport protocols such as SIP [RFC3261]. IAX is coded as a binary protocol. One major benefit of using a binary protocol is bandwidth efficiency because the quality of voice calls is frequently related to the amount of bandwidth consumed. This is one way the protocol is specifically optimized to make efficient use of bandwidth for individual voice calls. The bandwidth efficiency for other stream types is sacrificed for the sake of individual voice calls. Other benefits of a binary protocol are robustness against buffer-overrun attacks, and compact implementation capability, which reduces interoperability issues related to parsing. The atomic communication unit in IAX is the "Frame". There are multiple classes of Frames, each of which is described below. In general, "Full Frames" carry signaling/control data, while "Mini Frames" carry media stream data. Full Frames enclose optional 'Information Elements' (IEs). IEs describe various types of user- or call-specific data. "Meta Frames" are used for call trunking or video stream transmission. An IAX-based call may consist of many call legs, or segments. Each call leg may be implemented using different protocols, e.g., SIP to IAX to ISDN (Integrated Services Digital Network). IAX is responsible for setting up one or more legs of a complete call path, not necessarily the end-to-end call. IAX is an optimized peer-to-peer protocol. If two adjacent call legs utilize the IAX protocol and if the intermediate peer determines that it does not need to remain in the call path, it can supervise a calling path change such that it removes itself from the path. This supervision is complete, a call path is not changed until all peers in the optimized call path confirm they can properly communicate. IAX supports security features by allowing multiple methods of user authentication and authorization, as well as allowing multiple security methods for peer registration. IAX also specifies a generic framework for native encryption. Spencer, et al. Informational [Page 7] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 4. Naming Conventions Call Identifier: A call leg is marked with two unique integers, one assigned by each peer involved in creating the call leg. Number: The Calling and Called Numbers are a set of digits and letters identifying a call originator and the desired terminating resource. The term 'Number' is historic and has been expanded to include letters. A peer is responsible for defining its own dialplan. A peer MAY define its dialplan according to ITU-T Recommendation E.164 [E164]. However, this is not required. Username: A username is a string used for identification purposes. 5. IAX Uniform Resource Identifiers 5.1. IAX URI Scheme Registration This section registers IAX according to the guidelines in [RFC4395]. URI scheme name: iax. Status: Permanent. URI scheme syntax: The "iax:" scheme follows the guidelines in [RFC3986]. The general form is as follows: iax:[username@]host[:port][/number[?context]] where these tokens have the following meanings: iax: The literal 'iax:'. username: A string used for identification purposes. host: The domain of the resource. The host part contains either a fully-qualified domain name or numeric IPv4 or IPv6 address. An IPv6 address must be enclosed within brackets (i.e., '[2001:db8::1]') as defined in [RFC3986]. Using the fully-qualified domain name form is RECOMMENDED whenever possible. Spencer, et al. Informational [Page 8] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 port: The numeric UDP port number. number: The name or number identifying the resource on that host. context: The name of the host partition in which the service is identified or processed. Examples iax:example.com/alice iax:example.com:4569/alice iax:example.com:4570/alice?friends iax:192.0.2.4:4569/alice?friends iax:[2001:db8::1]:4569/alice?friends iax:example.com/12022561414 iax:johnQ@example.com/12022561414 ABNF Formal syntax is defined using ABNF [RFC5234]. Certain values are included by reference from [RFC3986]: iax-uri = "iax:" [ userinfo "@" ] host [ ":" port ] [ "/" number [ "?" context ] ] userinfo = host = port = number = *(unreserved / sub-delims / pct-encoded ) context = *(unreserved / sub-delims / pct-encoded ) unreserved = sub-delims = pct-encoded = URI Scheme Semantics: An IAX URI identifies a communications resource capable of communicating using the IAX Version 2 protocol defined in this document. Within this document, we refer to IAX Version 2 protocol URI as IAX. An IAX URI contains enough information to initiate an IAX-based call with that resource. Spencer, et al. Informational [Page 9] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 IAX URIs are associated with server resources to which calls may be routed. For instance, an IAX URI may represent an appearance on a phone, a voice-mail box on a messaging service, an interactive program, a Public Switched Telephone Network (PSTN) address or gateway, or any group of the above. The IAX URI scheme translates into a location that may be used by the IAX protocol to establish a new call using the URI scheme components described in the previous section. This new call function is the only defined operation. Encoding considerations: IAX URI scheme encoding conforms to the encoding rules established for URIs in [RFC3986]. Applications/protocols that use this URI scheme name: The scheme is used by ENUM Dynamic Delegation Discovery System (DDDS) services to specify resources that support the IAX protocol. The IAX protocol provides application-layer control and media protocol for creating, modifying, and terminating multimedia sessions over Internet Protocol (IP) networks. Interoperability considerations: None. Security considerations: The IAX URI Scheme does not introduce any new security concerns except that it provides a uniform syntax for describing IAX resources and that, when published, these addresses are subject to various denial-of-service attacks. Contact: Ed Guy, edguy@emcsw.com, +1.973.437.4519. Author/Change controller Not Applicable. References: RFC 5456 (this document) Spencer, et al. Informational [Page 10] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 5.2. URI Comparison Some operations in this specification require determining whether two IAX URIs are equivalent. IAX URIs are compared for equality according to the following rules: All components of the URI MUST be identical except: The port, if omitted, is considered to be the same as the default, 4569. All URI components, except the username field, are case insensitive, and MUST be normalized to lower case as per Section 6.2.2.1 of [RFC3986] before comparison. The URIs within each of the following sets are equivalent: iax:atlanta.com/alice iax:AtLaNtA.com/ALicE iax:atlanta.com:4569/alice iax:alice@atlanta.com/alice iax:alice@AtLaNtA.com:4569/ALicE The URIs within the following set are not equivalent: iax:ALICE@atlanta.com/alice iax:alice@atlanta.com/alice NOTE: A host in domain form and in IP address form are NOT considered identical even if the host name resolves to an address record that matches the given IP address. 6. Peer Behavior and Related Messages Messages are divided into two categories: reliable and non- guaranteed. The reliable messages are referred to as "Full Frames". In addition to a message type indicator and facilities to ensure reliability, see Section 7, they include the full call identifier. It consists of each of peer's identifiers for the call. Additional attributes, "Information Elements" or "IEs", may be associated with the Full Frame messages. The non-guaranteed messages are referred to as "Mini-Frames" and "Meta Frames" and these more compact messages only have the originating peer's call identifier and MUST NOT have any "Information Elements". Spencer, et al. Informational [Page 11] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 Peer behavior is presented in several partitions divided by the following functional areas: Registration (OPTIONAL) Call Link Management Call Path Optimization (OPTIONAL) Mid-Call Behavior Call Tear Down Network Monitoring Digit Dialing (OPTIONAL) Miscellaneous Media Messages Each of these behavior topics and the messages involved are described in the sections that follow. 6.1. Registration (OPTIONAL) 6.1.1. Overview In order for one IAX peer to be reachable by another IAX peer, the calling peer needs the network address of the receiving peer. This address may be manually provisioned, determined through a shared directory, e.g. an ENUM-like service, [RFC3761] or configured using the IAX protocol. IAX provides a facility for one peer to register its address and credentials with another so that callers can reach the registrant. The IAX registration facility is optional. If implemented, the IAX registration protocol MAY be done in parts, e.g., an analog telephone adapter MAY only implement the registrant portion of the protocol. IAX allows user authentication via multiple methods. MD5 Message- Digest authentication [RFC1321] uses an MD5 sum arrangement, but still requires that both ends have plaintext access to the secret. (See Section 8.6.15.) Rivest, Shamir, and Adleman's (RSA) algorithm [RFC3447] allows unidirectional secret knowledge through public/ private key pairs. IAX Private keys SHOULD always be Triple Data Encryption Standard (3DES) encrypted [RFC1851]. (See Section 8.6.16.) Spencer, et al. Informational [Page 12] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 ________________ | | | Unregistered |<--------------------------\ |________________| | | | /Init | | ------------ | | snd REGREQ | +--------+ | | | | rec REGAUTH | _______V____V___ | ----------- | | | | snd REGREQ | | Reg Sent +----+ | |________________+----------+ | | ^ | rec REGAUTH | rec REGACK | | | /No Credentials| ------------ | | REG timeout | -------------- | snd ack | | ------- | snd ack | | | REGREQ __V___ | _______V____|___ | | | | | | No | | | Registered | | Auth | | |________________| |______| | | ^ | | | rec REGAUTH | | release | /No Credentials| | ------- | -------------- | +-------+ | snd REGREL | snd ack | rec REGAUTH | | | | | ----------- | _V_____V________ | | snd REGREL | | |----------+ | +-----+ Releasing |---------------------------+ |________________| rec ACK ------- x __________ rec REGREJ | | ---------- *->| Rejected | snd ack |__________| Figure 1: Registrant State Diagram Registration, illustrated in Figure 1, is performed by a registrant that sends a username and a registration 'refresh' period to the registrar. This is accomplished with a REGREQ message. If authentication is required, the registrar responds with the REGAUTH message that indicates the types of authentication supported by the Spencer, et al. Informational [Page 13] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 registrar. In response, the registrant resends a REGREQ with one of the supported authentications. If the registrant cannot authenticate, no further action is necessary. If accepted, the registrar sends a REGACK message, which MUST indicate the 'apparent address' and SHOULD indicate the 'refresh'/expire time. If no 'refresh' is sent, a default registration expiration of 60 seconds MUST be assumed by both peers. At any time during this exchange, the registrar may send a REGREJ message to indicate a failure. A registration has a specified time period associated with it for which it is valid. This time period begins when the registrar sends a REGACK message. A registrant may extend that time period by repeating the registration process. A registrant MAY also force an expiration in the registrar by sending the REGREL message. This message may be challenged with REGAUTH or, if sufficient credentials were included, it will be accepted with REGACK. In response to a REGAUTH, a REGREL message SHOULD be resent using the specified credentials. See Sections 9.3 and 9.4 for example call flows. 6.1.2. REGREQ Registration Request Message The REGREQ occurs independently of any media-carrying call. A REGREQ MUST include the 'username' IE and SHOULD include the 'refresh' IE. A REGREQ is used both for an initial registration request as well as for a reply to a REGAUTH. As a reply to a REGAUTH message, it MUST include credentials such as a response to a REGAUTH's challenge. Upon receipt of a REGREQ message that has credentials, a registrar MUST determine their validity. If valid, it MUST respond with a REGACK message indicating the time period for which this registration is valid. If the provided credentials are not valid or the registrar cannot validate the credentials, the registrar MUST respond with a REGREJ message. If credentials are not provided, the registrar MUST respond with a REGAUTH message that indicates the available authentication methods. Registrants MUST implement this message and registrars MUST be able to process it. The following table specifies IEs for this message: Spencer, et al. Informational [Page 14] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 +------------+----------------+-------------+-------------+ | IE | Section | Status | Comments | +------------+----------------+-------------+-------------+ | Username | Section 8.6.6 | Required | | | | | | | | MD5 Result | Section 8.6.15 | Conditional | per REGAUTH | | | | | | | RSA Result | Section 8.6.16 | Conditional | per REGAUTH | | | | | | | Refresh | Section 8.6.18 | Optional | | +------------+----------------+-------------+-------------+ 6.1.3. REGAUTH Registration Authentication Response Message A REGAUTH is a response to a REGREQ or REGREL. It is sent when a registrar requires authentication to permit registration. A REGAUTH message MUST include the 'authentication methods' and 'username' IEs, and the 'MD5 challenge' or 'RSA challenge' IE if the authentication methods include MD5 or RSA. Upon receipt of a REGAUTH message, the registrant MUST resend the REGREQ or REGREL message with one of the requested credentials, if it has the specified credentials. Registrars MUST implement this message and registrants MUST be able to process it. The following table specifies IEs for this message: +--------------+----------------+-------------+---------------+ | IE | Section | Status | Comments | +--------------+----------------+-------------+---------------+ | Username | Section 8.6.6 | Required | | | | | | | | Auth Methods | Section 8.6.13 | Required | | | | | | | | Challenge | Section 8.6.14 | Conditional | If RSA or MD5 | +--------------+----------------+-------------+---------------+ 6.1.4. REGACK Registration Acknowledgment Message A REGACK is sent in response to a REGREQ. A REGACK typically includes the 'refresh' IE specifying the number of seconds before the registration will expire. If the 'refresh' IE is not included with a REGACK, a default registration expiration of 60 seconds MUST be assumed. A REGACK MAY also include the 'username' and 'apparent Spencer, et al. Informational [Page 15] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 address' IEs to indicate how the peer identifies the registrant. IEs related to caller identification or the time the registration occurred MAY be sent as well. Receipt of a REGACK message requires an ACK in response. Registrars MUST be able to send this message and registrants MUST be able to process it. The following table specifies IEs for this message: +------------------+----------------+----------+----------+ | IE | Section | Status | Comments | +------------------+----------------+----------+----------+ | Username | Section 8.6.6 | Required | | | | | | | | Date Time | Section 8.6.28 | Required | | | | | | | | Apparent Address | Section 8.6.17 | Required | | | | | | | | Message Count | Section 8.6.23 | Optional | | | | | | | | Calling Number | Section 8.6.2 | Optional | | | | | | | | Calling Name | Section 8.6.4 | Optional | | | | | | | | Refresh | Section 8.6.18 | Optional | | +------------------+----------------+----------+----------+ 6.1.5. REGREJ Registration Rejection Message A REGREJ indicates that a registration request has been rejected. This rejection can occur for several reasons. A REGREJ MUST include the 'causecode' and 'cause' IEs to specify why registration was rejected. Upon receipt of a REGREJ message, the registrant MUST consider registration process unsuccessful and no further interaction is required. A peer MAY reinitiate the process at later time accounting for potential configuration changes on the registrar or registrant. Both registrants and registrars MUST be capable of sending and processing this message. The following table specifies IEs for this message: Spencer, et al. Informational [Page 16] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 +------------+----------------+----------+----------+ | IE | Section | Status | Comments | +------------+----------------+----------+----------+ | Cause | Section 8.6.21 | Required | | | | | | | | Cause Code | Section 8.6.33 | Required | | +------------+----------------+----------+----------+ 6.1.6. REGREL Registration Release Request Message A REGREL is used by a registrant for a forced release of a prior registration. It MUST include the 'username' IE to identify the registrant to be released, and MAY include the 'causecode' and 'cause' IEs to specify why registration is being released. Upon receipt of this message, a peer MUST authenticate the sender using the provided credentials or send a REGAUTH message requesting them. If authenticated, it MUST immediately purge its registration of the specified registrant or send a REGREJ message if the registration is not found. Registrants SHOULD be capable of sending this message and registrars MUST be able to process it. The following table specifies IEs for this message: +----------+----------------+-------------+-------------------------+ | IE | Section | Status | Comments | +----------+----------------+-------------+-------------------------+ | Username | Section 8.6.6 | Required | | | | | | | | MD5 | Section 8.6.15 | Conditional | MD5 or RSA Result is | | Result | | | required | | | | | | | RSA | Section 8.6.16 | Conditional | | | Result | | | | | | | | | | Cause | Section 8.6.21 | Optional | | | | | | | | Cause | Section 8.6.33 | Optional | | | Code | | | | +----------+----------------+-------------+-------------------------+ Spencer, et al. Informational [Page 17] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 6.2. Call Leg Management +--------+ HANGUP/ack | | _____________|__ | | | | +--------->| Initial |<----+ | |________________|<---------------------+ | | ^ | start call | | | ---------- | | | send NEW | +-------+ | | | | | rec AUTHREQ | | _____V__V__ | ----------- | | | | | snd AUTHREP | +------------| Waiting |----+ | rec REJECT |___________|------------------------>+ ---------- | | ack | rec HANGUP | | --------- | | snd ack | | | rec ACCEPT | | ---------- | +------+ | snd ack | | | PROCEEDING / ack | _________V___V | RINGING / ack | | | | | | Linked |-----+ | |______________|------------------------>+ | rec HANGUP | rec ANSWER | ---------- | ----------- | snd ack | snd ack | | | | | rec HANGUP | _______V________ --------- | | | snd ack | | UP |--------------------->+ |________________|--------------------->+ finish ------ snd HANGUP Figure 2: Call Origination State Diagram Spencer, et al. Informational [Page 18] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 +--------+ rec HANGUP/ack | | _____________V__ | rec NEW(no Auth)/snd AUTHREQ | | | | Initial |-----+ rec NEW(not Auth)/snd REJECT | | |________________|<--------------------+ | | rec NEW | | (valid credentials)| | ---------- | +------+ | snd ACCEPT | | | snd PROCEEDING | _________V___V | snd RINGING | | | | | | Linked |-----+ | | | |______________|------------------------>+ | rec HANGUP | /answered | ---------- | ----------- | snd ack | snd ANSWER | | | rec HANGUP | _______V________ --------- | | | snd ack | | UP |--------------------->+ |________________|--------------------->+ finish ------ snd HANGUP Figure 3: Call Termination State Diagram 6.2.1. Overview The IAX protocol can be used to set up 'links' or 'call legs' between two peers for the purposes of placing a call. The process, illustrated in Figure 2 and Figure 3, starts when a peer sends a NEW message indicating the destination 'number' (or name) of a Called Party on the remote peer. The remote peer can respond with either a credentials challenge (AUTHREQ), a REJECT message, or an ACCEPT message. The AUTHREQ message indicates the permitted authentication schemes and SHOULD result in the sending of an AUTHREP message with the requested credentials. The REJECT message indicates the call cannot be established at this time. ACCEPT indicates that the call leg between these two peers is established and that higher-level call signaling (Section 6.3) MAY proceed. After sending or receiving the Spencer, et al. Informational [Page 19] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 ACCEPT message, the call leg is in the 'Linked' state and is used to pass call control messages until the call is completed. Further detail on messages used for this process can be found in Section 6.3. Call legs are labeled with a pair of identifiers. Each end of the call leg assigns the source or destination identifier during the call leg creation process. 6.2.2. NEW Request Message A NEW message is sent to initiate a call. It is the first call- specific message sent to initiate an actual media exchange between two peers. 'NEW' messages are unique compared to other Call Supervision messages in that they do not require a destination call identifier in their header. This absence is because the remote peer's source call identifier is not created until after receipt of this frame. Before sending a NEW message, the local IAX peer MUST assign a source call identifier that is not currently being used for another call. A time-stamp MUST also be assigned for the call, beginning at zero and incrementing by one each millisecond. Sequence numbers for a NEW message, described in the transport section, (Section 7) are both set to 0. A NEW message MUST include the 'version' IE, and it MUST be the first IE; the order of other IEs is unspecified. A NEW SHOULD generally include IEs to indicate routing on the remote peer, e.g., via the 'called number' IE or to indicate a peer partition or ruleset, the 'called context' IE. Caller identification and CODEC negotiation IEs MAY also be included. Upon receipt of a NEW message, the receiving peer examines the destination and MUST perform one of the following actions: Send a REJECT response, Challenge the caller with an AUTHREQ response, Accept the call using an ACCEPT message, or Abort the connection using a HANGUP message, although the REJECT message is preferred at this point in call. If the call is accepted, the peer MUST progress the call and further respond with one of PROCEEDING, RINGING, BUSY, or ANSWER depending on the status of the called party on the peer. See Section 6.3 for further details. The following table specifies IEs for the NEW message: Spencer, et al. Informational [Page 20] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 +--------------+----------------+-------------+---------------------+ | IE | Section | Status | Comments | +--------------+----------------+-------------+---------------------+ | Version | Section 8.6.10 | Required | | | | | | | | Called | Section 8.6.1 | Required | | | Number | | | | | | | | | | Auto Answer | Section 8.6.24 | Optional | | | | | | | | Codecs Prefs | Section 8.6.35 | Required | | | | | | | | Calling | Section 8.6.29 | Required | | | Presentation | | | | | | | | | | Calling | Section 8.6.2 | Optional | | | Number | | | | | | | | | | Calling TON | Section 8.6.30 | Required | | | | | | | | Calling TNS | Section 8.6.31 | Required | | | | | | | | Calling Name | Section 8.6.4 | Optional | | | | | | | | ANI | Section 8.6.3 | Optional | | | | | | | | Language | Section 8.6.9 | Optional | | | | | | | | DNID | Section 8.6.12 | Optional | | | | | | | | Called | Section 8.6.5 | Conditional | 'Default' assumed | | Context | | | if IE excluded | | | | | | | Username | Section 8.6.6 | Optional | | | | | | | | RSA Result | Section 8.6.16 | Conditional | If challenged with | | | | | RSA | | | | | | | MD5 Result | Section 8.6.15 | Conditional | If challenged with | | | | | MD5 | | | | | | | Format | Section 8.6.8 | Required | | | | | | | | Capability | Section 8.6.7 | Conditional | | | | | | | | ADSICPE | Section 8.6.11 | Optional | | | | | | | | Date Time | Section 8.6.28 | Optional | Suggested | Spencer, et al. Informational [Page 21] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 | | | | | | Encryption | Section 8.6.34 | Optional | | | | | | | | OSP Token | Section 8.6.42 | Optional | | +--------------+----------------+-------------+---------------------+ 6.2.3. ACCEPT Response Message An ACCEPT response is issued when a NEW message is received, and authentication has taken place (if required). It acknowledges receipt of a NEW message and indicates that the call leg has been set up on the terminating side, including assigning a CODEC. An ACCEPT message MUST include the 'format' IE to indicate its desired CODEC to the originating peer. The CODEC format MUST be one of the formats sent in the associated NEW command. Upon receipt of an ACCEPT, an ACK MUST be sent and the CODEC for the call MAY be configured using the 'format' IE from the received ACCEPT. The call then waits for an ANSWER, HANGUP, or other call control signal. (See Section 6.3.) If a subsequent ACCEPT message is received for a call that has already started, or has not sent a NEW message, the message MUST be ignored. The following table specifies IEs for this message: +--------+---------------+----------+----------+ | IE | Section | Status | Comments | +--------+---------------+----------+----------+ | Format | Section 8.6.8 | Required | | +--------+---------------+----------+----------+ 6.2.4. REJECT Response Message A REJECT response is sent to indicate that a NEW, AUTHREP, DIAL, or ACCEPT request has been denied. It MAY be due to an authentication failure, an invalid username, or if a peer cannot provide a valid password or response to an issued challenge. It MAY also be used to notify a peer of a call setup failure, e.g., when IAX peers cannot negotiate a CODEC to use. Upon receipt of a REJECT message, the call leg is destroyed and no further action is required. (Note: REJECT messages require an explicit ACK.) REJECT messages MAY include the 'causecode' and 'cause' IEs to indicate the rejection reason. The following table specifies IEs for this message: Spencer, et al. Informational [Page 22] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 +------------+----------------+----------+----------+ | IE | Section | Status | Comments | +------------+----------------+----------+----------+ | Cause | Section 8.6.21 | Optional | | | | | | | | Cause Code | Section 8.6.33 | Optional | | +------------+----------------+----------+----------+ 6.2.5. HANGUP Request Message A HANGUP message is sent by either peer and indicates a call tear- down. It MAY include the 'causecode' and 'cause' IEs to indicate the reason for terminating the call. Upon receipt of a HANGUP message, an IAX peer MUST immediately respond with an ACK, and then destroy the call leg at its end. After a HANGUP message has been received for a call leg, any messages received that reference that call leg (i.e., have the same source/destination call identifiers) MUST be answered with an INVAL message. This indicates that the received message is invalid because the call no longer exists. After sending a HANGUP message, the sender MUST destroy the call and respond to subsequent messages regarding this call with an INVAL message. The following table specifies IEs for this message: +------------+----------------+----------+----------+ | IE | Section | Status | Comments | +------------+----------------+----------+----------+ | Cause | Section 8.6.21 | Optional | | | | | | | | Cause Code | Section 8.6.33 | Optional | | +------------+----------------+----------+----------+ 6.2.6. AUTHREP Authentication Reply Message An AUTHREP MUST include the appropriate challenge response or password IE, and is only sent in response to an AUTHREQ. An AUTHREP requires a response of either an ACCEPT or a REJECT. Typical reasons for rejecting an AUTHREP include 'destination does not exist' and 'suitable bearer not found'. The following table specifies IEs for this message: Spencer, et al. Informational [Page 23] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 +------------+----------------+-------------+----------+ | IE | Section | Status | Comments | +------------+----------------+-------------+----------+ | RSA Result | Section 8.6.16 | Conditional | If RSA | | | | | | | MD5 Result | Section 8.6.15 | Conditional | If MD5 | +------------+----------------+-------------+----------+ 6.2.7. AUTHREQ Authentication Request Message The AUTHREQ message is sent in response to a NEW message if authentication is required for the call to be accepted. It MUST include the 'authentication methods' and 'username' IEs, and the 'challenge' IE if MD5 or RSA authentication is specified. Upon receiving an AUTHREQ message, the receiver MUST respond with an AUTHREP or HANGUP message. The following table specifies IEs for this message: +--------------+----------------+----------+----------+ | IE | Section | Status | Comments | +--------------+----------------+----------+----------+ | Username | Section 8.6.6 | Required | | | | | | | | Auth Methods | Section 8.6.13 | Required | | | | | | | | Challenge | Section 8.6.14 | Required | | +--------------+----------------+----------+----------+ 6.3. Call Control 6.3.1. Overview IAX's call control messages provide end-to-end signaling functions common to other telephony control protocols. The messages include RINGING, ANSWER, BUSY, and PROCEEDING. These messages MUST only be sent after an IAX call leg has been ACCEPTed. In response to an exchange starting with a NEW message, typically, the first call control message is RINGING; however, a PROCEEDING message MAY precede it or the call MAY proceed directly to the ANSWER message. If the call is answered, an ANSWER message will be sent. Other possibilities include a "BUSY" indication, or if the called party's service cannot be reached, the call will be torn down using the link-level HANGUP and an appropriate cause code. Spencer, et al. Informational [Page 24] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 If the link was started with a DIAL message, the sequence is an optional PROCEEDING, then optional RINGING, then ANSWER or BUSY. Of course, a link level HANGUP MAY occur at any time. Various private extensions to IAX Control messages have been deployed for passing application-specific data over the IAX control link. One such extension is an application that controls ham radio transceivers. An IAX peer that receives a control message that is not understood MUST respond with the UNSUPPORT message. The mandatory IAX control messages are explained below. 6.3.2. PROCEEDING Response Message The PROCEEDING message SHOULD be sent to a calling party when their call request is being processed by a further network element but has not yet reached the called party. Upon receipt of a PROCEEDING message, the peer SHOULD perform protocol-specific actions to indicate this fact to the calling party, e.g., tones, an ISUP (ISDN User Part) Proceeding message, etc. If the prior call leg is utilizing the IAX protocol, a PROCEEDING message MUST be sent to that peer. The processing of this message at an originating or transcoding peer is not specified; however, if possible, the status may be displayed to the calling party. The PROCEEDING message does not require any IEs. 6.3.3. RINGING Response Message This message is sent from a terminating party to indicate that the called party's service has processed the call request and is being alerted to the call. An IAX RINGING message MUST be sent to an IAX- based calling party when the peer determines that the called party is being alerted, e.g., when their phone is ringing. Upon receipt of an IAX RINGING message, the peer MUST pass this indication to the calling party, unless the calling party has already received such indication. For an initiating peer, this is typically done by starting the ring-back tone; however, many implementations start ring-back before ringing in order to meet user expectations. If the calling party is using the IAX protocol, a RINGING message MUST be passed to this caller. The RINGING message does not require any IEs. Spencer, et al. Informational [Page 25] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 6.3.4. ANSWER Response Message This message is sent from the called party to indicate that the party has accepted the call request and is communicating with the calling party. Upon receipt of this message, any ring-back or other progress tones MUST be terminated and the communications channel MUST be opened. The ANSWER message does not require any IEs. 6.4. Mid-Call Link Operations 6.4.1. FLASH Request Message The FLASH message is sent to indicate a mid-call feature. Its interpretation is system dependent and if it is not expected, it SHOULD be ignored. Typically, this message is only sent from analog telephone adapters when a brief circuit interruption is made during an answered call. The FLASH message does not require any IEs. 6.4.2. HOLD Request Message The HOLD message is sent to cause the remote system to stop transmitting audio on this channel, and optionally replace the audio with music or other sounds. If the remote system cannot perform this request, it SHOULD be ignored. The HOLD message SHOULD only be sent in IAX calls that are started using the DIAL message. The HOLD message does not require any IEs. 6.4.3. UNHOLD Request Message The UNHOLD message is sent to cause the remote system to resume transmitting audio on this channel. If the remote system cannot perform this request, it SHOULD be ignored. The UNHOLD message SHOULD only be sent in IAX calls after the HOLD message. The UNHOLD message does not require any IEs. Spencer, et al. Informational [Page 26] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 6.4.4. QUELCH Request Message The QUELCH message is sent to cause the remote peer to squelch or stop transmitting audio on this channel. It MAY replace the audio sent to the further party with music or other sounds. If the remote system cannot perform this request, it SHOULD be ignored. The QUELCH message MUST only be sent in IAX calls after an ACCEPT is sent or received; it SHOULD only be used on calls that are started using the NEW message. The QUELCH message does not require any IEs. 6.4.5. UNQUELCH Request Message The UNQUELCH message is sent to cause the remote system to resume transmitting audio on this channel. If it previously replaced the audio with music or other sounds, it MUST discontinue it immediately. If the remote system cannot perform this request, it SHOULD be ignored. The UNQUELCH message SHOULD only be sent in IAX calls after the QUELCH message. The UNQUELCH message does not require any IEs. 6.4.6. TRANSFER Request Message The TRANSFER message causes the receiving peer to restart the call using another specified number. The receiving peer MUST be on the calling side of this call leg and the new call behavior is unspecified. After processing this message, a HANGUP message SHOULD be sent and the call leg torn down. When sending a TRANSFER message, the new number to which the call is being transferred MUST be included in the CALLED_NUMBER IE and a CALLED_CONTEXT IE MAY be included. The call leg MUST NOT be used for anything else and MAY be torn down. The following table specifies IEs for this message: Spencer, et al. Informational [Page 27] RFC 5456 IAX: Inter-Asterisk eXchange Version 2 February 2010 +-----------+---------------+----------+----------------------------+ | IE | Section | Status | Comments | +-----------+---------------+----------+----------------------------+ | Called | Section 8.6.1 | Required | | | Number | | | | | | | | | | Called | Section 8.6.5 | Optional | Use this IE if context is | | Context | | | other than default. | +-----------+--