Confirm
471
edits
Changes
lots of updates
* define how wrap(kB) is unwrapped to get kB
* confirm this is actually implementable inside Firefox (especially w.r.t. NSS)
The test vectors included on this page were produced by the python code in https://github.com/warner/picl-spec-crypto . The diagrams may lag behind the latest version of that code.
= Email+Password -> SignToken/ResetToken Creating The Account =
The first interaction with the keyserver takes an email+password pair and receives back (kA, wrap(kB), token). This starts act performed by using key-stretching a user is to transform create the account. They enter email+password into a "masterKey"their browser, which 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 does the keyserver, resulting in three valuesfollowing steps: kA, wrap(kB), and the signToken (or resetToken). The masterKey is also used to derive the key that will decrypt wrap(kB) into the actual kB value.
The protocol is optimized to minimize roundserver, when creating a new account, creates both kA and wrap(kB) as randomly-generated 256-bit (32-trips and to enable parallelismbyte) strings. As a resultIt stores these, along with all the remaining values, indexed by email, in the two messages it sends (getToken1 and getToken2) each perform multiple jobsaccount table where they can be retrieved by getToken later.
== ProofEmail+Password -Of-Work => SignToken/ResetToken =
To protect connect a browser to an existing account, we use the server's session table memory following "getSignToken" protocol to transform an email+password pair into (kA, kB, signToken). "kA" and CPU usage for "kB" enable the initial SRP calculationbrowser to encrypt/decrypt synchronized data records, while "signToken" is used to convince the storage server might require clients to perform busy-work before calling getToken1(). The server can control how much work is requiredaccept read and write requests for those records.
The server should create a prefix string that contains a parseable timestamp protocol is optimized to minimize round-trips and to enable parallelism, to reduce the time it takes to connect a random nonce (e.g. "%d-%d-" % (int(time.time()), b32encode(os.urandom(8)))). The server should also decide on browser to the account to just a cutoff time (perhaps ten minutes ago)few seconds. Each server must then maintain As a table of "old PoW strings" to prevent replay attacks result, the two messages it sends (these do not need to be shared among all servers: an in-RAM cache is finegetToken1 and getToken2)each perform multiple jobs.
After "masterKeystretchedPW" is derived, a second HKDF call is used to derive "unwrapKeysrpPW" and "srpPWunwrapBKey" which will be used later.
[[File:PICL-IdPAuth-main-KDF.png|masterKey KDF]]
== SRP Protocol Details ==
The PiCL client uses the SRP protocol (http://srp.stanford.edu/) to prove that it knows the (stretched) account password without revealing the actual password (or information enabling a brute-force attack) to the server or any eavesdroppers.
SRP is somewhat underspecified. We use SRP-6a, with SHA256 as the hash, and the 2048-bit modulus defined in RFC 5053 Appendix A. We consistently zero-pad all string values to 256 bytes (2048 bits), and use H(A+B+S) as the key-confirmation message "M1". These details, plus the SRP design papers and RFCs 2945 and 5054, should be enough to build a compatible implementation. The diagrams below are annotated with test vectors to verify compatibility.
After using resetAccount, clients should immediately perform the getToken(sign) protocol. If the old password was forgotten, this is necessary to fetch kA. In either case, a new signToken is required, since old signTokens are revoked by resetAccount. Clients should retain the srpPassword value during this process to avoid needing to run the lengthy key-stretching routine a second time.
= Crypto Notes =
A slightly more-traditional alternative would be to use AES-CTR (with the same HMAC-SHA256 used here), with a randomly-generated IV. This is equally secure, but requires implementors to obtain an AES library (with CTR mode, which does not seem to be universal). An even more traditional technique would be AES-CBC, which introduces the need for padding and a way to specify the length of the plaintext. The additional specification complexity, plus the library load, leads me to prefer HKDF+XOR.
kB is equal to the XOR of wrapKey (which is a deterministic function of the user's email address, password, stretchSaltmainSalt, and the stretching parameters) and the server's randomly-generated wrap(kB) value, making kB a random value too. Using XOR as a wrapping function allows us to avoid sending kB or wrap(kB) in the initial createAccount arguments, which are not protected by SRP, and thus would enable an eavesdropper to mount a dictionary attack on the password (using wrap(kB) as their oracle).
Likewise, allowing the server to generate kA avoids exposure during createAccount. The only point of vulnerability is a forgotten-password resetAccount() message, if an eavesdropper can learn the resetToken. In this case, the attacker might either use the resetToken themselves (then use signToken to learn kA and wrap(kB)), or passively decrypt the resetAccount() arguments to retrieve just wrap(kB). Given wrap(kB) and some encrypted browser data, the attacker can guess passwords (and derive kB, etc) until the data decrypts properly.
To make this technique safe, any time kB or the password is changed, the stretchSalt mainSalt should be changed too. Otherwise knowledge of both wrap(old-kB) and old-kB would reveal wrapKey, making it easy to deduce the new kB. Changing stretchSalt mainSalt causes wrapKey to change too, preventing this.
There is no MAC on wrap(kB). If the keyserver chooses to deliver a bogus wrap(kB) or kA, the client will discover the problem a moment later when it talks to a storage server and attempts to retrieve data from an unrecognized collection-ID (since we intend to derive collection-IDs from the key used to encrypt their data, which will be derived from kA or kB as appropriate). It might be useful to add a checksum to kA and wrap(kB) to detect accidental corruption (e.g. store and deliver kA+SHA256(kA)), but this doesn't protect against intentional changes. We omit this checksum for now, assuming that disks will be reliable enough to let us never experience such failures.
= 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 getToken1(). The server can control how much work is required.
The getToken1() call looks for a "X-PiCL-PoW:" HTTP header. Most of the time, clients don't supply this header. But if the server responds to the getToken1() call with an error that indicates PoW is required, clients must create a valid PoW string and include it as the value of an "X-PiCL-PoW:" header in their next call to getToken1().
The server's error message includes two parameters. The first is a "prefix string": the client's PoW string is required to begin with this prefix. The second is a "threshold hash". SHA256(PoWString) is required to be lexicographically earlier than the thresholdHashString (i.e. the numerical value of its hash must be closer to zero than the threshold). The client is expected to concatenate the prefix with a counter, then repeatedly increment the counter and hash the result until they meet the threshold, then re-submit their getToken1() request with the combined prefix+counter string in the header. If the client has spent more than e.g. 10 seconds doing this, the client should probably help the user cancel the operation and try again.
When a server is under a DoS attack (either via some manual configuration tool or sensed automatically), it should start requiring valid unique X-PiCL-PoW headers. The server should initially require very little work, by using a threshold hash with just a few leading zero bits. If this is insufficient to reduce the attack volume, the threshold should be lowered, requiring even more work (from both the attacker and legitimate clients).
The server should create a prefix string that contains a parseable timestamp and a random nonce (e.g. "%d-%d-" % (int(time.time()), b32encode(os.urandom(8)))). The server should also decide on a cutoff time (perhaps ten minutes ago). Each server must then maintain a table of "old PoW strings" to prevent replay attacks (these do not need to be shared among all servers: an in-RAM cache is fine).
When the server receives a proposed PoW string, it first splits off the leading timestamp, and if the timestamp is older than the cutoff time, it rejects the string (either by dropping the connection, or returning a new "PoW required" error if it's feeling nice). Then it hashes the whole string and compares it against the threshold, rejecting those which fail to meet the threshold. Finally, for strings that pass the hash threshold, it checks the "old strings" table, and rejects any that appear on that list.
If the PoW string makes it past all these checks, the server should add the string to the "old strings" table, then accept the request (i.e. compute an srpB value and add a session-id table entry for the request).
The old-strings table check should be optimized to reject present strings quickly (i.e. if we are under attack, we should expect to see lots of duplicates of the same string, and must minimize the work we do when this occurs).
The server can remove values from the old-strings table that have timestamps older than the cutoff time. The server can also discard values at other times (to avoid consuming too much memory), without losing anything but protection against resource consumption.
Other notes:
The server-side code for this can be deferred until we care to have a response to a DoS attack. However the client-side code for this must be present from day one, otherwise we won't be able to turn on the defense later without fear of disabling legitimate old clients.
The server should perform as little work as possible before rejecting a token. Every extra CPU cycle it spends in this path is increasing the DoS attack amplification factor.
The nonce in the prefix string exists to make sure that two successive clients get different prefixes, and thus do not come up with the same counter value (and inadvertently create identical strings, looking like a replay attack). If this proved annoying or expensive, we could instead obligate clients to produce their own nonce.
TBD: Is this worth it? Should the PoW string go into an HTTP header? (I want it to be cheap to extract, and not clutter logs). Should the error response be a distinctive HTTP error code so our monitoring tools can easily count them? We can also use this feature to slow down online guessing attacks (i.e. trigger it either when getToken1 is called too much or when getToken2 produces too many errors). Since getToken1() includes an email address, we could also requires PoWs for some addresses (e.g. those we know to be under attack) but not others.
= Glossary =
