Privacy/Reviews/Push API
Contents
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)
- User powers on the handset
- App that wants a PUSH API calls the PushAPI
- App asks gecko to listen to push messages
- Gecko if not previously connected, registers itself as a UA with notification server
- Gecko registers the Web App, (token and public key)
- Notification server stores this information in database, and generates a url to send back to UA.
- Gecko send url to Web App
- Web App sends url to App server
- 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 |
