RFC 5456
IAX: Inter-Asterisk eXchange Version 2
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".
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.)
________________ | | | 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
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:
+------------+----------------+-------------+-------------+
| 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
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:
+------------+----------------+----------+----------+
| 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 | | | |
+----------+----------------+-------------+-------------------------+
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
+--------+ 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 Diagram6.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
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:
+--------------+----------------+-------------+---------------------+ | 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 |
| | | | | | 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:
+------------+----------------+----------+----------+
| 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:
+------------+----------------+-------------+----------+
| 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.
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.
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.
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:
+-----------+---------------+----------+----------------------------+ | 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. | +-----------+---------------+----------+----------------------------+6.5. Call Path Optimization
If a peer is handling a call between two other IAX peers and the peer no longer has any need to monitor the progress, content, or duration of the call, it MAY remove itself from the call by directing the other two peers to communicate directly. This call path optimization, or "supervised transfer", is done in a manner that ensures the call will not be lost in the process; the initiating peer does not give up control of the process until it has confirmed the other two peers are communicating. Note: the parties involved in the call are not aware of this operation; it is purely a network operation.
________________ rec TXREJ | | rec TXREL ---------- *--------->| None |<-----------------+ snd TXREJ |________________| ack ^ to other | | | | V | | | | * (From All) | /Init Transfer | | rec TXREQ | ------------ | | --------- | snd TXREQ | | snd TXCNT | to both | | | _v___________v__ | | | | | Begin |----------------->+ |________________| | | | | rec TXACC | | rec TXREADY | --------- | | --------- | snd TXREADY | | x | | | | _v___________v__ | | |----------------->+ ----------| Ready |---------- | | |________________| | | | | | | /Both Legs Ready| /Both Legs Ready| rec TXMEDIA| | and not media-only| and media-only | | | ------------ | ------------ | -----------| | snd TXREL | snd TXMEDIA | x | | | | | | ____V____ _____V___ ___V_____ | | | | | | | | | Release | | Media | | Media | | |_________| |_________| | Pass | | | |_________| | | | | V V | rec TXCNT +------------------------->+ ---------- (In any state) snd TXACC Figure 4: Call Path Optimization State Diagram
When a peer initiates this procedure, both call legs MUST be in the UP state, i.e., they MUST have sent or received the ACCEPT message for that call leg. To start, it sends a TXREQ message with the addresses and information from the other remote peers to each its neighbors. If capable of performing this procedure, they begin transmitting all channel information to both the initiating peer and the new remote peer. They also send a TXCNT message indicating packet counts for the call leg to the new remote peer. Each TXCNT message is acknowledged with a TXACC message. The peers respond by sending a TXREADY message to the initiator indicating that they have confirmed the new communications path. When all remote peers have sent the initiator a TXREADY message, the transfer is successful and the initiator responds with a TXREL and has finished its involvement with the call. If during the transfer process, the two remote peers cannot communicate, they send a TXREJ message to the initiator. An example is shown in Section 9.5. These messages are described in the sections that follow.6.5.1. TXREQ Transfer Request Message
The TXREQ message is sent by a peer to initiate the transfer process. When sent, it MUST be sent to both adjacent peers involved in the call. It MUST include the following Information Elements: +------------------+----------------+----------+----------+ | IE | Section | Status | Comments | +------------------+----------------+----------+----------+ | Apparent Address | Section 8.6.17 | Required | | | | | | | | Call Number | Section 8.6.20 | Required | | | | | | | | Transfer ID | Section 8.6.26 | Required | | +------------------+----------------+----------+----------+ The Apparent Address is the IP address data structure address for the other remote peer. The Call Number IE is the callid used by the other remote peer and the Transfer ID is a unique number assigned by the initiator. Upon receipt of a TXREQ message for a valid call from the corresponding remote peer, a peer MUST respond by attempting to communicate with the newly specified remote peer. This task is accomplished by sending a TXCNT message directly to the peer at the address specified in the Apparent Address parameter.
6.5.2. TXCNT Transfer Connectivity Response Message
The TXCNT message is used to verify connectivity with a potential replacement peer for a call. It MUST include the TRANSFERID IE. Upon receipt on a message of this type, and if the peer has previously received a TXREQ for this call leg, the peer MUST respond with a TXACC message. If the TXCNT message is not successfully transmitted or if a TXACC message is not received in response to it, the transfer process MUST be aborted by sending a TXREJ message to the initiating host. It MUST include the following Information Element: +----------+----------------+----------+----------------------------+ | IE | Section | Status | Comments | +----------+----------------+----------+----------------------------+ | Transfer | Section 8.6.26 | Required | A unique number assigned | | ID | | | by the initiator. | +----------+----------------+----------+----------------------------+6.5.3. TXACC Response Message
Like the TXCNT message, the TXACC message is used to verify connectivity with a potential replacement peer. It MUST include the TRANSFERID IE. Upon receipt on a message of this type if the peer is attempting to transfer this call leg, the peer stops sending call- related media to the initiating peer and sends a TXREADY message to it. It MUST include the following Information Element: +----------+----------------+----------+----------------------------+ | IE | Section | Status | Comments | +----------+----------------+----------+----------------------------+ | Transfer | Section 8.6.26 | Required | A unique number assigned | | ID | | | by the initiator. | +----------+----------------+----------+----------------------------+6.5.4. TXREADY Transfer Ready Response Message
The TXREADY message indicates that the sending peer has verified connectivity with the peer which it was instructed to transfer the call. It MUST include the TRANSFERID IE. When TXREADY messages are received from both remote peers, it MUST discontinue media transport and send a TXREL message to each peer. It MUST include the following Information Element:
+----------+----------------+----------+----------------------------+ | IE | Section | Status | Comments | +----------+----------------+----------+----------------------------+ | Transfer | Section 8.6.26 | Required | A unique number assigned | | ID | | | by the initiator. | +----------+----------------+----------+----------------------------+6.5.5. TXREL Transfer Release Response Message
The TXREL message indicates that the transfer process has successfully completed. After sending and upon receipt of this message, no further interaction (other than an ACK, of course) is needed between the peers on this call leg. The TXREL is also used to revert a split-media call (one where the media and signaling follow different paths) to a call where the media and signaling follow the same path. It MUST include the following Information Element: +-------------+----------------+----------+----------+ | IE | Section | Status | Comments | +-------------+----------------+----------+----------+ | Call Number | Section 8.6.20 | Required | | +-------------+----------------+----------+----------+6.5.6. TXMEDIA Transfer Media Message
The TXREL message indicates that the MEDIA transfer process has successfully completed. After sending and upon processing of this message, Full Frames MUST continue to follow the original signaling path and media frames MUST follow the newly negotiated path. This split-path process continues until the call ends with a HANGUP or peer receives a TXREL message for the call leg. A peer MAY force the paths to rejoin by sending a TXREL message. It MUST include the following Information Element: +-------------+----------------+----------+----------+ | IE | Section | Status | Comments | +-------------+----------------+----------+----------+ | Call Number | Section 8.6.20 | Required | | +-------------+----------------+----------+----------+
6.5.7. TXREJ Transfer Rejection Response Message
The TXREJ MAY be sent at anytime during the transfer process to indicate that the transfer cannot proceed. Upon receiving a TXREJ message, if the receiver is the initiating peer, it MUST form a TXREJ message and send it to the other remote peer. The TXREJ message does not require any IEs.6.6. Call Tear Down
The messages used to finish a call vary depending on the particular process the call is in at the time. The terminal messages for a call are: HANGUP. See Section 6.2.5. REJECT. See Section 6.2.4. TRANSFER. See Section 6.4.6. TXREADY. See Section 6.5.4. These messages are discussed in their respective sections. Also, if the reliable transport procedures determine that messaging cannot be maintained, the call leg MUST be torn down without any other indications over the errant IAX call leg.6.7. Network Monitoring
The IAX protocol has various tools to determine the network load. It uses the POKE message to monitor reachability of remote peer and the LAGRQ message to measure the quality of a current call leg including the jitter buffer delay.6.7.1. POKE Request Message
A POKE message is sent to test connectivity of a remote IAX peer. It is similar to a PING message, except that it MUST be sent when there is no existing call to the remote endpoint. It MAY also be used to "qualify" a user to a remote peer, so that the remote peer can maintain awareness of the state of the user. A POKE MUST have 0 as its destination call number. Upon receiving a POKE message, the peer MUST respond with a PONG message. This message does not require any IEs.
6.7.2. PING Request Message
A PING message is sent to test connectivity of the remote IAX endpoint on an existing call. Transmission of a PING MAY occur when a peer-defined number of seconds have passed without receiving an incoming media frame on a call, or by default every 20 seconds. Receipt of a PING requires an acknowledging PONG be sent. This message does not require any IEs.6.7.3. PONG Response Message
A PONG message is a response to a PING or a POKE. It acknowledges the connection. The receiver uses the time-stamp of the received PING or POKE and its times to determine the Round Trip Time of the connection. Several receiver report IEs MAY be included with a PONG, including received jitter, received frames, delay, and dropped frames. Receipt of a PONG requires an ACK. This message does not require any IEs.6.7.4. LAGRQ Lag Request Message
A LAGRQ is a lag request. It is sent to determine the lag between two IAX endpoints, including the amount of time used to process a frame through a jitter buffer (if any). It requires a clock-based time-stamp, and MUST be answered with a LAGRP, which MUST echo the LAGRQ's time-stamp. The lag between the two peers can be computed on the peer sending the LAGRQ by comparing the time-stamp of the LAGRQ and the time the LAGRP was received. This message does not require any IEs.6.7.5. LAGRP Lag Response Message
A LAGRP is a lag reply, sent in response to a LAGRQ message. It MUST send the same time-stamp it received in the LAGRQ after passing the received frame through any jitter buffer the peer has configured. This message does not require any IEs.6.8. Digit Dialing
Digit Dialing support is an optional portion of the IAX protocol designed to support devices that do not maintain their own dial plans, for instance, analog telephone adapters, or ATAs. The dialing portion of the IAX protocol MAY be implemented for the client/ phone-side, server-side or not all. The exchanges work as a series
of Dialing Plan requests (DPREQs) each followed by a response (DPREP) indicating if additional digits SHOULD be collected before sending the call. The sections that follow describe these messages and the rules associated with them.6.8.1. DPREQ Dial Plan Request Message
A DPREQ is a request for the server to analyze the passed called number and determine if there is a valid dialing pattern on the remote peer. It MUST include the 'called number' IE to specify what extension is being queried. This command is used in the case where a local peer does not handle its own dialplan/extension switching. The local peer can inquire (as a user dials) how the remote peer perceives the 'called number'. If a DPREP is received indicating that the number is valid, a DIAL MAY be sent. This message MAY be sent by the client and MUST be implemented on servers which provide IAX dialing support. It MUST include the following Information Element: +-------------+----------------+----------+----------+ | IE | Section | Status | Comments | +-------------+----------------+----------+----------+ | Call Number | Section 8.6.20 | Required | | +-------------+----------------+----------+----------+6.8.2. DPREP Dial Plan Response Message
A DPREP is a reply to a DPREQ, containing the status of the dialplan entry requested in the 'called number' IE of the DPREQ. It MUST include the 'called number', 'dpstatus', and 'refresh' IEs. The called number is the same one received in the 'called number' IE of the DPREQ. The 'dpstatus' IE contains the status of the dialplan entry referenced by the received called number. The status indicates whether the called number exists, can exist, needs more digits, or is invalid. More information can be found in Section 8.6 under the DPSTATUS information element. The 'refresh' IE specifies the number of minutes the 'dpstatus' is valid. If the 'refresh' IE is not present, a default 10 minutes period is assumed. The sending of this message MUST be implemented by servers which support IAX dialing. Clients which support IAX dialing MUST be capable of receiving such messages. It MUST include the following Information Elements:
+----------+----------------+----------+----------------------------+ | IE | Section | Status | Comments | +----------+----------------+----------+----------------------------+ | Call | Section 8.6.20 | Required | | | Number | | | | | | | | | | Dial | Section 8.6.20 | Required | Indicates if number | | Plan | | | exists, is a partial | | Status | | | match, etc. | | | | | | | Dial | Section 8.6.20 | Optional | Inclusion is strongly | | Plan | | | suggested. The default is | | Refresh | | | 10 minutes. | +----------+----------------+----------+----------------------------+6.8.3. DIAL Request Message
The DIAL message is used with IAX peers that do not maintain their own dialplan/extension routing. Once an extension is validated by one or more DPREQ/DPREP exchanges, the number MAY be dialed in a DIAL message, using the 'called number' IE to specify the extension it is attempting to reach. The remote peer then handles the remaining aspects of call setup, including ringing the extension and notifying the local peer when it has been answered following the same requirements as the NEW command (Section 6.2.2). The following table specifies the IEs used by this message: +-----------+---------------+----------+----------------------------+ | 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. | +-----------+---------------+----------+----------------------------+6.9. Miscellaneous
6.9.1. ACK: Acknowledgement Message
An ACK acknowledges the receipt of an IAX message. An ACK is sent upon receipt of a Full Frame that does not have any other protocol- defined response. An ACK MUST have both a source call number and destination call number. It MUST also not change the sequence number
counters, and MUST return the same time-stamp it received. This time-stamp allows the originating peer to determine to which message the ACK is responding. Receipt of an ACK requires no action. An ACK MAY also be sent as an initial acknowledgment of an IAX message that requires some other protocol-defined message acknowledgment, as long as the required message is also sent within some peer-defined amount of time. This allows the acknowledging peer to delay transmission of the proper IAX message, which may add security against brute-force password attacks during authentication exchanges. When the following messages are received, an ACK MUST be sent in return: NEW, HANGUP, REJECT, ACCEPT, PONG, AUTHREP, REGREL, REGACK, REGREJ, TXREL. ACKs SHOULD not be expected by any peer and their purpose is purely to force the transport layer to be up to date. The ACK message does not requires any IEs.6.9.2. INVAL: Invalid Response Message
An INVAL is sent as a response to a received message that is not valid. This occurs when an IAX peer sends a message on a call after the remote peer has hung up its end. Upon receipt of an INVAL, a peer MUST destroy its side of a call. The INVAL message does not requires any IEs.6.9.3. VNAK: Voice Negative Acknowledgement Message
A VNAK is sent when a message is received out of order, particularly when a Mini Frame is received before the first full voice frame on a call. It is a request for retransmission of dropped messages. A message is considered out of sequence if the received iseqno is different than the expected iseqno. On receipt of a VNAK, a peer MUST retransmit all frames with a higher sequence number than the VNAK message's iseqno. The VNAK message does not requires any IEs.6.9.4. MWI: Message Waiting Indicator Request Message
An MWI message is used to indicate to a remote peer that it has one or more messages waiting. It MAY include the 'msgcount' IE to specify how many messages are waiting. The following table specifies IEs used by this message:
+----------+----------------+----------+-----------+
| IE | Section | Status | Comments |
+----------+----------------+----------+-----------+
| MSGCOUNT | Section 8.6.23 | Optional | Suggested |
+----------+----------------+----------+-----------+
6.9.5. UNSUPPORT Unsupported Response Message
An UNSUPPORT message is sent in response to a message that is not
supported by an IAX peer. This occurs when an IAX command with an
unrecognized or unsupported subclass is received. No action is
required upon receipt of this message, though the peer SHOULD be
aware that the message referred to in the optionally included 'IAX
unknown' IE is not supported by the remote peer.
The following table specifies IEs used by this message:
+---------+----------------+----------+-----------+
| IE | Section | Status | Comments |
+---------+----------------+----------+-----------+
| UNKNOWN | Section 8.6.22 | Optional | Suggested |
+---------+----------------+----------+-----------+
6.10. Media Messages
The IAX protocol supports many types of media and these are
transported through the same UDP port as other IAX messages. Voice
and video are unique in that they utilize two different encodings,
each with different support procedures. Abbreviated 'Mini Frames'
are normally used for audio and video; however, each time the time-
stamp is a multiple of 32,768 (0x8000 hex), a standard or 'Full
Frame' MUST be sent. This approach facilitates efficiency and
reliability by sending compressed packets, without guaranteed
delivery, most of the time while periodically forcing reliable
exchanges with the peer. If communication fails, call tear-down
procedures are invoked.
Upon receiving any media message, except the abbreviated audio and
video Mini Frames, an ACK message MUST be sent. The content SHOULD
be passed to an associated application, device, or call leg. The
data MAY be buffered before it is presented to the user.
6.10.1. DTMF Media Message
The message carries a single digit of DTMF (Dual Tone Multi-
Frequency). Useful background information about DTMF can be found in
[RFC4733] and [RFC4734], but, note that IAX does not use the RTP
protocol.
6.10.2. Voice Media Message
The message carries voice data and indicates the CODEC used.6.10.3. Video Media Message
The frame carries video data and indicates the video format of the data.6.10.4. Text Media Message
The frame carries a text message in UTF-8 [RFC3629] format.6.10.5. Image Media Message
This message carries a single image. The image MUST fit in one message in this version of the protocol.6.10.6. HTML Media Message
The HTML message class carries HTML and related data as well as status about the display of that HTML page. The subclass parameter indicates the HTML content type. It MAY be a URL, the start, middle, or end of a data block. HTML data MUST be in the format described in [html401]. If a peer receives an HTML message for a channel that does not support HTML, it MUST respond with an HTML message that has the HTML NOT SUPPORTED indication. When a device that supports HTML completes loading the page, it SHOULD send a LOAD COMPLETE message6.10.7. Comfort Noise Media Message
This message indicates that comfort noise SHOULD be played. It has a parameter that indicates the level. The noise is to be locally generated.
(page 39 continued on part 3)
