I'm maybe going to try to do this in the short term:

• Write the integrity-check-management scripts in T12470.
• Rename digest() to weakDigest().
• Introduce a new table in the Auth database for HMAC keys, deprecating security.hmac-key with the intent to eventually remove it.
• The new method will have a signature like PhabricatorHash::digest($material, $role), where $role is a lookup to a random secret key in the HMAC table that we read through the ImmutableCache.
• Use the new stuff for integrity checks.

Then we can audit and replace the old stuff at our leisure.

Piece of info (you guys might already be aware of it) which might be of interest when implementing this; SHA512 is often faster then SHA256 on x64. See for example: https://crypto.stackexchange.com/questions/26336/sha512-faster-than-sha256

I get these rough per-hash costs locally (Macbook Pro), with a 64-byte key:

I think these costs are both way beneath the level of line noise for all applications we use hashing for.

(That said, the hash cost may become very relevant when we eventually ship "Phabricator Valuable Golden Coin Money", our blockchain-based virtual currency.)

In moving forward here, we're generally moving from manually-configured HMAC keys to automatic ones. This is generally good: it's simpler (less configuration); and I believe almost no one configured the old ones, so installs now actually get unique HMAC keys; and the new keys have more entropy, too.

In some cases, there was theoretical value in changing these keys as a security response. For example, if you leaked some "Reply-To" addresses, you could change phabricator.mail-key to invalidate all the old addresses. I believe essentially no one has ever done this, but we could be exceptionally robust here by doing this:

• Add an abstract class PhabricatorNamedHMACDigest { ... }.
• Subclass it into final class PhabricatorMailObjectAddressNamedHMACDigest { const HMAC = 'mail.object-address-key'; ... }.
• Have some methods like getAnExplanationOfWhatThisKeyIs() and describeWhyYouWouldWantToRegenerateThisKey().
• Provide bin/hmac list to show current keys and explain what they are, and bin/hmac regenerate <key> to regenerate a particular key.

This is a bit of work and pretty low-value, but maybe not totally unreasonable. It doesn't add much complexity, but does feel fairly YAGNI.

The low-budget version of hmac regenerate <key> is DELETE FROM phabricator_auth.auth_hmackey WHERE .... This will automatically regenerate the missing key the next time it is used.