ASL3 Web Transceiver IAX2 protocol (end to end)¶

This page documents the full call flow an astar-lib client uses to place a Web Transceiver (WT) call into an AllStarLink (ASL3) node, as proven live against the public parrot/echo node 55553 (104.232.32.242:4569). It covers three stages: out-of-band portal auth, the IAX2 call setup, and the media + teardown rules.

The IAX2 mechanics are standard RFC 5456 except where called out; everything in the "Web Transceiver auth" stage is an AllStarLink layer with no RFC basis.

Stage 1 — Web Transceiver authentication (out of band)¶

ASL3 gates Web Transceiver guests behind a portal-minted token. The IAX2 credentials themselves are the shared guest allstar-public / allstar; the per-user identity is carried by the token in the CALLING_NAME IE and validated by the node's dialplan, not by the IAX2 AUTHREP.

Minting the token¶

The <applet> params:

user=allstar-public  pass=allstar  host=<node IAX ip:port>
callingNo=<node>     callingName=<TOKEN>     callSign=<callsign>

Scrape the callingName value — that opaque hex string is the token. It is callsign-bound and works for any destination node (in testing it was minted via node 77777 and used to reach 55553). The token is session-tied; mint a fresh one per connect.

The node-side gate (dialplan)¶

The guest call lands in the node's [allstar-public] dialplan context, which CURLs the auth helper with the CALLING_NAME (the token):

... CURL(https://.../authwebphone.pl?<CALLING_NAME>) -> RESP
  RESP == "OHYES<callsign>"  -> proceed (connect to the node, run Rpt())
  RESP == "???" (or not "OHYES...") -> Answer; Wait(1); Hangup   (cause 16)

authwebphone.pl resolves the token back to its bound callsign. A valid token yields OHYES<callsign> and the call proceeds; anything else yields the Answer; Wait(1); Hangup path — which is why an un-gated call appears to "answer" and then drops exactly ~1 second later with cause 16. That 1-second drop is the dialplan's Wait(1), not a protocol timeout.

Stage 2 — IAX2 call setup¶

This is mostly standard IAX2 (RFC 5456 §6, §8) plus ASL3's CALLTOKEN-with-dest_call=0 requirement and the WT IE set.

sequenceDiagram
    participant C as astar-lib
    participant N as ASL3 node
    C->>N: NEW  (IE: CALLTOKEN = empty)
    N->>C: CALLTOKEN  (opaque token)
    C->>N: NEW  (dest_call=0, CALLTOKEN echoed, WT IEs)
    N->>C: AUTHREQ  (auth methods, CHALLENGE)
    C->>N: AUTHREP  (MD5 = md5(challenge + "allstar"))
    N->>C: ACCEPT  (format)
    N->>C: CONTROL RINGING
    N->>C: CONTROL ANSWER

CALLTOKEN exchange¶

1. Send a NEW carrying only an empty CALLTOKEN IE (no other IEs needed yet). This is the RFC 5456 §6.7 / §8.6.x anti-spoofing call-token challenge.
2. The peer replies with a CALLTOKEN frame containing an opaque token.
3. Resend the NEW echoing that token back, now carrying the full WT IE set.

The resent NEW IE set (Web Transceiver shape)¶

Authentication¶

ASL3 replies with AUTHREQ carrying a challenge. Compute the response as standard IAX2 MD5 auth (RFC 5456 §8.6.13):

AUTHREP md5 = MD5( challenge_string + "allstar" )

"allstar" is the shared guest secret (paired with username allstar-public). The per-user AllStar account password is consumed entirely by the Stage-1 portal/token step — it is not used in the IAX2 AUTHREP. On success the node sends ACCEPT, then CONTROL RINGING and CONTROL ANSWER.

Stage 3 — Media¶

Once answered, audio is carried by IAX2 Voice frames. The keying behavior (how the node decides you are "transmitting") is described on the app_rpt TEXT commands page — for a WT caller the node is in RADIO_KEY_NOT_ALLOWED mode, so your voice frames key the link.

First frame must be a full Voice frame¶

sequenceDiagram
    participant C as astar-lib
    participant N as ASL3 node
    Note over C: t = 0 (after ANSWER)
    C->>N: FULL Voice (codec=ulaw, ts=32-bit)
    C->>N: mini Voice (ts low-16)
    C->>N: mini Voice (ts low-16)
    Note over C: high-16 ts rolls (~65 s) OR codec change
    C->>N: FULL Voice (re-establish context)
    C->>N: mini Voice ...

Keepalives¶

chan_iax2 drives the keepalives on its own schedule (self-rescheduling); the peer does not need to PING you:

• PING roughly every ~21 s
• LAGRQ roughly every ~10 s

These are standard IAX2 reliability frames (RFC 5456 §8.4 PING/PONG, §8.4 LAGRQ/LAGRP). A WT client should answer them but need not initiate beyond its own reliability needs.

Teardown — hangup cause¶

When the node tears the call down it sends a HANGUP carrying a CAUSE IE (RFC 5456 §8.6.x cause codes). For example CAUSE = 16 is Normal Clearing (the same code the Answer; Wait(1); Hangup reject path uses). A client should surface this cause rather than flatten it to a generic abort — e.g. "remote hung up (normal clearing)" — so the operator can distinguish a clean disconnect from the WT-gate reject.

Where ASL3 diverges from / layers on plain IAX2¶

Confidence and provenance¶

• Wire-confirmed against parrot 55553 (live captures, 2026-06-10): the CALLTOKEN→resent-NEW→AUTHREQ→AUTHREP→ACCEPT→RINGING→ANSWER sequence; the dest_call=0 REJECT (reproduced by flipping 0→1); the first-frame-full / VNAK-storm behavior; the 1 s Wait(1) reject vs the held-open valid-token call; HANGUP cause 16.
• Reverse-engineered from app sources (DroidStar iax.cpp / obtain_asl_wt_creds; app_rpt dialplan [allstar-public]): the portal login + token-mint flow and the authwebphone.pl OHYES/??? gate.
• Standard IAX2 (RFC 5456): frame types, MD5 auth, full/mini Voice frames, PING/LAGRQ, CAUSE IE.

The portal scrape is unofficial and fragile. The token-mint flow depends on AllStarLink's portal markup and may break without notice.