Google TV

Google TV Pairing Protocol

This document discusses how to use the Google TV Pairing Protocol to establish the identities of client devices and servers that use the Anymote Protocol to communicate with each other. In particular, client applications that communicate with Google TV need to use the Anymote Protocol and the Google TV Pairing Protocol.

The Google TV Pairing Protocol can be used to conduct pairing sessions between clients and servers on a local network, for example between a mobile phone and Google TV. In the pairing process, the client contacts the server, and the server issues a challenge for the client to complete. This usually involves the server showing a code of some kind, and the client echoing that code back to the server. For example, in the case of Google TV, the server might show an alphanumeric code for the user to enter on the client device's keyboard

To establish a proper challenge, the client must send the types of challenges it can accept to the server. For example, if the client has a Qwerty keyboard but no camera, it can respond to alphanumeric challenges but not to bar code challenges. When the server receives the types of supported challenges, it creates the challenge and asks the client to respond.

The Google TV Pairing Protocol was previously known unofficially as the polo protocol. We mention this because the protocol definition file is named polo.proto.

Source Code and Message Definitions for the Google TV Pairing Protocol

For the source code for the Google TV Pairing Protocol, see http://code.google.com/p/google-tv-pairing-protocol/. Both Java and C++ implementations of the Pairing protocol are available.

For the message definitions, see polo.proto.

Message Sequence

A pairing protocol session takes place in a short-lived SSL connection.  A client sends a sequence of messages to the server.  Each message calls for a specific acknowledgment from the server.  The logic of the protocol does not branch.

The message sequence is:

  • The client sends the server a PairingRequest message to initiate the pairing process.
  • The server responds with a PairingRequetAck.
  • The client sends its options for handling challenges (the kinds of challenges it can handle).
  • The server sends its options for handling challenges (the kinds of challenges it can issue and the kind of response input it can receive).
  • The client sends configuration details for the challenge in a Config message.
  • The server responds with a ConfigAck.
  • The server and client exchange a secret.
    • the server issues an appropriate challenge. For example, the server display a code.
    • the user responds to it. For example, the user echoes the code back.
  • When the user had responded to the challenge, the client checks the response and if it is correct, sends a Secret message.
  • The server checks the response, and if it is correct, sends a SecretAck.

The message sequence is illustrated in the diagram below.

In theory, any device could have the capability to issue a challenge or to respond to the challenge. In practical terms, Google TV issues the challenge, and the mobile device responds to the challenge. For communicating with Google TV, the client needs to establish a pairing session on the next, consecutive port of the server. The client should set up the pairing session for 4 digit hexadecimal encoding.

Message format

All messages in the protocol consist of two parts:

  • An "outer" message, which encapsulates all messages exchanged on the wire and contains common header fields.
  • An inner "payload", which is sub-message of one of the 8 currently defined protocol messages.

The outer message contains two required fields, and two semi-optional fields. The required fields are:

  • protocol_version -- An integer that describes the version of the protocol being spoken.  This may be useful for backwards compatibility if the protocol is extended. The current version is "1".

  • status -- An integer value representing the status of the protocol. A status code of "OK" (value 200) implies that the previous message (if any) was accepted, and that the next message in the protocol may be sent.  Any other value indicates that the sender has experienced a fault, which should cause the session to terminate.

The two remaining fields are semi-optional: they are required when status is "OK", but optional (and ignored/undefined) otherwise. They are:

  • type -- If the status code is "OK", then this value must contain the integer type number which describes the payload.
  • payload -- If the status code is "OK", then this value must contain the encapsulated message whose type matches `type`.

The following diagram illustrates the complete set of messages involved in the protocol, and their relationship to the outer message:

 

Message Definitions

For the definitions of the messages in the Google TV Pairing Protocol, see polo.proto on code.google.com.

Wire Format

The reference implementation for the Google TV Pairing Protocol provides various methods of serializing the protocol messages ("Wire Adapter"). However, Google TV implements the protocol buffer wire format. Consequently, applications that pair with Google TV must use the protocol buffer wire format too.

Streaming Format

Messages between client and server are sent across a TCP channel established by the client to the server.  Since the length of many messages is variable, messages are streamed by first prepending a simple header.  For a single message, the data sent over the wire is:

  • a 4-byte unisgned integer (in network byte order) indicating the length of the payload
  • the serialized message (message type OuterMessage).

Challenge Encoding

In a pairing session between two devices, the exact methods for generating and responding to challenges are determined dynamically, based on the capabilities and preferences of both devices.  For example, the challenge issuer may be able to receive the response as a bar code, but it may need to accept alphanumeric input when it pairs with a device that can't display bar codes.

The possible encodings for challenges are:

  • QRCODE — 2-dimensional barcode, containing binary bitstream
  • ALPHANUMERIC — text message composed of characters [0-9A-Za-z]+
  • HEXADECIMAL — text message composed of characters [0-9A-Fa-f]+
  • NUMERIC — text message composed of characters [0-9]

During the initialization of the pairing session, each device lists:

  • what roles it can play (can it issue or respond to challenges or can it do both?)
  • what types of challenge encodings it can handle for each role it can play

If a device can issue challenges and also respond to them, then it must provide a separate list of supported encoding types for each role (challenge issuer and responder). If the device does not support a role, it must not provide encoding types for that role. For example, a device with no display can only have a responder role because it cannot display the details of a challenge.

This document assumes that the client plays the role of challenge responder, and the server (Google TV) plays the role of challenge issuer.

Role Negotiation

During the initialization of the pairing session, the devices need to determine their respective roles:

  • one device will be the challenge issuer (the one displaying the challenge)
  • the other will be the responder (the one responding to the challenge).

The list below gives a relative ordering of encoding schemes, in ascending order of user effort needed per bit:

In general, the device that initiates the connection should take priority as the challenge responder, since most protocols have some form of user interaction on the initiating side.

INPUT_ENCODINGS

For each supported method of responding to a challenge, the device should list the encoding along with the number of symbols it can handle in the challenge message. In other words, INPUT_ENCODINGS are a sequence of 2-tuples, with each tuple listing an encoder and the number of symbols that will be generated.

For example:

 INPUT_ENCODINGS = [
   (HEXADECIMAL, 8),
   (HEXADECIMAL, 4),
   (ALPHANUMERIC, 4),
 ]

OUTPUT_ENCODINGS

For each supported method of displaying the challenge message, the device should list the encoding along with the number of symbols that will be in the challenge message.

Encoding Reference

QRCODE

This challenge message is a 2-dimensional QR-format barcode.

The QR Code format supports several encoding methods. This encoding of the challenge hash uses the binary encoding method of QR Code.

Generate the QRCode with the N least significant bits of the bitstream.

Devices should negotiate QR code size and error correction level.

For more information about the QR code format see:

ALPHANUMERIC

This challenge message is an N-symbol message, each character representing 5 bits of hash.

The following set of 32 symbols is used:

[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]

That is [A-Z0-9], removing the characters [I1O0] to reduce the set to 32 characters (and avoiding symbols that could be hard to differentiate visually).

The translation table is:

  b'00000 = 'A'
  b'00001 = 'B'
  ...
  b'11111 = '9'

To encode a bitstring as an ALPHANUMERIC encoding of N symbols, take successive groups of 5 bits starting with the LSB. (If N%5 != 0, then the remaining bits should be treated as 0).

When receiving symbols to decode, an input node should ignore the case of the letters.

HEXADECIMAL

The challenge message is an N-symbol hexadecimal stream, each symbol representing 4 bits of hash.

The following set of 16 symbols is used:

[0-9A-F]

The translation table is

  b'0000 = '0'
  b'0001 = '1'
  ...
  b'1111 = 'F'

To encode the bitstring as a HEXADECIMAL encoding of N symbols, take successive groups of 4 bits starting with the LSB and apply the translation function. (If N%4 != 0, then remaining bits should be treated as 0.)

When receiving symbols to decode, an input node should ignore the case of the letters.

NUMERIC

The challenge message is an N-digit number, each digit representing 3 bits of hash.

The following set of 8 symbols is used:    

[01234567]

The translation table is:

 
b'000' = '0'
b'001' = '1'
...
b'111' = '7'

To encode a bitstring as a NUMERIC encoding of N symbols, take successive groups of 3 bits starting with the LSB. (If N%3 != 0, then remaining bits should be treated as 0).

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.