Session Creation
The authenticator has two request types: first time and subsequent authentication.
First Time Authentication
First time requests require the device to send in the application developer key generated by Yahoo! Connected TV. Before a response is sent back to the remote device, the consumer must enter a four digit security code.
Syntax
SESSION|CREATE|<application_key>|<device_name>|END
Parameters
The <application_key> is the application developer key issued to developers by Yahoo! Connected TV to validate the remote device application.
This application developer key is validated by Yahoo! Connected TV and can be revoked for malicious applications. See the
Creating an Application Key section above.
The <device_name> is a human-readable
remote device name and is used for the security code dialog on the connected TV display.
Example
No previous successful connections have been made. The remote device initiates a connection. An untrusted SSL handshake is completed.
Device Request: SESSION|CONFIG|0.1|END
Device Request: SESSION|CREATE|12345-6789-1011|Jim's Awesome Phone|END
A dialog containing a four digit security code is displayed on the connected TV asking the consumer if he or she wants to connect to the Engine running on the connected TV. In order to prevent man-in-the middle attacks, the consumer must enter this four digit security code into the remote device, which creates a signature and sends it back to the Engine.
Signature Formula
The signature formula which secures the connection between the device and the Engine is a hash-based message authentication code (HMAC) using the cryptographic hash function SHA-1. The HMAC-SHA1 signature is created using the security code and the SSL Client Certificate received in the SSL handshake.
signature = HMAC-SHA1(<consumer_inputed_code>, <entire_client_certificate>)
Syntax
SESSION|AUTH|<signature>|END
Parameters
The <signature> parameter is the HMAC-SHA1 signature generated from the security code and the SSL Client Certificate.
Example
- No previous successful connections have been made. The remote device initiates a connection. An untrusted SSL handshake is
completed.
- Device Request:
SESSION|CONFIG|0.1|END - Device Request:
SESSION|CREATE|12345-6789-1011|Jim's Awesome Phone|END
- Device Request:
- The device displays an Onscreen Keyboard (OSK).
- The TV displays a dialog with a four digit code.
- The consumer enters the four digit code into the remote device OSK.
- The device generates a signature.
- Device Request:
SESSION|AUTH|jd87h0u3n2309r8fhefhe9ugh0i0fg|END
- Device Request:
- Until the session is granted, any other messages sent by the remote device are considered a protocol violation.
The Engine validates the signature and grants the session returning an instance ID to identify the application on the remote
device. As long
as the instance ID remains valid, the remote device may connect to the Engine. After the session is granted, messages can
be freely sent and received.
- Engine Response:
SESSION|GRANTED|1234567|END
- Engine Response:
- If the device had generated an incorrect signature, the Engine sends an error record with an Invalid Signature
message.
- Engine Response:
ERROR|003|Invalid Signature|END
- Engine Response:
- The TV displays a dialog with a new four digit code and continues from step 3 above.
Subsequent Authentication
After the remote device had been allowed access by the consumer, no further dialogs are required for the session. If the remote device is disconnected, the session can be reset at any time using the instance ID stored on the remote device.
Syntax
SESSION|RESET|<instance_id>|END
Parameters
The <instance_id> parameter is the unique instance
ID of the application on the remote device.
Example
- The remote device application already has an instance ID. The remote device initiates a connection. An untrusted SSL handshake
is completed.
- Device Request:
SESSION|CONFIG|0.1|END - Device Request:
SESSION|RESET|1234567|END
- Device Request:
- Until the session is granted, any other messages sent by the remote device are considered a protocol violation.
The Engine grants the session returning the instance ID that identifies the application on the remote device. As long
as the instance ID remains valid, the remote device may connect to the Engine. After the session is granted, messages can
be freely sent and received.
- Engine Response:
SESSION|GRANTED|1234567|END
- Engine Response:
Authentication Response
Assuming authentication has completed successfully, the Engine will respond with an acknowledgement.
Syntax
SESSION|GRANTED|<instance_id>|END
Parameters
The <instance_id>
parameter is the unique instance ID of the application on the remote device.
Error Codes
If the authentication has failed, the possible error messages include:
ERROR|001|Invalid Application Key|END
ERROR|002|Invalid Instance ID|END
ERROR|003|Invalid Signature|END
ERROR|101|Unknown Message Type|END
Status Request
A remote device makes a status request to know if access is still granted. Before sending a RESET command, first check to see if the instance ID is still valid. If access is allowed, the session can be reset without an error. If access is denied, the session needs to be re-authenticated.
Syntax
SESSION|STATUS|<instance_id>|END
Parameters
The <instance_id> parameter is the unique instance ID of the application on the remote device.
Status Response
The Engine responds with allowed if
access is still granted and the given instance ID is valid and denied otherwise.
Syntax
SESSION|STATUS|<allowed|denied>|END
Parameters
The allowed or denied parameter is returned from the Engine to indicate if the previously passed instance ID is valid.
Revoking Authentication
The Profile app’s settings sidebar provides an interface for the consumer to revoke authentication of mobile device applications. Resetting the Engine to factory settings will also revoke all existing authentications.
When authentication has been revoked by the consumer, the possible error messages include:
ERROR|002|Invalid Instance ID |END