feat: strict FF3/FF3-1 tweak — no silent zero-fill (matches NIST + BC + rust)

Configuration now parses the optional hex 'tweak' field and exposes it
to the Client. FPE dispatch in protect/access requires an exact-length
tweak for FF3 (8 bytes) and FF3-1 (7 bytes); missing or wrong length
throws with the canonical spec message. FF1 stays permissive — empty
tweak is still fine per NIST SP 800-38G. Silent zero-fill is gone —
any two configs that omit a tweak no longer share an FPE keyspace
under the same key.

Author: lgutschow

src/Cyphera.php

@@ -55,13 +55,21 @@ private function __construct(array $config)
                 $this->headerIndex[$header] = $name;
             }
 
+            $tweakHex = $cfg['tweak'] ?? null;
+            $tweak = (is_string($tweakHex) && $tweakHex !== '') ? hex2bin($tweakHex) : null;
+            if ($tweakHex !== null && $tweak === false) {
+                throw new \InvalidArgumentException("configuration error: invalid hex tweak in '{$name}'");
+            }
+
             $this->configurations[$name] = [
+                'name' => $name,
                 'engine' => $cfg['engine'] ?? 'ff1',
                 'alphabet' => self::resolveAlphabet($cfg['alphabet'] ?? null),
                 'key_ref' => $cfg['key_ref'] ?? null,
                 'header' => $header,
                 'header_enabled' => $headerEnabled,
                 'header_length' => (int)($cfg['header_length'] ?? 3),
+                'tweak' => $tweak,
                 'pattern' => $cfg['pattern'] ?? null,
                 'algorithm' => $cfg['algorithm'] ?? 'sha256',
             ];
@@ -163,6 +171,22 @@ private function accessWithConfiguration(string $protectedValue, array $configur
 
     // ── FPE ──
 
+    /**
+     * Require an exact-length tweak for FF3 / FF3-1. Missing or wrong-length
+     * tweaks are a hard error — no silent zero-fill. FF1 tweak is optional
+     * per NIST SP 800-38G and is handled separately.
+     */
+    private static function requireTweak(array $configuration, int $expectedLen, string $label): string
+    {
+        $tweak = $configuration['tweak'] ?? null;
+        if (!is_string($tweak) || strlen($tweak) !== $expectedLen) {
+            throw new \InvalidArgumentException(
+                "configuration '{$configuration['name']}' is missing required 'tweak' ({$label} needs {$expectedLen} bytes)"
+            );
+        }
+        return $tweak;
+    }
+
     private static bool $ff3Warned = false;
 
     /** Emit the FF3 deprecation warning to stderr, once per process. */
@@ -187,11 +211,11 @@ private function protectFpe(string $value, array $configuration): string
 
         if ($configuration['engine'] === 'ff3') {
             $this->warnFf3Deprecated();
-            $cipher = new FF3($key, str_repeat("\x00", 8), $alphabet);
+            $cipher = new FF3($key, self::requireTweak($configuration, 8, 'FF3'), $alphabet);
         } elseif ($configuration['engine'] === 'ff31') {
-            $cipher = new FF31($key, str_repeat("\x00", 7), $alphabet);
+            $cipher = new FF31($key, self::requireTweak($configuration, 7, 'FF3-1'), $alphabet);
         } else {
-            $cipher = new FF1($key, '', $alphabet);
+            $cipher = new FF1($key, $configuration['tweak'] ?? '', $alphabet);
         }
         $encrypted = $cipher->encrypt($encryptable);
 
@@ -224,11 +248,11 @@ private function accessFpe(string $rawCiphertext, array $configuration): string
 
         if ($configuration['engine'] === 'ff3') {
             $this->warnFf3Deprecated();
-            $cipher = new FF3($key, str_repeat("\x00", 8), $alphabet);
+            $cipher = new FF3($key, self::requireTweak($configuration, 8, 'FF3'), $alphabet);
         } elseif ($configuration['engine'] === 'ff31') {
-            $cipher = new FF31($key, str_repeat("\x00", 7), $alphabet);
+            $cipher = new FF31($key, self::requireTweak($configuration, 7, 'FF3-1'), $alphabet);
         } else {
-            $cipher = new FF1($key, '', $alphabet);
+            $cipher = new FF1($key, $configuration['tweak'] ?? '', $alphabet);
         }
         $decrypted = $cipher->decrypt($encryptable);
 

tests/CypheraTest.php

@@ -129,4 +129,53 @@ public function testTwoArgAccessOnIrreversibleConfigurationRaises(): void
         $this->expectExceptionMessage("cannot reverse 'ssn_mask' — mask is irreversible");
         $c->access($masked, 'ssn_mask');
     }
+
+    // ── Strict FF3 / FF3-1 tweak (no silent zero-fill) ──
+
+    public function testFf3MissingTweakRaises(): void
+    {
+        $c = Cyphera::fromConfig([
+            'configurations' => [
+                'ff3_no_tweak' => ['engine' => 'ff3', 'alphabet' => 'digits', 'key_ref' => 'k', 'header' => 'T03'],
+            ],
+            'keys' => ['k' => ['material' => '2B7E151628AED2A6ABF7158809CF4F3C']],
+        ]);
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage("configuration 'ff3_no_tweak' is missing required 'tweak' (FF3 needs 8 bytes)");
+        $c->protect('123456789', 'ff3_no_tweak');
+    }
+
+    public function testFf31MissingTweakRaises(): void
+    {
+        $c = Cyphera::fromConfig([
+            'configurations' => [
+                'ff31_no_tweak' => ['engine' => 'ff31', 'alphabet' => 'digits', 'key_ref' => 'k', 'header' => 'T04'],
+            ],
+            'keys' => ['k' => ['material' => '2B7E151628AED2A6ABF7158809CF4F3C']],
+        ]);
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage("configuration 'ff31_no_tweak' is missing required 'tweak' (FF3-1 needs 7 bytes)");
+        $c->protect('123456789', 'ff31_no_tweak');
+    }
+
+    public function testFf3WithExplicitTweakRoundtrips(): void
+    {
+        $c = Cyphera::fromConfig([
+            'configurations' => [
+                'ff3_ok' => ['engine' => 'ff3', 'alphabet' => 'digits', 'key_ref' => 'k', 'header' => 'T05', 'tweak' => 'D8E7920AFA330A73'],
+            ],
+            'keys' => ['k' => ['material' => '2B7E151628AED2A6ABF7158809CF4F3C']],
+        ]);
+        $protected = $c->protect('123456789', 'ff3_ok');
+        $this->assertNotSame('123456789', $protected);
+        $this->assertSame('123456789', $c->access($protected));
+    }
+
+    public function testFf1MissingTweakStillWorks(): void
+    {
+        // FF1 tweak stays optional per NIST SP 800-38G.
+        $c = self::createClient();
+        $protected = $c->protect('123456789', 'ssn'); // ssn is ff1 with no tweak
+        $this->assertSame('123456789', $c->access($protected));
+    }
 }