Identity/Verified Email Protocol/Latest: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Replaced content with "This spec has been deprecated. Please check the /Identity/BrowserID protocol.")
Line 1: Line 1:
 
This spec has been deprecated. Please check the [[/Identity/BrowserID]] protocol.
This spec is not up to date with the latest BrowserID implementation yet. Read these:
 
* [http://lloyd.io/how-browserid-works How BrowserID works]
* [http://lloyd.io/primary-identity-authorities-in-browserid Primary Identity Authorities in BrowserID]
* [http://identity.mozilla.com The Identity Team Blog]
 
Past blog posts contain a lot of information, for example: [http://identity.mozilla.com/post/11145921163/browserid-design-for-privacy BrowserID Design for Privacy]
 
__TOC__
''MediaWiki editor tip: If you aren't seeing numbered section headings in the body of this document, you can force them to appear by logging in and clicking the "My preferences" link, at left, and select "Auto-number headings"''
 
;DRAFT
 
== Overview ==
 
This specification defines a mechanism for websites to request, from the user via her user-agent, a signed assertion of email-address ownership. Web sites can use this mechanism to register users on their first visit and log them back in on their subsequent visits. The trust path for these assertions of email-address ownership is designed to be federated and decentralized: individual domains can certify their own users. A fallback secondary authentication mechanism is defined to bootstrap the protocol.
 
== Terms ==
 
;Identity
:An email address controlled by the user.
 
;Public Key
:The public portion of an asymmetric cryptographic keypair used in a digital signature algorithm.
 
;Identity Certificate
:A cryptographically signed string which asserts that a given public-key is bound to a given identity.
 
;Primary Authority
:A signer of identity certificates for identities that are directly within this authority's domain.
 
;Secondary Authority
:A signer of identity certificates for identities that are ''not'' directly within this authority's domain. Relying parties may choose to trust only a subset of secondary authorities.
 
;Audience/Relying Party
:A relying party is a web site requesting, and later verifying, an identity assertion.
 
;Identity Assertion
:A cryptographically signed string which asserts to a particular audience that the current user owns the stated identity.
 
== Objects / Messages ==
 
The Verified Email Protocol defines messages using the [http://www.ietf.org/dyn/wg/charter/jose-charter JOSE specifications] for signing JSON-formatted objects.
 
=== Public Key ===
 
A VEP public key is a JSON object that includes fields:
 
* ''alg'' the algorithm for which this key was generated, using JOSE taxonomy
* additional fields specified by the algorithm, e.g. ''n'' and ''e'' for RSA public keys.
 
For example:
 
{
  "alg": "RS256",
  "n" : "4b3c34...",
  "e" : "93bc32...",
}
 
This data structure should move to [http://tools.ietf.org/html/draft-jones-json-web-key-01 JSON Web Keys].
 
=== Identity Certificate ===
 
An Identity Certificate is a JWT object with the following claims:
 
* ''exp'' the expiration as per JWT
* ''iss'' the domain of the issuer as per JWT
* ''public-key'' the serialized public key as defined above
* ''principal'' the principal being certified.
 
The principal is a JSON object that indicates the type of principal, e.g.
 
  {"email": "bob@example.com"}
 
or
 
  {"host": "intermediate.example.com"}
 
A complete JWT cert example:
 
{
  "iss": "example.com",
  "exp": "1313971280961",
  "public-key": {
    "alg": "RS256",
    "n" : "4b3c34...",
    "e" : "93bc32...",
  },
  "principal": {
    "email": "john@example.com"
  }
}
 
 
JOSE currently does not specify a certificate format. If it eventually does, we will consider moving to it.
 
=== Identity Assertion ===
 
An Identity Assertion is a JWT with the following claims:
 
* ''exp'' for expiration
* ''aud'' for the relying party (audience.)
 
An assertion might look like (with line breaks for readability):
 
eyJhbGciOiJSUzY0In0.
eyJleHAiOjEzMjAyODA1Nzk0MzcsImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6MTAwMDEifQ.
JmEBqwOH_qzw6_EHsCRB-CeShGyQ2y0bpapARZ308_8uT6TCWrKBpB8L2bFnMb664lz1nGytkBXF-tTIzGCOjg
 
which is a JWT with header:
 
{"alg": "RS64"}
 
and a payload of:
 
{"exp":1320280579437,"aud":"http://localhost:10001"}
 
=== Bundled Assertion ===
 
A Bundled Assertion is a combination of an Identity Assertion and a relevant sequence of Identity Certificates that tie the assertion to an issuing domain. Typically, a bundled assertion is a single certificate tying a public-key to an Identity, signed by the domain, and an Identity Assertion tied by the just-certified public key.
 
Currently, and ''this is subject to change'', a Bundled Assertion is the base-64 encoding of a JSON object that looks like:
 
{
  "certificates": ["...","..."],
  "assertion": "..."
}
 
Each certificate is an Identity Certificate as defined above. The assertion is an Identity Assertion as defined above.
 
== Main Protocol Flow ==
 
''This section is informative.''
 
Consider a web site, <tt>http://example.com</tt>, receiving a visit from a user. This web site wishes to obtain the user's verified email address using the Verified Email Protocol. The user in question, for the purposes of this description, is Alice. Alice owns two email addresses, <tt>alice@homedomain</tt> and <tt>alice@workdomain</tt>.
 
* <tt>example.com</tt> presents a login button with a JavaScript click handler.
* when Alice clicks the login button, <tt>example.com</tt>'s click handler invokes
navigator.id.getVerifiedEmail(gotAssertion);
* Alice is presented with a user-agent dialog that lets her select which email to present to <tt>example.com</tt>.
* If Alice chooses to cancel the transaction, <tt>gotAssertion</tt> is invoked with no parameters.
* If Alice chooses to authenticate using one of her email addresses, <tt>gotAssertion</tt> is invoked with a single parameter, an Identity Assertion.
* <tt>example.com</tt> should take this assertion and pass it back to its server. This can be accomplished with an AJAX request. For example, using jQuery:
 
function gotAssertion(assertion) {
  if (!assertion) {
    alert('you canceled login!');
  } else {
    $.post("/verifyAssertion", {assertion: assertion}, afterVerifyAssertion);
  }
}
 
It is worth noting that this assertion is a Bundled Assertion, as defined above. We call it ''assertion'' here for simplicity, since the Relying Party typically need only pass this assertion to a verifier service without worrying about the specific assertion contents.
 
== User-Agent Compliance ==
 
The User-Agent is critical for Verified Email Protocol support. Here, we define, normatively, the API that user agents MUST implement, including specific behaviors in response to these API calls. Relying Parties and Identity Providers can safely skip this section.
 
=== API ===
 
A compliant VEP User-Agent must implement all <tt>navigator.id</tt> API calls as described here:
 
<tt>navigator.id.getVerifiedEmail(object options, function callback);</tt>
 
The Relying Party MAY call the navigator.id.getVerifiedEmail method when it wishes to request that the User Agent generate an identity assertion as soon as it can. The User Agent SHOULD immediately seek to generate an Identity Assertion, prompting the user if it deems it necessary, and call the provided callback with an identity assertion or null in case the user chooses not to log in.
 
FIXME: should we provide error information if it's not just a user cancel?
 
<tt>navigator.id.beginProvisioning(object callback)</tt>
 
The callback function SHOULD accept parameters <tt>email</tt> and <tt>cert_duration_s</tt>.
 
<tt>navigator.id.genKeyPair(object callback);</tt>
 
The callback function SHOULD accept parameter <tt>pubkey</tt>, a serialized public-key string as per the above public-key spec.
 
<tt>navigator.id.registerCertificate(certificate);</tt>
 
The certificate parameter MUST be a valid serialized certificate, as per the above spec. The trust root for this certificate SHOULD comply with the characteristics described in the "Acceptable Trust Paths" section below.
 
<tt>navigator.id.raiseProvisioningFailure(string reason);</tt>
 
The reason parameter MUST be a string that can be reported to the user regarding the reason why a certificate failed to be provisioned.
 
WebIDL:
 
module navigator {
    module id {
        void beginProvisioning(object callback);
        void genKeyPair(string email, object callback);
        void registerCertificate(string certificate, string updateURL);
        void raiseProvisioningFailure(string reason);
    }
};
 
 
To process a request for identity registration from a web page, a User-Agent MUST:
 
# Create, if it has not already done so, a local data store that will persist beyond the current page view, keyed on email identity.
# Check the local data store for whether a certificate for the email address already exists and is valid. If so, the User-Agent SHOULD NOT proceed with key generation, and instead immediately call the provided callback to registerVerifiedEmail with a ''null'' argument.
# If no certificate already exists, the User-Agent MAY notify the user that a new email identity is being registered with the User-Agent. If the email identity has a domain that is different from the Identity Authority, the User-Agent SHOULD notify the user and seek confirmation.
# Produce an asymmetric keypair compatible with the JSON Web Key specification [JWK] and store it in the local data store.
# Return the public key to the JavaScript runtime of the web page through the provided callback.
# At a future point, when the registerVerifiedEmailCertificate function is called by a web page, the User Agent MUST verify that the public key in the Identity Certificate matches the already-stored keypair for the email identity in question. If it does not match, the User-Agent SHOULD reject the certificate and (do what?).
# Save the new certificate, as well as the refreshURL and errorURL arguments of the registerVerifiedEmailCertificate function.
 
=== Identity Assertion Generation ===
 
To process a request for a verified email, a User-Agent MUST:
# Reliably establish the full domain of the requesting site (including scheme and non-standard port).
# Check a local data store for previously established identity associations for the requesting site. If one or more associations are found, the User-Agent MAY ask the user for which identity to use, or automatically choose one based on some criteria (e.g., last-used).
# If no associations are found, the User-Agent SHOULD ask the user for what to do, by presenting a list of known email identities to choose from.
# If no email identities are known, the User-Agent MAY assist the user in any way it sees fit. [xxx ?]
# Verify the expiry date of the certificate associated with the identity of the previously-chosen association. If the certificate has expired, or would expire before the intended validity period of the assertion to be generated, the User-Agent MUST follow the steps in the CERTIFICATE REFRESH section of this specification.
# Create an Identity Assertion object for the chosen identity, scoped to the full domain of the requesting site (including scheme and non-standard port), and sign it with the private key associated with the chosen identity.
# Execute the navigator.id.onVerifiedEmail callback and provide the newly-created Identity Assertion as an argument.
 
=== Certificate Refresh ===
 
# To refresh a certificate, the User-Agent MUST fetch the resource located at the refresh URL provided by the Identity Authority in the registerVerifiedEmailCertificate for the certificate to be refreshed. The User-Agent SHOULD NOT display this resource to the user.
# If the server returns with an error status when loaded (in the 4xx or 5xx range), certificate refresh has failed. The User-Agent SHOULD notify the user and load the error URL associated with the certificate at registration time. This resource SHOULD be visible to the user, who is expected to interact with the Identity Authority to resolve the problem.
# If the server returns with 2xx status, the loaded resource is expected to follow the steps under section 1.4 (Identity Registration) to sign new keys for the user.
# The User Agent MUST maintain the resource loaded and operational for at least 30 seconds since last activity (network or JavaScript) to allow the Identity Authority to register multiple certificates if it wishes.
 
== Primary Authority Compliance ==
 
=== Declaring Support for Verified Email ===
 
=== Certifying Users ===
 
== Assertion Verification ==
 
Identity Assertions MUST NOT be verified in the client, in JavaScript or otherwise, since client runtimes may be altered to circumvent such verification. Instead, Identity Assertions SHOULD be sent to a trusted server for verification.
 
To verify an Identity Assertion, a Relying Party MUST perform the following checks:
# If the valid-until date of the assertion is earlier than the current time, the assertion has expired and must be rejected.
# If the nonce in the assertion has previously been received by the relying party, the assertion has been used and must be rejected.
# If the audience field of the assertion does not match the full domain (including scheme and optional non-standard port) of the page that requested the Identity Assertion, the assertion must be rejected.  Note that implementations MUST include the scheme and non-standard port, if any, in the match check.  A domain that includes the standard port, of 80 for HTTP and 443 for HTTPS, MUST be treated as equivalent to a domain that matches the protocol but does not include the port.  (Can we find an RFC that defines this equality test?)
# The signature over the assertion must be verified with the public key contained in the certificate.
# The certificate must be verified using the issuer's public key.  If the certificate contains an Issuer element, the certificate is secondary; in this case, the Relying Party must further decide whether the issuer is one that it trusts.
 
Note that a relying party may, at its discretion, use a verification service that performs these steps and returns a summary of results.  In that case, the verification service is acting as a relying party, and MUST perform all the checks described here.  In order to perform audience checking, the verification service must be told what audience to expect by the relying party.
 
== Security Considerations ==
 
things to write about:
* certificate validity period
* UAs reusing a key to get a new certificate
* timing attacks
* javascript implementations, good RNGs
 
== References ==
 
* JWT: [http://self-issued.info/docs/draft-jones-json-web-token-04.html http://self-issued.info/docs/draft-jones-json-web-token-04.html]
* JWK: [http://self-issued.info/docs/draft-jones-json-web-key.html http://self-issued.info/docs/draft-jones-json-web-key.html]

Revision as of 16:52, 19 January 2012

This spec has been deprecated. Please check the /Identity/BrowserID protocol.

Retrieved from "https://wiki.mozilla.org/index.php?title=Identity/Verified_Email_Protocol/Latest&oldid=388531"