CloudServices/Notifications/Bipostal

Overview

BrowserID Postal (BIPostal) provides a semi-anonymous method for BrowerID consumers to safely communicate and control communcations with third parties (e.g. webapp providers).

In later efforts, it will be a mechanism for older sites to provide notification content to users via an email attachment.

Project Contacts

Principal Point of Contact - jr conlin jrconlin@

IRC - #identity

Group Email - TBD

Goals

Some users may be uncomfortable providing their real, correlatable email address to a particular site. BiPostal allows users to have an email address auto-generated for them that still allows remote sites to contact them directly.

BIPostal provides the hooks and framework to allow that sort of function.

Use Cases

A Customer wishes to purchase a WebApp. The user does not wish to share their current master email with WebApp, so a proxy email address (nToken@host.tld) is automatically created and provided to WebApp. WebApp then wishes to notify Customer, so WebApp sends the email to nToken@host.tld. Host processes the notification, blocking notification if Customer has disabled that Token, or stripping non-text content and wrapping the notification for delivery to the registered Customer email.

In addition, Host may also submit the notification content to the Push Notification system for eventual display on Customers Push Notification enabled devices.

Requirements

• Host service shall accept BrowserID assertions as valid credentials for Customers
• Host service shall provide a unique token (nToken) that may be used to represent the Customer
  • Token shall have a minimum of 256 bits of entropy
  • Token shall only use characters 0-9, a-z (due to MTA restrictions)
• Host service shall associate an nToken with a Customer Email address
  • Email address shall consist of an nToken (as a valid RFC5322 local part) in conjunction with the recipient host name.
• Host service shall allow users to manage IDs associated with their email address
  • Users can "disable" (Make temporarily unavailable) or "delete" (permanently disable) an id.
  • Only "active" tokens shall be allowed to forward to the user.
  • The host system will attempt to re-assign a previously "disabled" ID for a user for a specific audience site (e.g. if the user had previously registered "123abc" for "example.com", a subsequent registration to "example.com" will re-activate the "123abc" nToken)
  • nTokens that the user has marked as "deleted" shall be retained for the legal minimum period required by law.

BrowserID has had a long standing request for an email redirect service. The service would accept mail addressed with an email safe, significant token as the local component, and redirect email to the principle registered email address of the user. Put far more clearly:

• A User logs into Site with BrowserID as "Bob@example.com"
• BrowserID then identifies User to Site as "a0b2c3@browserid.org"
• Site, wishing to send notifications to User, may now email "a0b2c3@browserid.org", which will then forward the message to "Bob@example.com"
• BrowserID adds a header/footer to the outbound message
• User may disable or drop "a0b2c3" from receiving mail at some time in the future if Site is overly chatty or that email address has been compromised.

Get Involved

Currently the code is still under development. Please see the Code Repositories.

Design

Points of Contact

Engineer - jr conlin jrconlin@

API Reference/Documentation

There are two components to BIPostal. BIPostal Dash is the API Dashboard service which creates and manages aliases.

https://wiki.mozilla.org/Services/Notifications/Bipostal/API

BIPostal is the other aspect, and is a pair of PostFix plugins.

BIPostmap is an address mapping plugin that uses standard Postfix name mapping protocols. See http://www.postfix.org/ADDRESS_REWRITING_README.html for details.

BIPostal_milter is a standard Postfix Milter which modifies the message (stripping extra content, adding headers and in the future, pulling JSON formed objects out for transmission to the Notifications PUSH platform). See http://www.postfix.org/MILTER_README.html for details.

Platform Requirements

This package was authored for Linux based systems. It was originally constructed for the Ubuntu distribution, and has been modified for use under Red Hat Enterprise.

Libraries Required

The following system level libraries and packages are required and should be installed at the system level. Repository names are taken from Ubuntu/Debian distributions.

General

• python-dev
• memcached & mysql-client (note, the package may require access to a mysql server)
• redis (An optional, alternate storage method)
• libmysqlclient-dev
• nginx

BIPostal Dash

curl3 libcurl3-gnutls

Code Repository

Stable - BIPostal_store - Common data storage packages - http://github.com/jrconlin/bipostal_store BIPostal - Postfix Plugins - http://github.com/mozilla-services/bipostal BIPostal_dash - Dashboard / API for BIPostal - http://github.com/jrconlin/bipostal_dash

Devel - See "dev" branches of above.

Release Schedule

Test/Staging - Q4 2011 Public - Q1 2012

QA

Points of Contact

services-qa@

Security and Privacy

Questionnaire Answers

1.1 Goal of Feature

This feature provides a semi-anonymous email address to users of BrowserID. Users are granted a randomly generated, 64 character, alphanumeric "string of crap"@browserid.org which acts as a site specific email address. Sites may then email the user at that alias. We reformat the email (currently wrap it with a TBD header/footer and strip non-text content) and send it to the user.

User has control over the email and can 'deactivate' it, rendering the email as invalid.

The project uses a combination of nginx and python (for the API support elements), Memcache and MySQL (for data storage), and Postfix milters for mail processing. API support and storage were determined after discussions with Operations as well as a desire to use consistent code elements. Likewise the Postfix milter allowed the minimal set of code to be created on top of a stable, well supported architecture than can be updated independently of the work done.

(See surrounding document for detailed Use Cases, rationale, etc.)

2. Potential Threat Vectors and Mitigation Points

1. Address resolution: Since this is designed around email, attackers could generate random 64character email addresses to attempt to scattergun spam.

We are working with an external provider (SocketLabs) to provide an initial filter for incoming email. They would provide DKIM filtering and known site blacklisting. This should restrict the potential attack sources. In addition, the very large namespace should prevent successful hits.

2. Alias injection/manipulation: Alias generation and control is handled via a simple REST API, credentialed by a BrowserID token.

The API uses a combination of 2legged OAuth 1.0 with the temporary token exchange occurring as part of the BrowserID authorization response. These tokens are session based and runs across https. This should minimize sniffing and simple XSS.

Review Status

Bugzilla Tracking # - see https://wiki.mozilla.org/Security/Reviews

Operations

Deployment Architecture

Bugzilla Tracking # -

Customer Support

Review Meeting

BiPostal API

The BiPostal system uses REST-like API calls to perform most of the work. Some of the API entry points have legacy names and may change

GET /0.5/new_token

Returns a new, mail local-part safe hash based on a 256bit random number

Arguments: {}

Returns: JSON complient string containing the new token

POST /0.5/user_queue

Creates returns the user's queue, creating if necessary.

Arguments: 'Credentials'

   Credentials are determined by the backend-auth mechanism used.
   For basic Auth they consist of the username and password.
   For browserId they consist of the assertion in the 'password'
   field with no 'username' required.

   Resolved User_id may be stored in beaker as 'uid' to bypass 
   credential check.
 
Returns: {'queue_id': token,
          'host': Submission host name,
          'port': Server access port}

   'queue_id' is the user's queue token. This id should be valid across 
   log-in credentials (e.g. if a user has "bob@example.com" and 
   "bjones@example.com", this ID would be consistent.

   'host' is the host URL to use for queue submission.

   'port' is the host PORT to use for queue submission.

POST /0.5/new_subscription

Create a new subscription for the user. Note: if this is a re-subsciption, the previous subscription value is returned.

Arguments: Request containing:
   'credentials' (see user_queue)
   'token' SMTP local-part compliant token. Either created from /new_token
       or generated by another source.
   'origin' site+tld (to be used to qualify token.)

POST /0.5/remove_subscription

Deactivate a subscription

Arguments: Request containing:
   'credentials' (see user_queue)
   'token' Subscription token to deactivate