Official Firefox Browser Extension
Switch branches/tags
Nothing to show
Pull request Compare This branch is 192 commits behind privly:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
chrome/content
defaults/preferences
locale/en-US
skin
.gitignore
.package_ignore
MIT-LICENSE
README.textile
chrome.manifest
install.rdf
package.sh

README.textile

The Privly Protocol

This document details the proof-of-concept (0.1) and working draft (1.0) versions of the Privly protocol— a method for sharing private content via third-party websites without granting content access to the host page.

Version 0.1 establishes the sharing backbone of the Privly system. It facilitates the private sharing of information, but not the secure sharing of information. Version 1.0 outlines the future development of the system with functionality for client-side cryptography. The principal contribution of Privly to date is a method for injecting content into any website. This is how we want to build on that success.

This draft was prepared a while back and does not have all the sharing concepts we wish to implement, and all of the concepts need rigorous review and specification. This document is in a public repository so anyone can make it better, make your criticism known through improvement or tagging the threats to the sharing model in the document.

Preliminaries

The “magic” in this system is on the browser side. Version 0.1 is implemented on the Privly content server and the reference browser extension. If you are developing an extension for the Privly system, version 0.1 is a good place to start. It will continue to be supported in subsequent versions.

Version 0.1

The Privly content server is built on a Rails application and follows RESTful principles unless otherwise noted. We assume a familiarity with RESTful principles in this document.

Authentication

Authentication in a distributed setting needs reworking. This section is targeting a single web application install.

Reading protected content and posting content to the server requires a user account, and user accounts are identified by appending all extension requests with an authentication token, “?auth_token=”. The content server authenticates using the Rails gem Devise. This page contains two forms that will return new authentication tokens for extensions. You can adapt these forms for your extension. Please note that generating a new token will invalidate your old token.

Content Parameters

All Privly content in 0.1 is in the posts endpoint. New posts expect the following parameters:

  • auth_token
    • See “Authentication” above. This ties the content to a user account.
  • public
    • an optional boolean value indicating whether the content should be public by default.
  • content

After the content is posted to the server you will be redirected to the show action for the content. The show action sets a header “privlyurl,” which contains the url of the post.

Display URLs

After the page load event Privly extensions perform the following actions:

  1. Convert all plaintext priv.ly links to anchor tags.
  2. Correct link indirection by replacing the href element of anchor tags with the proper Privly URL. For an example, look at what Twitter does to their links.
  3. Replace the content with an iframe for that content:

frame_id is an optional parameter that is attached to an event, IframeResizeEvent, that is fired by the loaded iframe. The IframeResizeEvent also contains a value for “height” that should be used by the extension to set the height of the content’s host iframe.

Sharing

Version 0.1 can limit sharing capabilities to a list of email addresses. Email shares are at the /email_shares endpoint.

Version 1.0, Working Draft

The following conventions are under development, meaning you can help develop this part of the system, but don’t expect your extension will work with these endpoints yet.

URL Structures

Each of these endpoints have different security arrangements, and collectively cover most secure sharing needs. The steps below the URL format outline what an extension would do when it encounters the URL.


LEVEL 0: Intermediary with Access

https://priv.ly/posts/

  • Parameter: Post Identifier
  1. The extension asks Privly for the content, which the user may or may not have access to

https://priv.ly/distributed

  • Parameter: Content Host (example: contenthost.org/privly/####?optional_additional_auth=)
  1. The extension checks the user preferences and the privacy status of contenthost.org
  2. The extension then requests the content from contenthost.org

LEVEL 1: Separation of Content and Cryptography

In this level of security and privacy, the link contains either the cipher text or the decryption key, and the link points to the server with the identified cipher text or decryption key. This level preserves content readability without needing an extension or user account, but the remote server only needs the link to have access to the cleartext.

https://priv.ly/cipher_text/

  • Parameter: Post Identifier
  • Parameter: PGP Key
  1. The extension asks Privly for the cipher text, which the user may or may not have access to
  2. The extension decrypts the content according to the key on the url

https://priv.ly/private_key/

  • Parameter: Key Identifier
  • Parameter: Cipher Text
  1. The extension asks Privly for the decryption key, which the user may or may not have access to
  2. The extension decrypts the content from the URL according to the key from the server

https://priv.ly/distributed/cipher_text

  • Parameter: Cipher Text Host (example: contenthost.org/privly/####?optional_additional_auth=)
  • Parameter: PGP Key
  1. The extension checks the user preferences and the privacy status of contenthost.org
  2. The extension then requests the cipher text from contenthost.org
  3. The extension decrypts the content according to the key on the url

https://priv.ly/distributed/private_key

  • Parameter: Key Host (example: keyhost.org/privly/####?optional_additional_auth=)
  • Parameter: Key Identifier
  • Parameter: Cipher Text
  1. The extension checks the user preferences and the privacy status of keyhost.org
  2. The extension then requests the decryption key from keyhost.org
  3. The extension decrypts the content according to the returned key

LEVEL 1.5: Two Parties

In this level of security and privacy, the link points to two different servers and organizations. The individuals or organizations storing the keys and cipher text could collaborate to gain access to the cleartext, but in many cases this would be unlikely.

https://priv.ly/separation

  • Parameter: Cipher Text Host (example: contenthost.org/privly/####?optional_additional_auth=)
  • Parameter: Key Host (example: keyhost.org/privly/####?optional_additional_auth=)
  • Parameter: Key Identifier
  • Parameter: Cipher Text Identifier
  1. The extension checks the user preferences and the privacy status of contenthost.org and keyhost.org
  2. The extension then requests the decryption key from keyhost.org
  3. The extension then requests the cipher text from contenthost.org
  4. The extension decrypts the content according to the returned key

LEVEL 2 Intermediaries Have no Access

These links have secondary layer of encryption. Keys are encrypted according to the public key for a user’s encryption wallet. No one but the holder of the key for the wallet can access the clear text decryption keys. The procedures below all assume that the extension has checked out the encryption wallet (from somewhere) and decrypted it on the extension.

Sharing procedures in this level are more complex and require encrypting the keys for each shared individual. Sharing procedures will be finalized when the viewing procedures below are finalized. All content can still be viewed on the web server on this level if the user gives the server access to their private keys and the link. Giving the remote server access to private keys is discouraged.

https://priv.ly/cipher_text/

  • Parameter: Post Identifier
  1. The extension asks Privly for the cipher text, which the user may or may not have access to
  2. The extension decrypts the content according to their private key

https://priv.ly/private_key/

  • Parameter: Key Identifier
  • Parameter: Cipher Text
  1. The extension decrypts the key with their private key if they have one
  2. The extension decrypts the content from the URL

https://priv.ly/distributed/cipher_text

  • Parameter: Content Host (example: contenthost.org/privly/####?optional_additional_auth=)
  • Parameter: Encrypted PGP Key (encrypted by a public key)
  1. The extension attempts to decrypt the PGP key in the parameter
  2. The extension checks the user preferences and the privacy status of contenthost.org
  3. The extension then requests the cipher text from contenthost.org
  4. The extension decrypts the content according to the key on the url

https://priv.ly/distributed/private_key

  • Parameter: Key Host (example: keyhost.org/privly/####?optional_additional_auth=)
  • Parameter: Key Identifier
  • Parameter: Cipher Text
  1. The extension checks the user preferences and the privacy status of keyhost.org
  2. The extension then requests the decryption key from keyhost.org
  3. The extension decrypts the private key
  4. The extension decrypts the content according to the decrypted private key

https://priv.ly/separation

  • Parameter: Cipher Text Host (example: contenthost.org/privly/####?optional_additional_auth=)
  • Parameter: Key Host (example: keyhost.org/privly/####?optional_additional_auth=)
  • Parameter: Key Identifier
  • Parameter: Cipher Text Identifier
  1. The extension checks the user preferences and the privacy status of contenthost.org and keyhost.org
  2. The extension then requests the decryption key from keyhost.org
  3. The extension attempts to decrypt the decryption key
  4. The extension then requests the cipher text from contenthost.org
  5. The extension decrypts the content according to the decrypted key

Version 2.0, Teaser

Ubiquitous privacy+security, distributed identity, access tokens, p2p, and site-specific parsers+formatters.