Privacy/Reviews/Push API

Document Overview

Feature/Product:	Push API
Projected Feature Freeze Date:	8 Sept 2012
Product Champions:	Fernando Rodriguez
Privacy Champions:
Security Contact:	Paul Theriault
Document State:	[DONE] dropped protocol to be changed

Timeline:

Architectural Overview:	29 August
Recommendation Meeting:	(date TBD)
Review Complete ETA:	dropped

Architecture

Main goal of the feature is to allow a Web App to receive notifications via a push mechanism. The proposed architecture is that a Carrier provides a Notification Server, which stores and forwards all the messages to the client Web App on behalf of the Web App's Application Server.

Normal flow of actions
(see linked document above for further detail)

1. User powers on the handset
2. App that wants a PUSH API calls the PushAPI
3. App asks gecko to listen to push messages
4. Gecko if not previously connected, registers itself as a UA with notification server
5. Gecko registers the Web App, (token and public key)
6. Notification server stores this information in database, and generates a url to send back to UA.
7. Gecko send url to Web App
8. Web App sends url to App server
9. When app wants to push, the app server sends a post to the URL provided

See design document below.

The main objective of this feature/product is:

Design Documents: https://www.dropbox.com/s/xa3gqxyd7ycpw0y/Push%20notification%20server%20APIs.docx https://bugzilla.mozilla.org/show_bug.cgi?id=776501

Components

The Push API involves the following components:

• Web App (WA)
• Gecko (User Agent or UA)
• Notification Server - carrier (NS)
• Application Server - developer (AS)

Web App

The Web App will call a registration function with a token (WAToken) and public key (pbk) to register itself as wanting to listen for Push notifications. Both of these values come from the application server. A proposed extension is to add a feature where gecko creates a large securely random value for your app, which case the Web App would then need to send the WAToken to the Application Server instead of the other way around.

Stored Data:

What	Where
WAToken (random token string)	Web App determined (likely indexedDB or other storage available to the Web App
Public Key (base64 encoded string)	Web App determined (likely indexedDB or other storage available to the Web App

Communication with Gecko

Direction	Message	Data	Notes
Out:	Register	Send WAToken and Public Key to Gecko, so that gecko can then register for the Push Notifications
IN:	Resulting URL to publish push notifications to.	Publish URL

Communication with Application Server The communication between Web App and Application server is proprietary, and completely in the control of the developer.However, in the normal use case, the Web App would be expected to recieve the WAToken and Public Key values in some manner, and also the Web App must send the publication URL back to the server so that

Gecko

Gecko is responsible for registering the device with the notification server, and then registering all the applications that have requested to receive notifications, and returning the publication url to the Web App.

Stored Data:

What	Where
User Agent Token (UAToken)	IndexedDB (ua-registration)
WA Registrations (WATokens, url)	IndexedDB (wa-registration)

Communication with Web App

Direction	Message	Data	Notes
Out:	Response to registration request	URL if request was successful, or error message if not.
	Push Notification Event	Event information, including data from Application Server
IN:	Registration request	WAToken and Public Key to register to listen for push notications

Communication with Notification Server This API is divided on two interfaces, a HTTP GET one only used to recover valid cryptographic tokens (to be used as a UAToken) and another one using a WebSocket for the rest of stuff.

Direction	Message	Data	Notes
Out:	Request AU Token	HTTPs request to the notification server for a new UAToken
	Register UA	Sends back a UAToken that was previously retrieved from the Notification Server
	Register WA	Send the WATOken and public key to notification server, so that it can be registered
	getAllMessages	Retrieve all messages for a specific UA
	ACK
IN:	Registration request	WAToken and Public Key to register to listen for push notications

Notification Server

Stored Data:

What	Where
WA Registrations	UA Token, WAToken & Public Key triples which correspond to a registration from a single app instance.
UA Registrations	Registrations of UAToken corresponding to

Communication with Gecko See the Gecko section above.

Communication with Third Party Application Server

Direction	Message	Data	Notes
Out:	Response to message request	Data
IN:	Notify	Message from the AS is sent to the url provided when registering. Signed with private key corresponding to stored public key
	Revoke (TBD, proposed only)	Public

Application Server

The application server is the website that wants to publish push notifications to a client. To use the Push API the application server will need to store WAToken, URL and a Public & Private Key Pair. All storage and communication is under the control of the developer.

User Data Risk Minimization

In this section, the privacy champion will identify areas of user data risk and recommendations for minimizing the risk.

Alignment with Privacy Operating Principles

In this section, the privacy champion will identify how the feature lines up with Mozilla's privacy operating principles.

See Also: Privacy/Roadmap_2011#Operating_Principles:

Principle: Transparency / No Surprises

Will the user be prompted if an application requests Push Notifications? Can the user delete existing WATokens? How long are WATokens stored?

Recommendations: (what can be improved)

• Prompt the user when an application (first?) registers for push applications.
• Clear WATokens when a user "clears application data" or deletes the application

Principle: Real Choice

Recommendations:

• A user should be able to opt-out of push notifications (either on a per-app or global basis)

Principle: Sensible Defaults

Recommendations:

• We should encrypt notifications so that the network and notification server can't intercept them.

Principle: Limited Data

Recommendations:

Follow-up Tasks and tracking

What	Who	Bug	Details
[NEW] Initial Overview Discussion	?		Meeting time TBD