doc: add caveats and example to crypto.timingSafeEqual

[lostfictions]

#41507 recently added documentation about an error case for crypto.timingSafeEqual, but even with that addition I think there are a few extra caveats to timingSafeEqual's use that are worth mentioning. I've tried to be as clear as possible in this addition without going outside the scope of documentation for a single function (ie. into the realm of broader crypto best practices). I've also added a short example for the function.

[Trott]

@nodejs/crypto

[tniessen]

Welcome @lostfictions and thank you for the contribution!

timingSafeEqual is tricky. In my personal experience, when inputs have different lengths, either something is wrong (for example, passwords should never be compared using timingSafeEqual) or the length of the secret is not actually secret (for example, when comparing API keys).

Do you have an example use case that potentially passes inputs to timingSafeEqual without validating their lengths first?

[tniessen]

Unfortunately, operations such as Buffer.byteLength(secret) are generally not timing-safe.

[lostfictions]

Fair enough! Maybe this is all extraneous and timingSafeEqual is more of a "this is a low-level primitive and I assume you already know what you're doing if you reach for it" deal. Or maybe it's worth instead amending the documentation with a brief mention of what you said -- raw passwords should never be compared directly, and it's a smell if you're comparing inputs of different lengths.

Do you have an example use case that potentially passes inputs to timingSafeEqual without validating their lengths first?

I actually saw this is in the wild in a package with 240,000 downloads per week:

https://github.com/LionC/express-basic-auth/blob/dd17b4de9fee9558269cdc583310bde5331456e7/index.js#L7-L17

Admittedly maybe the bigger issue here is "never use basic auth"?