CloudServices/Notifications/Bipostal
Contents
- 1 Project is in Cold Storage
- 2 ProjectName
- 3 Overview
- 4 Design
- 5 QA
- 6 Security and Privacy
- 7 Operations
- 8 Logging and Metrics
- 9 Customer Support
Project is in Cold Storage
ProjectName
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.</br>
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==