Signaling Protocol

The RedPhone signaling protocol is very similar to a RESTful HTTP API, where every request yields a corresponding response, and authentication is done through an Authorization header.

Like SIP, however, both endpoints are simultaneously server and client, issuing requests and responses to each-other. You can browse the code for the available RedPhone signals.

Basic Signal Format

RedPhone's basic signal format resembles a HTTP REST API:

<verb> <resource> HTTP/1.0\r\n
Authorization: [Basic|OTP] <authorization_string>\r\n
Content-Length: <length>\r\n
\r\n
<content>

Responses also resemble HTTP:

HTTP/1.0 <response_code> <response_string>\r\n
Content-Length: <length>\r\n
\r\n
<content>

The RedPhone signaling protocol differs from HTTP in the following ways:

1. The addition of new HTTP verbs, beyond GET, PUT, and DELETE.
2. The addition of a new Authorization type, OTP.
3. That both ends of a signaling connection act as both client and server, each receiving requests and issuing responses.

OTP Authorization Format

The OTP Authorization type is a mechanism for transmitting HOTP-formatted credentials. The basic format is:

Authorization: OTP Base64Encoded(<phone_number>:<HOTP_credential>:<counter>)

1. <phone_number> is the identifying number the device registered with.
2. <HOTP_credential> is Hmac-SHA1(authentication_key, counter)
3. <authentication_key> is an 144bit random key created by the client at registration time.
4. <counter> is a monotonically incrementing counter. The server will not accept a counter value <= a value it has already seen.

Standard Call Signals

Initiate

1. Description: Sent by an initiator client who wishes to establish a call with a responder
2. Verb: GET
3. Resource: /session/<responder_number>

Response Codes:

1. 404: No such user, the specified responder number isn't registered with RedPhone.
2. 401: Authentication failed.
3. 200: Initiate successful.

Response body (application/json encoded):

{
  "relayPort" : <port> // The UDP port for this session allocated on the relay server.
  "sessionId" : <sessionId> // The session ID allocated for this session.
  "serverName" : <name> // The name of the relay server.
}

Ringing

1. Description: Sent by a responder to indicate that it received an initiate signal, and that it is currently ringing.
2. Verb: RING
3. Resource: /session/<session_id>

Response Codes:

1. 404: No such session, or stale session.
2. 401: Authentication failed.
3. 200: Relayed.

Busy

1. Description: Sent by a responder to indicate that it received an initiate signal, but that it is not able to ring (typically another call is in progress).
2. Verb: BUSY
3. Resource: /session/<session_id>

Response Codes:

1. 404: No such session, or stale session.
2. 401: Authentication failed.
3. 200: Relayed.

Hangup

1. Description: Sent by an initiator or responder to indicate that they are terminating the call.
2. Verb: DELETE
3. Resource: /session/<session_id>

Response Codes:

1. 404: No such session, or stale session.
2. 401: Authentication failed.
3. 200: Relayed.

Compressed Signaling Protocol

The initiate signal is transmitted to a responder via SMS, C2DM, or GCM. These are compact transports with limited space, and require special formatting to account for these size restrictions.

When transmitted over such transports, the initiate signal is encoded using protobuf. You can view the source for the protobuf IDL here.

This signal is also encrypted, of course, which is documented separately.