CloudServices/Notifications/Bipostal

Project is in Cold Storage

This project was frozen on Apr. 03 2012. No further work is being done on this project at this time.

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 several components to BIPostal. ppymilter2
A tweaked version of ppymilter that uses gevent instead of asyncore
https://github.com/jrconlin/ppymilter2

bipostal_store
A common library for data management between various BiPostal services.
https://github.com/jrconlin/bipostal_store

BIPostal Dash
An API & Dashboard service which creates and manages aliases.
https://wiki.mozilla.org/Services/Notifications/Bipostal/API

BIPostal
a pair of PostFix plugins:
https://github.com/mozilla-services/bipostal

BIPostmap
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.

Data Schema

While only really appropriate for the Mysql_Memcache model, the following schema presents how data can be stored.

User

user - string(255) - user id primary key
email - string(255) - preferred email address (may be different than user.
metainfo - Text - Unindexed, optional JSON data associated with the user (mostly used by the UI)

Alias

alias - string(255) - Alias for a user
email - string(255) - email to send to
user - string(255) - user ID associated with this record
origin - string(190) - optional alias origin (site registered to use this alias)
created - Integer - UTC Timestamp of alias creation
status - Enum('active','inactive','deleted') - Alias status
metainfo - Text - Optional additional information associated with this alias

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. Unless otherwise specified, all calls use two legged OAuth. The OAuth key/secret are returned from the Login BrowserID assertion post (See POST '/').

Calls will return HTTP error response codes for invalid requests. Listed returns presume a 200 response code.

POST /

Log a user into the service and create a server side session association.

Arguments {'assertion': 'BrowserID Assertion',
           'audience': 'origin of the request'}

(As appropriate for auth method)
Returns: {'consumer_key': 'Session based OAuth Consumer Key',
          'shared_secret': 'Session based OAuth Shared Secret',
          'access_token': 'Session based MAC access token',
          'mac_key': 'Session based MAC secret key',
          'refresh_token': 'Post expiration refresh token',
          'mac_algorithm': '(mac-sha-1 | mac-sha-256)',
          'expires_in': Seconds until token expires,
          'server_time': Server time in UTC seconds
           }

GET /new_alias

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

Arguments: {}

Returns: JSON complient string containing the new token

GET /alias/

Return list of known aliases for a logged in user.

Arguments: {}

Returns: {'email': 'main email for user',
          'aliases': [{'alias': 'alias string',
                       'email': 'associated email',
                       'origin': 'requesting domain audience',
                       'status': '(active | inactive)'
                      },
                      ...]
         }

POST /alias/

Add an alias to a logged in user's record

Arguments: {'alias': 'alias to use',
            'audience': 'remote request origin'} 

Returns: {'alias': 'alias string',
          'email': 'associated email',
          'origin': 'requesting domain audience',
          'status': '(active | inactive)'
         }

GET /alias/{alias}

Get detailed information for a logged in user's alias

Arguments: {'audience': 'Optional origin'}

Returns: {'alias': 'alias string',
          'email': 'associated email',
          'origin': 'requesting domain audience',
          'status': '(active | inactive)'
         }

DELETE /alias/{alias}

Delete an alias associated with the logged in user.

Arguments: {'audience': 'Optional origin'}

Returns: {'alias': 'alias string',
          'email': 'associated email',
          'origin': 'requesting domain audience',
          'status': 'deleted'
         }

PUT /alias/{alias}

Change the status of a logged in user's alias

Arguments: {'status': '(active | inactive)'}

Returns: {'alias': 'alias string',
          'email': 'associated email',
          'origin': 'requesting domain audience',
          'status': 'deleted'
         }            

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 (Postfix plugins)

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@

Test Framework

Security and Privacy

Points of Contact

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

Issues and Resolutions

Operations

Points of Contact

Deployment Architecture

Bugzilla Tracking # -

Escalation Paths

Lifespan Support Plans

Logging and Metrics

Points of Contact

Tracking Element Definitions

Data Retention Plans

Dashboard URL

Customer Support

Points of Contact

Sumo Tags

Review Meeting