Documentation

These input parameters are grouped together because the envisioned use for them is that they are constants (or near-constants) specified by a deployment. User-supplied inputs would typically not go here.

The seguid parameter acts as a deployment-wide salt. Cryptographically speaking, the most important thing a deployment can do is specify a constant seguid. It is highly recommended that the seguid input be a genuine Self-Documenting Globally Unique Identifier attesting to the parameters, purposes, and public playbook of the protocol for y'all to follow.

In more concrete cryptographic terms, the seguid parameter is the constant HMAC key used by the protocol right up until the final output exansion. This design is closely modelled on the HKDF construction. As such, adding null bytes onto the ends of seguids that are less than 64 bytes long should be the only source of trivial collisions in the entire protocol.

The remaining parameter strings are all directly-documenting plaintext tags. A deployment can use these tags to encode a message into the password hash function so that it must be known to whomever is hashing a password of their choice.

Finally, the rounds parameter determines the latency of the function. At least 250,000 rounds are recommended if PHKDF is used as the sole key stretching component of a password hash database.

Unfortunately PHKDF is inexpensively parallelized, so large investments here aren't a good expenditure of a user's latency budget. This is why the G3P integrates bcrypt, and cuts the suggested rounds down to 20,000

For comparison, n rounds of PHKDF is approximately equivalent to (1.5 + dtl)*n + c rounds of PBKDF2, where dtl is related to the domain tag length, and c is a bit larger than 130 or so.

Here, dtl is 0 when the domain tag is between 0 and 19 bytes long, 0.5 when the domain tag is between 20 and 83 bytes long, and an additional 0.5 for every 64 bytes thereafter. Thus these functions exhibit extreme timing side channels on the length of the domain tag.

By contrast, the long tag is hardened against timing side channels up to a bit less than 5 kilobytes in length. However, an extremely long tag does reduce the headroom provided to masking the length of the username and password fields, however the minimum headroom allocated to the username and password fields is a bit less than 3 kilobytes.

As an alternate tagging location, consider the phkdfInputArgs_credentials vector, which can be used as an inexpensive, pay-as-you-go plaintext tagging location.

If the total encoded byte length of phkdfInputBlock_tags is between 0-63 bytes, then these hash protocols operate in a constant number of SHA256 blocks. Every additional 64 bytes incurs the computation of two or three additional SHA256 blocks, because these tags are hashed into the result two times in the case of phkdfPass, and three times in the case of phkdfSimple (and g3pHash).

The username and password are grouped together because they are normally expected to be supplied by users or other observers of a deployment.

Furthermore, the credentials vector is here because it is an ideal location to include other user input. For example, one could implement a Two-Secret Key Derivation (2SKD) scheme analogous to 1Password's.

A deployment can also specify additional constant tags as part of the credentials vector. As the plaintext of these tags is only ever hashed into the output a single time, this is the least expensive pay-as-you-go option for plaintext tagging.

The credentials vector is constant time on 0-63 encoded bytes, incurring one additional SHA256 block every 64 bytes thereafter. This includes a variable-length field that encodes the bit length of each string; this field itself requires 2 or more bytes.

The username and password are constant time as long as their encoded lengths add up to less than roughly 3 kilobytes, or the username, password, and domain tag add up to less than roughly 8 kilobytes. The actual numbers are somewhat less in both cases, but this is a good approximation.

These parameters are used to tweak the final output, without redoing any expensive key stretching. A possible use case is including a high entropy secret in the role itself that isn't available until after a successful stage of authentication.

Since these parameters are processed in a context that could conceivably be performance sensitive, we don't apply any length padding or side-channel hardening. Instead we opt for maximizing free tagging space. Thus we want to avoid incurring additional SHA256 block computations, one of the favorite techniques employed by the key-stretching phase of phkdfPass to harden against timing side-channels.

A deployment could conceivably harden this expansion phase against timing side channels themselves, if the were sufficiently inclined. There are several techniques. For starters, a deployment could specify an additional variable-length string in the role vector, used to control its relative ending position inside the SHA256 buffer.

A plain-old-data explicit representation of the intermediate phkdfPass computation after the PhkdfInputBlock and PhkdfInputArgs have been processed and key stretching has been completed, but before the tweaks have been applied and the final output generated.

If you ever need to serialize or persist a seed, you probably want this.

Intended to be generated by phkdfPass_seedInit and then consumed without modification by phkdfPass_seedFinalize.

A non-tweakable, complete password prehash protocol

A tweakable, complete prehash protocol. Note that this function is very intentionally implemented in such a way that the following idiom is efficient, and only performs the expensive key stretching phase once:

 let mySeed = phkdfPass block args
  in [ mySeed tweak1, mySeed tweak2, mySeed tweak3 ]

However in the case that you want or need to persist or serialize the intermediate seed, then the plain-old-datatype PhkdfSeed and its companion functions phkdfPass_seedInit and phkdfPass_seedFinalize are likely to be more appropriate.

This generates a seed, which encapsulates the expensive key-stretching component of phkdfPass into a reusable, tweakable cryptographic value. This function is way slower than it's companion, phkdfPass_seedFinalize. Broadly comparable to HKDF-Extract, though with key stretching built-in.

This consumes a seed and tweaks to produce the final output stream. This function is the output expansion phase of phkdfPass. This function is way faster than it's companion phkdfPass_seedInit. Broadly comparable to HKDF-Expand.