Skip to content
This repository

A BrowserID Library (including a standalone verifier)

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 example
Octocat-spinner-32 lib
Octocat-spinner-32 nbproject
Octocat-spinner-32 phpdoc
Octocat-spinner-32 shimmed_primaries
Octocat-spinner-32 var
Octocat-spinner-32 .gitignore
Octocat-spinner-32 README
Octocat-spinner-32 verify.php
README
---------------------
BrowserID PHP Library
---------------------

(1) Summary
(2) Requirements
(3) Release notes
(4) Usage
(5) Websites
(6) Credits
(7) License
(8) TODOs


(1) Summary
-----------

The library offers functions for verifying BrowserID/Persona assertions either directly 
on the server or using Mozillas fallback verifier. Verifying the assertions directly 
has the advantage that the assertion is not sent over the internet and to reduce 
dependencies on others.

Since BrowserID/Persona is highly under developement right now, this libraries local 
verifier may be out of date the time you use it. Until the protocol get's stable, 
the usage is only advised for experimental usage. If you want to use BrowserID/Persona 
in an productional environment, it's recommented to use Mozillas verifier instead of 
verifying locally.

Using the remote verifier is currently the default mode if the environment is set 
to "production". To use the local verifier, open the file /lib/browserid.php and 
uncomment the following line:

Configuration::getInstance()->setEnvironment("developement");

!!! THIS IS NOT ADVISED FOR PRODUCTIONAL USE !!!

This will enable all currently configured developement features like the local verifier 
or shimmed primaries. To get back into the safe production environment, just comment the 
line out again.


(2) Requirements
----------------

This library uses native JSON support and cURL. Therefore you must use a 
version >= 5.2.0 for it to work. Fallback JSON implementations may follow.


(3) Release notes
-----------------

This library offers the working state as of 2012-10-02. This code uses some 
ideas as showed at https://github.com/mozilla/browserid/tree/dev/lib and 
https://github.com/mozilla/jwcrypto and ported them for PHP.


(4) Usage
---------

Example for verifying an assertion:
==============================================================
include('lib/browserid.php');
$response = Verifier::verify($assertion, 'yoursite.org');
if ($response["status"] == "okay") {
    $_SESSION['email'] = $response["email"];
    ...
} else {
    echo $response["reason"];
    ...
}
==============================================================

For more usage examples see the examples folder. Please configure the file 
lib/BrowserID/configuration.php before testing (especially hostname and base_path)

- examples/createKeys.php
    The library is offering some functions for helping to implement identity 
    providers. This example shows how to create and save a key pair later used 
    for signing identity certificates. The created certificates will be saved as 
    var/root.cert (public key) and var/root.secretkey. To obtain these keys for 
    signing, you can call Secrets::loadPublicKey() and Secrets::loadSecretKey().

- examples/createBundle.php
    This example creates an bundled assertion, just like the browser would do.
    The variables $publicKeyIdentity and $secretKeyIdentity contain the keys that 
    normally would be created by the browser.

    CertAssertion::createAssertion() creates the assertion claim and signs it with 
    the users identity certificate ($secretKeyIdentity). The public key of the 
    identity certificate will be signed by calling CertAssertion::createIdentityCert() 
    acting like a identity provider would do while provisioning using the public 
    key stored in Secrets::loadPublicKey().

NOTICE:
If you only want to use the remote verifier on your server, you only have to upload 
the following files without configuring anything:
    - verify.php
    - lib/browserid.php
    - lib/BrowserID/configuration.php
    - lib/BrowserID/utils.php
    - lib/BrowserID/verifier.php


(5) Websites
------------

BrowserID at GitHub :
- https://github.com/mozilla/browserid

Persona @ MDN :
- https://developer.mozilla.org/de/docs/persona

Mozilla Persona Main Page :
- https://login.persona.org/


(6) Credits
-----------

This library makes use of some external libraries. The following were adopted full or partly:
- PHPSecLib (http://phpseclib.sourceforge.net by Jim Wigginton)
- Math_BigInteger (http://pear.php.net/package/Math_BigInteger by Jim Wigginton)
- Crypt_DSA (http://pear.php.net/pepr/pepr-proposal-show.php?id=467 by TSURUOKA Naoya)

(7) License
-----------

Copyright (c) 2012 - 2013 Benjamin Krämer

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

(8) TODOs
---------

Some more data checking of fields needed before accessing them and adding IdP Proxies.

Implement public key cache. First try it with authenticating using the cached public 
key, if this fails, try it with fetching the well-known public key. The cache should 
also expire the keys since it is possible that the public key of a provider may change 
in case it is compromised.
Something went wrong with that request. Please try again.