Skip to content

doc: add caveats and example to crypto.timingSafeEqual #41837

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lostfictions wants to merge 3 commits into
base: main
Choose a base branch
from
Open

doc: add caveats and example to crypto.timingSafeEqual #41837

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0230cb0
doc: add footguns and example to `timingSafeEqual`
lostfictions Feb 3, 2022
41ca418
doc: refine language in `crypto.timingSafeEqual`
lostfictions Feb 4, 2022
3a9030c
doc: further refine language for `crypto.timingSafeEqual`
lostfictions Feb 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
doc: further refine language for crypto.timingSafeEqual
  • Loading branch information
@lostfictions
lostfictions authored Feb 4, 2022
commit 3a9030c9fc18ff8cc72a2b6fa4a47955043b90d5
13 changes: 7 additions & 6 deletions doc/api/crypto.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5339,12 +5339,13 @@ Particular care must be taken if `crypto.timingSafeEqual` is used in scenarios
where one or both arguments may vary in length, as its algorithm is only
constant-time with respect to a byte length that is consistent. For example, if
you are comparing a known secret to an input of unknown length, do not truncate
the longer of the two to match the length of the shorter one. Doing so may seem
more efficient, but it can leak timing information. In this case, you might
instead choose to always size `a` and `b` to the length of the input; this
means that `crypto.timingSafeEqual` may not always execute in the same amount
of time, but its variance will be strictly dependent on the attacker's input
rather than on the length of your secret.
whichever of the two happens to be longer to match the length of the shorter
one. Doing so may seem more efficient, but it can leak timing information. In
this case, you might instead choose to _always_ size `a` and `b` to the length
of the input, regardless of whether it's longer or shorter than the secret.
This would mean that `crypto.timingSafeEqual` might not always execute in the
same amount of time across calls, but its variance will be strictly dependent
on the attacker's input rather than on the length of your secret.

In the above scenario you'll also need to check that the original input is of
the same length as the secret, but this should be done _in addition_ to calling
Expand Down