Changes

== Email+Password -> AccountToken SignToken ==

The current stub just submits plaintext email+password and receives back (accountToken, kA, wrap(kB)). It uses no key-stretching, nor SRP.  The full replacement uses key-stretching to transform the email+password into a "masterKey", then feeds this into an SRP protocol to get a session key. It uses this session key to decrypt a bundle of encrypted data from the keyserver, resulting in three values: kA, wrap(kB), and the signToken. [[File:PICL-IdPAuth-bigpix.png|IdP Auth Big Picture]] This same protocol is used, with slightly different constants, to obtain the "resetToken". The protocol is optimized to minimize round-trips and to enable parallelism. As a result, the two messages it sends (getSignToken1 and getSignToken2) each perform multiple jobs. === getSignToken1 === As soon as the user finishes typing in the email address, the client should send it in the "getSignToken1" message to the keyserver. The response will be replaced sooninclude a set of parameters that are needed for key-stretching (described below), and the common parameters used by both sides of the SRP protocol to follow. These are simply looked up in a database entry for the client, along with an account-id. It must also include an allocated session-id that is used to associate this request with the subsequent getSignToken2 request. Finally, the response also includes the server's contribution to the SRP protocol ("srpB"), which is calculated on the server based upon a random value that it remembers in the session. === Proof-Of-Work === To protect the server's session table memory and CPU usage for the initial SRP calculation, the server might require clients to perform busy-work before calling getSignToken1(). (TBD)

=== SRP to Obtain Account Token ===The current stub does no stretching. It just performs a single HKDF operation, combining the user's email address, their password, and a "stretchSalt" retrieved from the server's getSignToken1() response. [[File:PICL-IdPAuth-stretch-KDF.png|Stretching KDF]]

== Using A later version of the Account Token ==protocol will replace this with the PBKDF2+scrypt+PBKDF2 protocol described in [[Identity/CryptoIdeas/01-PBKDF-scrypt]]. This stretching is expected to take a second or two. The client can optimistically start this process before receiving the getSignToken1() response using default parameters, and then check that it used the right parameters afterwards (repeating the operation if not). (We'll want to build the stretching function with periodic checkpoints so that we don't have to lose all progress if the parameters turn out to be wrong). The "stretchSalt" is added *after* the stretching, to enable this parallelism (at a tiny cost in security).

The single-use Account Token can be traded in for either a Signing Token or After "masterKey" is derived, a Reset Token. Once second HKDF call is used, the Account Token becomes invalid. The Account Token will also expire after a while (probably a few minutes to an hour). Each account derive "unwrapKey" and "srpPW" which will have just one Account Token valid at any given time. (We do not expect two devices to access the account so simultaneously that this becomes a problem)be used later.

[[File:PICL-IdPAuth-accountTokenmain-KDF.png|Using the Account TokenmasterKey KDF]]

The requestHMACkey is used in a HAWK (https://github.com/hueniverse/hawk/) request to provide integrity over the "getSignTokensignCertificate" request. It is used as credentials.key, while tokenID is used as credentials.id . HAWK includes the URL and the HTTP method ("POST") in the HMAC-protected data, and will optionally include the HTTP request body (payload) if requested (this is not used for getSignToken or getResetToken, but is used for "sign" itself).

For getSignToken and getResetToken, we don't We might not need request confidentialityfor signCertificate(). We *do* need it for resetAccount(). And we do need response confidentiality and integrityfor both. To achieve these, the HAWK response is defined to be HMAC'ed (using responseHMACkey) and encrypted (XORed with the responseXORkey). XOR is safe and appropriate because the key is single-use and the data we're protecting is short and fixed-length.