Overview

Firefox Native Verified Email Client (fVEC) Identity Engineering plan.

This document addresses the build portions of the Firefox Native Verified Email Client

Top level tracking bug is 664541

Key People

Technical Lead:	David Dahl
Additional Developers:	Rob Miller , JR Conlin
Project Manager:	Dan Mills
Product Manager:	Dan Mills
UX:	TBD

Work Items

Firefox Verified Email Client (fVEC)

Design Docs

Assigned to:	ddahl
Bug:	TBD
Assumes/Depends On:	Completed protocol specifications
Working Estimate:	2 days Best case: 1 day Worst case: 3 days Most Likely: 2 days

Design Diagram

Browser level API

Assigned to:	ddahl
Bug:	664614
Assumes/Depends On:
Working Estimate:	3 days Best case: 2 days Worst case: 5 days Most Likely: 3 days

the following Crypto API needs estimate by bsmith

Platform Crypto API

Assigned to:	bsmith, ddahl
Bug:	665057
Assumes/Depends On:
Working Estimate:	3 Best case: 1 day Worst case: 7 days Most Likely: 3 days

Crypto API

A (platform, chrome-privileged) crypto API that performs key pair generation, signature and verification will be needed
This API should be threadsafe and usable from a ChromeWorker - https://bugzilla.mozilla.org/show_bug.cgi?id=665057
Proposed IDL:

  
interface IdentityCryptoAPI {
  AString GenerateKeyPair(in AString aPassphrase); 
  AString GetPublicKey(in AString aOrigin);
  AString Sign(in AString aPlaintext);
  boolean Verify(in AString aPlainText, in AString aSignature, in AString aPublicKey); 
};

Places DB Table + integration

Assigned to:	ddahl
Bug:	bug 667451
Assumes/Depends On:	Estimate available after consult with Marco
Working Estimate:	TBD Best case: TBD Worst case: TBD Most Likely: TBD

Database table, integration with Places

Create a SQLite database - or use Places.sqlite to track email identity per site with a pubKey and cert per site

+----------------------------------------------------------------+
|identity_pub_key                                                |       
|----------------------------------------------------------------|       
|id                                                              |       
|email                                                           |       
|email_relying_party_fqdn                                        |       
|pub_key                                                         |       
|ctime                                                           |       
|mtime                                                           |       
|relying_party_fqdn                                              |       
|certificate                                                     |
|refresh_url                                                     | 
|error_url                                                       |       
+----------------------------------------------------------------+

If we use the places db - just add another table - this will have existing APIs for handling private browsing and history data truncation

Browser API

The window.navigator.id object will have the following properties

getVerifiedEmail()
Query the database for an existing ID for the RP.
- ID Found: generate an Identity assertion (IA, which is a JWT) - call the callback with the IA.
- No ID found for site: prompt user to use other existing ID:
  - display Window with list of verified emails to use
  - choose email address
  - generate keypair
  - update the database with site, email, keypair, etc
  - call Identity Authority email registration XHR(email, pubKey)
  - IA processes the email and key, creates a cert and send an email to user to fetch the certificate via clicking on a link, etc
- No IDs at all: prompt user to create an ID for logging into the browser and sites that support MozID
  - Display window, collect username (email), password, continue
  - Validate input, check server for free username or email
  - (Need to link to the HTTP API for this operation)
  - complete ID server account setup
  - (Question: does this operation also set up a Sync account?)
  - continue with "No ID found for site"
registerVerifiedEmail()
- The IA calls this when a user visits the IA site to verify an email address
  - the callback is called after a keypair is generated and the email and pubKey are passed to the callback
  - The IA must process this request, send an email to the requestor to confirm the email is valid
registerVerifiedEmailCertificate()
- The IA sent an email to the requestor, which contains a link to a url where the IA can call registerVerifiedEmailCertificate() - passing in the certificate generated server-side and the updateURL.
- The certificate is saved into the database along with the updateURL and errorURL.
- Firefox displays a notification to tell the user about the completed verified email process for site x.
- The browser has now fully registered a verified email 'identity' for use with the site.

Certificate refresh

Certs will expire, and require refresh
- (Question: when do we poll for an update? only right before use? also once weekly or monthly?)
- Firefox calls an XHR with the updateURL in the database
  - a 200 response means we generate a keypair and call the IA registration XHR(email, pubKey)
  - an Error response invokes a UI to tell the user that the ID cannot be used and needs refresh
    - A new tab is opened and the IA's errorURL saved during certificate registration is opened

e10s consideration

Need to study the e10s bugs and progress and factor in the additional hoops required for calling callbacks in content from chrome code
- bug 666713 - Dynamic analysis of chrome->content operations in Firefox
- https://wiki.mozilla.org/Electrolysis/Short-Term_Goals#Dynamic_Instrumentation_for_Chrome.2FContent_Interaction
- more links to follow

Identity Registration

Assigned to:	ddahl
Bug:	664748
Assumes/Depends On:
Working Estimate:	3 days Best case: 2 days Worst case: 7 days Most Likely: 3 days

Identity Assertion Generation

Assigned to:	ddahl
Bug:	664750
Assumes/Depends On:
Working Estimate:	2 days Best case: 1 days Worst case: 5 days Most Likely: 2 days

Certificate Refresh

Assigned to:	ddahl
Bug:	664751
Assumes/Depends On:
Working Estimate:	2 days Best case: 1 day Worst case: 5 days Most Likely: 2 days

JW* encoding and decoding

Assigned to:	ddahl
Bug:	668648
Assumes/Depends On:
Working Estimate:	2 days Best case: 1 day Worst case: 4 days Most Likely: 2 days

UI (front-end, 'login to browser')

Assigned to:	ddahl
Bug:	664754
Assumes/Depends On:	comprehensive mockups from UX
Working Estimate:	12 days Best case: 8 days Worst case: 15 days Most Likely: 12 days

Login to Browser UI/UX

need updated mockups
UI work items
- URLBar login button: updates via 'login to browser', tab switch/ url load/ content JS API calls
- Login to browser screen, login failure screen
- Create Firefox account screen
  - Error condition screen
    - Validate input feedback
  - Success screen
- Create verified email screen
  - Error condition screen
    - Validate input feedback
  - Success screen
- Chose a Verified Email as default 'Identity'

External Dependencies

Code Review

Assigned to:	ddahl
Bug:	TBD
Assumes/Depends On:	Browser peer is giving regular (weekly or 2X monthly feedback on patches)
Working Estimate:	12 days Best case: 10 days Worst case: 15 days Most Likely: 12 days

Security Review

Assigned to:	ddahl
Bug:	TBD
Assumes/Depends On:	Scheduling with InfraSec
Working Estimate:	1 day Best case: 1 day Worst case: 2 days Most Likely: 1 day

Questions from ddahl

Apparently, there is a need for 2 methods to verify email addresses...
- A web-only API that uses the navigator.id object exclusively
- A XHR API for talking to the Mozilla IA via the Firefox client to verify email

Private Browsing support

How should this work?
- 1. any IDs created during PB are removed on exit
- 2. IDs cannot be created during PB

Site-specific prefs UI: how does ID impact that? Do we need UI mockups, further specs, etc?

Login/Logout of the browser.
- Do we lock the browser like it is an OS?
- What do users type to 'login'? username (email) + password? What username is it? ID username, Sync username

Timeline

Expected Completion

Working Estimate: 34 days (rough est. - more mockups and discussions around the crypto API, places integration needed)

Milestones

Milestone 1: Complete browser window.navigator.id object plus Platform Crypto API

The client library requires browser resources as well as a new platform crypto API in order to function. At this milestone, the browser components are ready to use.

Associated Bugs: 664614, 664752, 665057
Working Estimate: 6 days (needs crypto API estimate)
Completion Date: TBD

Milestone 2: Complete Identity functions

At this milestone, the library is capable of receiving certificates and generating assertions.

Associated Bugs: 664748, 664750
Working Estimate: 15 days
Completion Date: TBD

Milestone 3: Process Identity Certificate Refreshes

At this milestone, the library should be able to detect an expired certificate, request a new certificate from the ID server, and be able to generate new Identity Assertions from that certificate.

Associated Bug: 664751
Working Estimate: 4 days
Completion Date: TBD

Milestone 4: UI Finalized

At this milestone, the user interface elements should be complete. NOTE: This will require working with UX and UI, which may impact deliverable date.

Associated Bug: 664754
Working Estimate: 8 days
Completion Date: TBD

Milestone 5: Wrapup

The client needs to have full test cases working, documentation, and packaged for deployment and testing. At this milestone, the client will be in a beta consumer ready state. Documentation may not be finalized, but they should be at a point where an external user can use the system with no prior knowledge of the system and minimal assistance.

Associated Bugs:(§3.1.11, §3.1.12)
Working Estimate: 14 days
Completion Date: TBD

Identity/EngPlan/fVEC

Contents