Http: Add HttpUtil::getTOTP() and relevant classes and interfaces

Author: lkrms

src/Toolkit/Contract/HasHmacHashAlgorithm.php

@@ -0,0 +1,13 @@
+<?php declare(strict_types=1);
+
+namespace Salient\Contract;
+
+/**
+ * @api
+ */
+interface HasHmacHashAlgorithm
+{
+    public const ALGORITHM_SHA1 = 'sha1';
+    public const ALGORITHM_SHA256 = 'sha256';
+    public const ALGORITHM_SHA512 = 'sha512';
+}

src/Toolkit/Contract/Http/OneTimePasswordGeneratorInterface.php

@@ -0,0 +1,14 @@
+<?php declare(strict_types=1);
+
+namespace Salient\Contract\Http;
+
+/**
+ * @api
+ */
+interface OneTimePasswordGeneratorInterface
+{
+    /**
+     * @param string $key Base32-encoded shared key.
+     */
+    public function getPassword(string $key): string;
+}

src/Toolkit/Http/HttpUtil.php

@@ -13,8 +13,10 @@
 use Salient\Contract\Http\HasHttpHeader;
 use Salient\Contract\Http\HasMediaType;
 use Salient\Contract\Http\HasRequestMethod;
+use Salient\Contract\HasHmacHashAlgorithm;
 use Salient\Http\Exception\InvalidHeaderException;
 use Salient\Http\Internal\FormDataEncoder;
+use Salient\Http\Internal\TOTPGenerator;
 use Salient\Utility\AbstractUtility;
 use Salient\Utility\Date;
 use Salient\Utility\Package;
@@ -31,6 +33,7 @@
  */
 final class HttpUtil extends AbstractUtility implements
     HasFormDataFlag,
+    HasHmacHashAlgorithm,
     HasHttpHeader,
     HasHttpRegex,
     HasMediaType,
@@ -432,4 +435,20 @@ public static function getNameValuePairs(iterable $items): iterable
             yield $item['name'] => $item['value'];
         }
     }
+
+    /**
+     * Get a time-based one-time password as per [RFC6238]
+     *
+     * @param string $key Base32-encoded shared key.
+     * @param HttpUtil::ALGORITHM_* $algorithm
+     */
+    public static function getTOTP(
+        string $key,
+        int $digits = 6,
+        string $algorithm = HttpUtil::ALGORITHM_SHA1,
+        int $timeStep = 30,
+        int $startTime = 0
+    ): string {
+        return (new TOTPGenerator($digits, $algorithm, $timeStep, $startTime))->getPassword($key);
+    }
 }

src/Toolkit/Http/Internal/TOTPGenerator.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Salient\Http\Internal;
+
+use Salient\Contract\Http\OneTimePasswordGeneratorInterface;
+use Salient\Contract\HasHmacHashAlgorithm;
+use Salient\Utility\Str;
+
+/**
+ * An [RFC6238] time-based one-time password generator
+ *
+ * @internal
+ */
+final class TOTPGenerator implements
+    OneTimePasswordGeneratorInterface,
+    HasHmacHashAlgorithm
+{
+    private int $Digits;
+    /** @var self::ALGORITHM_* */
+    private string $Algorithm;
+    private int $TimeStep;
+    private int $StartTime;
+
+    /**
+     * @param TOTPGenerator::ALGORITHM_* $algorithm
+     */
+    public function __construct(
+        int $digits = 6,
+        string $algorithm = TOTPGenerator::ALGORITHM_SHA1,
+        int $timeStep = 30,
+        int $startTime = 0
+    ) {
+        $this->Digits = $digits;
+        $this->Algorithm = $algorithm;
+        $this->TimeStep = $timeStep;
+        $this->StartTime = $startTime;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getPassword(string $key): string
+    {
+        // Get time steps between T0 and now as per [RFC6238] Section 4.2
+        $X = $this->TimeStep;
+        $T0 = $this->StartTime;
+        $T = (int) floor((time() - $T0) / $X);
+
+        /** @var string */
+        $T = hex2bin(sprintf('%016s', dechex($T)));
+        $K = Str::decodeBase32($key, true);
+
+        $hash = hash_hmac($this->Algorithm, $T, $K, true);
+
+        // Use dynamic truncation as per [RFC4226] Section 5.3
+        $offset = ord($hash[-1]) & 0xF;
+
+        $binaryCode = ((ord($hash[$offset]) & 0x7F) << 24)
+            | ((ord($hash[$offset + 1]) & 0xFF) << 16)
+            | ((ord($hash[$offset + 2]) & 0xFF) << 8)
+            | (ord($hash[$offset + 3]) & 0xFF);
+
+        return sprintf(
+            '%0' . $this->Digits . 's',
+            substr((string) $binaryCode, -$this->Digits),
+        );
+    }
+}

tests/unit/Toolkit/Http/HttpUtilTest.php

@@ -423,4 +423,58 @@ public static function replaceQueryProvider(): array
             ],
         ];
     }
+
+    /**
+     * @dataProvider getTOTPProvider
+     *
+     * @param HttpUtil::ALGORITHM_* $algorithm
+     */
+    public function testGetTOTP(
+        string $expected,
+        string $key,
+        int $digits = 6,
+        string $algorithm = HttpUtil::ALGORITHM_SHA1,
+        int $timeStep = 30,
+        int $secondsSinceStartTime = 0
+    ): void {
+        $startTime = time() - $secondsSinceStartTime;
+        $this->assertSame(
+            $expected,
+            HttpUtil::getTOTP($key, $digits, $algorithm, $timeStep, $startTime),
+        );
+    }
+
+    /**
+     * @return array<array{string,string,2?:int,3?:HttpUtil::ALGORITHM_*,4?:int,5?:int}>
+     */
+    public static function getTOTPProvider(): array
+    {
+        // 12345678901234567890 (20 bytes)
+        $key1 = 'GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ';
+        // 12345678901234567890123456789012 (32 bytes)
+        $key256 = 'GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZA====';
+        // 1234567890123456789012345678901234567890123456789012345678901234 (64 bytes)
+        $key512 = 'GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQGEZDGNA=';
+
+        return [
+            ['94287082', $key1, 8, HttpUtil::ALGORITHM_SHA1, 30, 59],
+            ['46119246', $key256, 8, HttpUtil::ALGORITHM_SHA256, 30, 59],
+            ['90693936', $key512, 8, HttpUtil::ALGORITHM_SHA512, 30, 59],
+            ['07081804', $key1, 8, HttpUtil::ALGORITHM_SHA1, 30, 1111111109],
+            ['68084774', $key256, 8, HttpUtil::ALGORITHM_SHA256, 30, 1111111109],
+            ['25091201', $key512, 8, HttpUtil::ALGORITHM_SHA512, 30, 1111111109],
+            ['14050471', $key1, 8, HttpUtil::ALGORITHM_SHA1, 30, 1111111111],
+            ['67062674', $key256, 8, HttpUtil::ALGORITHM_SHA256, 30, 1111111111],
+            ['99943326', $key512, 8, HttpUtil::ALGORITHM_SHA512, 30, 1111111111],
+            ['89005924', $key1, 8, HttpUtil::ALGORITHM_SHA1, 30, 1234567890],
+            ['91819424', $key256, 8, HttpUtil::ALGORITHM_SHA256, 30, 1234567890],
+            ['93441116', $key512, 8, HttpUtil::ALGORITHM_SHA512, 30, 1234567890],
+            ['69279037', $key1, 8, HttpUtil::ALGORITHM_SHA1, 30, 2000000000],
+            ['90698825', $key256, 8, HttpUtil::ALGORITHM_SHA256, 30, 2000000000],
+            ['38618901', $key512, 8, HttpUtil::ALGORITHM_SHA512, 30, 2000000000],
+            ['65353130', $key1, 8, HttpUtil::ALGORITHM_SHA1, 30, 20000000000],
+            ['77737706', $key256, 8, HttpUtil::ALGORITHM_SHA256, 30, 20000000000],
+            ['47863826', $key512, 8, HttpUtil::ALGORITHM_SHA512, 30, 20000000000],
+        ];
+    }
 }