From cc2ae19bcd95404caf6a3115fea0aec04a27c192 Mon Sep 17 00:00:00 2001 From: Igor Santos Date: Sun, 24 Jan 2021 02:55:03 -0300 Subject: [PATCH] Document the need for the code to be a string --- README.md | 4 +++- lib/TwoFactorAuth.php | 13 ++++++++++--- tests/TwoFactorAuthTest.php | 3 +-- 3 files changed, 14 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 46a90ab..ab2c9b6 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,9 @@ When the shared secret is added to the app, the app will be ready to start gener $result = $tfa->verifyCode($_SESSION['secret'], $_POST['verification']); ```` -`verifyCode()` will return either `true` (the code was valid) or `false` (the code was invalid; no points for you!). You may need to store `$secret` in a `$_SESSION` or other persistent storage between requests. The `verifyCode()` accepts, aside from `$secret` and `$code`, three more arguments. The first being `$discrepancy`. Since TOTP codes are based on time("slices") it is very important that the server (but also client) have a correct date/time. But because the two *may* differ a bit we usually allow a certain amount of leeway. Because generated codes are valid for a specific period (remember the `$period` argument in the `TwoFactorAuth`'s constructor?) we usually check the period directly before and the period directly after the current time when validating codes. So when the current time is `14:34:21`, which results in a 'current timeslice' of `14:34:00` to `14:34:30` we also calculate/verify the codes for `14:33:30` to `14:34:00` and for `14:34:30` to `14:35:00`. This gives us a 'window' of `14:33:30` to `14:35:00`. The `$discrepancy` argument specifies how many periods (or: timeslices) we check in either direction of the current time. The default `$discrepancy` of `1` results in (max.) 3 period checks: -1, current and +1 period. A `$discrepancy` of `4` would result in a larger window (or: bigger time difference between client and server) of -4, -3, -2, -1, current, +1, +2, +3 and +4 periods. +If you do extra validations with your `$_POST` values, just make sure the code is still submitted as string - even if that's a numeric code, casting it to integer is unreliable. Also, you may need to store `$secret` in a `$_SESSION` or other persistent storage between requests. `verifyCode()` will return either `true` (the code was valid) or `false` (the code was invalid; no points for you!). + + The `verifyCode()` accepts, aside from `$secret` and `$code`, three more arguments, with the first being `$discrepancy`. Since TOTP codes are based on time("slices") it is very important that the server (but also client) have a correct date/time. But because the two *may* differ a bit we usually allow a certain amount of leeway. Because generated codes are valid for a specific period (remember the `$period` argument in the `TwoFactorAuth`'s constructor?) we usually check the period directly before and the period directly after the current time when validating codes. So when the current time is `14:34:21`, which results in a 'current timeslice' of `14:34:00` to `14:34:30` we also calculate/verify the codes for `14:33:30` to `14:34:00` and for `14:34:30` to `14:35:00`. This gives us a 'window' of `14:33:30` to `14:35:00`. The `$discrepancy` argument specifies how many periods (or: timeslices) we check in either direction of the current time. The default `$discrepancy` of `1` results in (max.) 3 period checks: -1, current and +1 period. A `$discrepancy` of `4` would result in a larger window (or: bigger time difference between client and server) of -4, -3, -2, -1, current, +1, +2, +3 and +4 periods. The second, `$time`, allows you to check a code for a specific point in time. This argument has no real practical use but can be handy for unittesting etc. The default value, `null`, means: use the current time. diff --git a/lib/TwoFactorAuth.php b/lib/TwoFactorAuth.php index 7bc067d..e74ad97 100644 --- a/lib/TwoFactorAuth.php +++ b/lib/TwoFactorAuth.php @@ -62,6 +62,7 @@ class TwoFactorAuth /** * Calculate the code with given secret and point in time + * @return string */ public function getCode($secret, $time = null) { @@ -78,10 +79,16 @@ class TwoFactorAuth /** * Check if the code is correct. This will accept codes starting from ($discrepancy * $period) sec ago to ($discrepancy * period) sec from now + * @param string $secret + * @param string $code This shouldn't be casted to integer - you may lose zeroes to the left + * @param int $discrepancy + * @param int|null $time + * @param int $timeslice + * @return bool */ public function verifyCode($secret, $code, $discrepancy = 1, $time = null, &$timeslice = 0) { - $timetamp = $this->getTime($time); + $timestamp = $this->getTime($time); $timeslice = 0; @@ -90,7 +97,7 @@ class TwoFactorAuth // of the match. Each iteration we either set the timeslice variable to the timeslice of the match // or set the value to itself. This is an effort to maintain constant execution time for the code. for ($i = -$discrepancy; $i <= $discrepancy; $i++) { - $ts = $timetamp + ($i * $this->period); + $ts = $timestamp + ($i * $this->period); $slice = $this->getTimeSlice($ts); $timeslice = $this->codeEquals($this->getCode($secret, $ts), $code) ? $slice : $timeslice; } @@ -253,4 +260,4 @@ class TwoFactorAuth } return $this->timeprovider; } -} \ No newline at end of file +} diff --git a/tests/TwoFactorAuthTest.php b/tests/TwoFactorAuthTest.php index e011fc4..c9a070d 100644 --- a/tests/TwoFactorAuthTest.php +++ b/tests/TwoFactorAuthTest.php @@ -136,7 +136,6 @@ class TwoFactorAuthTest extends PHPUnit\Framework\TestCase } public function testVerifyCodeWorksCorrectly() { - $tfa = new TwoFactorAuth('Test', 6, 30); $this->assertEquals(true , $tfa->verifyCode('VMR466AB62ZBOKHE', '543160', 1, 1426847190)); $this->assertEquals(true , $tfa->verifyCode('VMR466AB62ZBOKHE', '543160', 0, 1426847190 + 29)); //Test discrepancy @@ -410,4 +409,4 @@ class TestTimeProvider implements ITimeProvider { public function getTime() { return $this->time; } -} \ No newline at end of file +}