{
  "public-key": "<encoded public key>",
  "authentication": "/browserid/auth",
  "provisioning": "/browserid/provision"
}

{
  "authority": "browserid.mozilla.org"
}

    // A function invoked to fetch provisioning parameters, such as
    // email and desired certificate duration.
    navigator.id.beginProvisioning(function(email, cert_duration_s) { });


<span class="c1">// cause the browser to generate a key-pair, cache the private key</span>
<span class="c1">// and return the public key for signing.</span>
<span class="nx">navigator</span><span class="p">.</span><span class="nx">id</span><span class="p">.</span><span class="nx">genKeyPair</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">pubkey</span><span class="p">)</span> <span class="p">{</span> <span class="p">});</span>

<span class="c1">// upon successful certificate signing, register the certificate</span>
<span class="c1">// with the browser.</span>
<span class="nx">navigator</span><span class="p">.</span><span class="nx">id</span><span class="p">.</span><span class="nx">registerCertificate</span><span class="p">(</span><span class="nx">certificate</span><span class="p">);</span>

<span class="c1">// in the event of a failure, the provisioning code should</span>
<span class="c1">// invoke this function to terminate the provisioning process,</span>
<span class="c1">// providing a developer readable string</span>
<span class="nx">navigator</span><span class="p">.</span><span class="nx">id</span><span class="p">.</span><span class="nx">raiseProvisioningFailure</span><span class="p">(</span><span class="nx">string</span> <span class="nx">reason</span><span class="p">);</span></code></pre></figure>


Provisioning web content should include the following javascript to
provide the above functions:

https://browserid.org/provisioning_api.js


Upon load, provisioning web content should immediately invoke
navigator.id.beginProvisioning() to indicate to the browser that
the provisioning process has begun, and to obtain provisioning
parameters such as the recommended certificate duration and the email
address the user would like to verify.

Once the email is obtained, the provisioning page can determine whether there
is an authenticated session in the user's present browser that can be leveraged
to confirm the user's identity.  The criteria for whether such a session exists
and the user may be silently provisioned with a certificate is up to
the primary IdP who may use standard web sessioning mechanisms (like cookies).

As soon as it is determined that the user may be provisioned, the primary's
provisioning code should cause a key-pair to be generated by the browser by
invoking navigator.id.genKeyPair(), providing a callback that will be called
with the encoded public key once the generation process is complete.

Once provisioning code has a public key, it should pass it up to IdP servers
for signing, and return the signed version to the client.  Finally the
provisioning code should invoke navigator.id.registerCertificate() with the
encoded certificate as a parameter to successfully complete the provisioning
process.

If at any point an error is encountered during the provisioning process,
navigator.id.raiseProvisioningFailure() may be called with a developer
readable failure string to indicate to the browser that an error has occurred.

Authentication Webpage

The authentication webpage is displayed from within the BrowserID dialog after
silent provisioning fails, and is intended to allow the user to provide
authentication credentials to the primary as part of authenticating to a website.

The authentication page should be designed to work well on mobile devices and
desktops.  For the latter, the IdP may assume a resolution of 700 pixels by
375 pixels.

Upon load, the authentication webpage will be loaded with several pieces of
GET data, including:


user: The local part of the email address the user is attempting to use.
return_to: The URL that the user should be sent to after authentication



In the previous example, the loaded authentication URL may look like:

https://exampleprimary.org/browserid/auth?user=bob&return_to=https://browserid.org/sign_in#Ad4f


Once the user's interaction with the authentication dialog is complete, the
dialog should redirect to the URL provided in the return_to GET parameter.

Subsequent to this interaction, the BrowserID dialog will re-attempt the
provisioning process, and the results of that will indicate whether the
user has successfully authenticated with the primary.

Data Formats

Above we avoid the important issue of data formats for certificates,
public keys, and private keys.  At the time of writing, we're working
to finalize the specific cryptographic algorithms and encoding formats
we'll be using.  BrowserID currently uses RSA encoded in JSON
Web Tokens.  These choices are being revisited to attempt to come
up with an algorithm and encoding that has adequate performance and
security, ideally with mature and widely available implementations.

Next Steps

There are several open issues with this proposal, and by no means should it be
considered final.  The intention of this post is to open up our present thinking
for discussion.  Along with fielding community feedback and ideas, we'll now start
prototyping an example primary to get a feel for implementation considerations and
user experience, to allow us to refine the proposal.

Issues for further consideration

Inline authentication

One complexity of primary IdPs is that today, the flow of authenticating to a
website becomes a three party transaction:  BrowserID, primary, and website. There
are many ways to transfer control from BrowserID to the primary once we
determine that the email the user wishes to use is associated with a primary
identity authority.

The mechanism that was chosen is to replace the BrowserID dialog with content from
the primary.  This decision has significant trade-offs to consider.  The benefits
of this approach include:


The URL bar is displayed by the browser as usual, leveraging familiar anti-phishing UI.
Primary content has full control over branding, how the user should be authenticated, and
 what sessioning mechanisms to use.
The user need not find a different window and return to the dialog subsequently,
 which would raise UX problems.
The protocol is highly portable.



Discovering the problems with the proposed approach is left as an exercise for the reader.

Division of Authentication and Provisioning

The above design breaks certificate provisioning
into two distinct processes, implemented by two distinct web
resources.  These are authentication - the process of establishing an
authenticated session with your primary - and provisioning - the
process of obtaining a signed certificate.

This decision was made to minimize the duplication of code, and simplify requirements on
primaries.  There are several features of this approach worth consideration:


Authentication code need not interact with any browser provided JavaScript APIs, nor include any cryptographic code
Provisioning code need not include any styling nor provide any visible UI.
Authentication code can refuse to be run in a frame.
Provisioning code must run in a frame.
In the case where an authenticated session does not exist, we'll perform provisioning twice.
Browser caching and careful API design should mitigate downsides of multiple provisioning attempts.



return_to vs. A Well-Known Return URL

When the authentication resource is loaded, it's passed a URL to send the user to upon completion
in the return_to GET parameter.  An alternative implementation would be to define this return
URL, making it well known.  Benefits of return_to include a means for the dialog to pass
temporal, non-sensitive state to itself, and a bit less specification to rev.

Errors during provisioning

The provisioning iframe can fail in a number of ways.  It can send no response to the containing
iframe, malformed responses, or it can try to frame-bust the BrowserID dialog.

For the first two cases, we should develop heuristics which can detect
runaway dialogs.  One utility of navigator.id.beginProvisioning() is
that it is expected to invoked at the time the provisioning code loads, which
give us an early indication that the provisioning code is
functioning as expected.  Timeout heuristics can consider information like this
to robustly determine whether provisioning should be considered stalled.

As far as frame busting, a reasonable countermeasure may be to have the BrowserID dialog close
upon unload with a failure, upon attempts by embedded code to frame-bust.  Further, the iframe
sandbox property can be used in browsers where it's supported.

Errors during authentication

Authentication code is in no way forced to redirect the user back to BrowserID as is designed.
The countermeasure here is a combination of existing browser native mechanisms to
help indicate to the user that something phishy is going on, combined with potentially a
dynamic blacklist of known bad actors.

When BrowserID is implemented by browser vendors, several additional countermeasures
become possible.

Versioning

Several protocols are defined in this proposal.  Drastic change can be handled by versioning
of the support declaration document, which would obviate the need for more granular versioning.