diff --git a/docs/changelogs/v4.7.7.md b/docs/changelogs/v4.7.7.md index 6623106d9e5e..a1bfb1b6ff51 100644 --- a/docs/changelogs/v4.7.7.md +++ b/docs/changelogs/v4.7.7.md @@ -6,6 +6,8 @@ Release Date: Unreleased ## BREAKING +- **Cache:** `FileHandler::validateKey()` now rejects `/`, `\` and null bytes in the cache item file name, independently of `Config\Cache::$reservedCharacters`, so a cache key can no longer point outside the cache directory when that setting is relaxed. See [File Cache Rejects Directory Separators](../installation/upgrade_477.md#file-cache-rejects-directory-separators) for migration instructions. + ## Message Changes - Added the `HTTP.invalidFileName` language string. diff --git a/docs/installation/upgrade_477.md b/docs/installation/upgrade_477.md index 082aa62c50e8..bfa87dc80d72 100644 --- a/docs/installation/upgrade_477.md +++ b/docs/installation/upgrade_477.md @@ -10,6 +10,12 @@ Please refer to the upgrade instructions corresponding to your installation meth ## Breaking Changes +### File Cache Rejects Directory Separators + +For security reasons, `FileHandler::validateKey()` now rejects `/`, `\` and null bytes in the cache item file name, independently of the `Config\Cache::$reservedCharacters` setting. A cache key can no longer point outside the cache directory when that setting is relaxed. + +With the default configuration most applications are unaffected, because `/`, `\` and `:` are already reserved characters. Applications that emptied `$reservedCharacters` to share one key namespace between handlers and used directory separators in File cache keys now get an `InvalidArgumentException`. Build keys from identifiers with a controlled format, or hash the input, instead of relaxing `$reservedCharacters`. See [Caching](../libraries/caching.md). + ## Breaking Enhancements ## Project Files diff --git a/docs/libraries/caching.md b/docs/libraries/caching.md index b9109dcdd4ca..d89313718864 100644 --- a/docs/libraries/caching.md +++ b/docs/libraries/caching.md @@ -52,10 +52,26 @@ The default number of seconds to save items when none is specified. WARNING: This is not used by framework handlers where 60 seconds is hard-coded, but may be useful to projects and modules. This will replace the hard-coded value in a future release. +### $reservedCharacters + +A string of characters that are not allowed in cache keys or tags. Handlers throw an `InvalidArgumentException` when a key contains one of them. The default, `{}()/\@:`, is required for PSR-6 compliance. + +Relaxing `$reservedCharacters` relaxes key validation for every cache handler. The File handler still rejects `/`, `\` and null bytes in the resulting file name, so a cache key cannot point outside the cache directory. The characters left in `$reservedCharacters` still keep keys from being interpreted differently by a handler or by the file system. + +On Windows, keep `:` reserved: it separates an NTFS alternate data stream, so a key such as `file:stream` refers to a stream of a file in the cache directory rather than to a new cache item. + +Do not use unvalidated user input directly as a cache key. Build keys from identifiers with a controlled format, or hash the input: + +```php +$key = 'search_' . hash('sha256', $userInput); +``` + ### $file This is an array of settings specific to the **File** handler to determine how it should save the cache files. +Cache files whose names start with a dot are not fully supported by the File handler: `getCacheInfo()` does not report them, `deleteMatching()` wildcard patterns do not match them, and `clean()` / `cache:clear` do not delete them. Avoid keys and prefixes that produce a leading dot. + ### $memcached This is an array of servers that will be used when using the **Memcached** handler. @@ -310,7 +326,7 @@ var_dump($cache->getMetadata('my_cached_item')); - **Return type**: `string` -This method is used by handler methods to check that keys are valid. It will throw an `InvalidArgumentException` for non-strings, invalid characters, and empty lengths. +This method is used by handler methods to check that keys are valid. It will throw an `InvalidArgumentException` for non-strings, invalid characters, and empty lengths. The File handler additionally rejects `/`, `\` and null bytes in the resulting file name, even when `Config\Cache::$reservedCharacters` is relaxed. Example: diff --git a/system/Cache/Handlers/FileHandler.php b/system/Cache/Handlers/FileHandler.php index 9c00998c1f85..cc24df2c1219 100644 --- a/system/Cache/Handlers/FileHandler.php +++ b/system/Cache/Handlers/FileHandler.php @@ -14,6 +14,7 @@ namespace CodeIgniter\Cache\Handlers; use CodeIgniter\Cache\Exceptions\CacheException; +use CodeIgniter\Exceptions\InvalidArgumentException; use CodeIgniter\I18n\Time; use Config\Cache; use FilesystemIterator; @@ -76,6 +77,35 @@ public function initialize(): void { } + /** + * Validates a cache key and returns the file name the item is stored under. + * + * The file name must not contain a directory separator or a null byte, so a + * cache item can never be written outside the cache directory, even when + * `Config\Cache::$reservedCharacters` is relaxed. Other characters are left + * to the configured reserved characters, because rejecting characters that + * are valid in file names on some platforms would break existing keys. + * + * @param mixed $key The key to validate + * @param string $prefix Optional prefix to include in length calculations + * + * @throws InvalidArgumentException When $key is not valid or the resulting + * file name contains a directory separator + * or a null byte + */ + public static function validateKey($key, $prefix = ''): string + { + // Parent validation also hashes keys that exceed MAX_KEY_LENGTH, so + // validate the returned file name and not the raw key. + $key = parent::validateKey($key, $prefix); + + if (strpbrk($key, '/\\') !== false || str_contains($key, "\0")) { + throw new InvalidArgumentException('Cache key cannot contain directory separators or null bytes.'); + } + + return $key; + } + public function get(string $key): mixed { $key = static::validateKey($key, $this->prefix); diff --git a/tests/system/Cache/Handlers/FileHandlerTest.php b/tests/system/Cache/Handlers/FileHandlerTest.php index 310b5a7ebce7..5a0e057bb349 100644 --- a/tests/system/Cache/Handlers/FileHandlerTest.php +++ b/tests/system/Cache/Handlers/FileHandlerTest.php @@ -16,6 +16,7 @@ use CodeIgniter\Cache\CacheFactory; use CodeIgniter\Cache\Exceptions\CacheException; use CodeIgniter\CLI\CLI; +use CodeIgniter\Exceptions\InvalidArgumentException; use CodeIgniter\I18n\Time; use Config\Cache; use PHPUnit\Framework\Attributes\DataProvider; @@ -30,6 +31,7 @@ final class FileHandlerTest extends AbstractHandlerTestCase { private static string $directory = 'FileHandler'; private Cache $config; + private string $originalReservedCharacters; protected function setUp(): void { @@ -39,6 +41,9 @@ protected function setUp(): void helper('filesystem'); } + // Restored in tearDown() so a relaxed setting cannot leak into another test. + $this->originalReservedCharacters = config('Cache')->reservedCharacters; + // Initialize path $this->config = new Cache(); $this->config->file['storePath'] .= self::$directory; @@ -52,6 +57,10 @@ protected function setUp(): void protected function tearDown(): void { + if (isset($this->originalReservedCharacters)) { + config('Cache')->reservedCharacters = $this->originalReservedCharacters; + } + parent::tearDown(); if (is_dir($this->config->file['storePath'])) { @@ -504,4 +513,358 @@ public function testReconnect(): void { $this->assertTrue($this->handler->reconnect()); } + + #[DataProvider('provideValidateKeyRejectsSeparatorsAndNullBytes')] + public function testValidateKeyRejectsSeparatorsAndNullBytes(string $key, string $prefix): void + { + // Multi-store setups often empty this setting to share keys between + // handlers, which must not weaken the file handler's own validation. + config('Cache')->reservedCharacters = ''; + + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('Cache key cannot contain directory separators or null bytes.'); + + FileHandler::validateKey($key, $prefix); + } + + /** + * @return iterable + */ + public static function provideValidateKeyRejectsSeparatorsAndNullBytes(): iterable + { + yield 'parent traversal' => ['../evil', '']; + + yield 'nested traversal' => ['sub/../../evil', '']; + + yield 'backslash traversal' => ['..\\evil', '']; + + yield 'forward slash separator' => ['sub/key', '']; + + yield 'backslash separator' => ['sub\\key', '']; + + yield 'forward slash only' => ['/', '']; + + yield 'backslash only' => ['\\', '']; + + yield 'null byte only' => ["\0", '']; + + yield 'null byte inside key' => ["sub\0key", '']; + + yield 'parent traversal in prefix' => ['key', '../']; + + yield 'backslash traversal in prefix' => ['key', '..\\']; + + yield 'null byte in prefix' => ['key', "a\0b"]; + + yield 'forward slash in prefix' => ['key', 'pre/']; + + yield 'absolute path' => ['/etc/passwd', '']; + + yield 'trailing slash in key' => ['key/', '']; + + yield 'mixed separators' => ['a/b\\c', '']; + + yield 'backslash and zero at start' => ['\\0key', '']; + + yield 'backslash and zero at end' => ['key\\0', '']; + + yield 'single slash prefix' => ['key', '/']; + + yield 'backslash zero prefix' => ['key', '\\0']; + + yield 'escaped traversal in prefix' => ['key', '..\\\\..\\\\']; + } + + #[DataProvider('provideValidateKeyAcceptsHarmlessNames')] + public function testValidateKeyAcceptsHarmlessNames(string $key, string $prefix, string $expected): void + { + config('Cache')->reservedCharacters = ''; + + $this->assertSame($expected, FileHandler::validateKey($key, $prefix)); + } + + /** + * @return iterable + */ + public static function provideValidateKeyAcceptsHarmlessNames(): iterable + { + yield 'plain key' => ['valid_key', '', 'valid_key']; + + yield 'dots before extension' => ['foo..json', '', 'foo..json']; + + yield 'dots inside name' => ['user..settings', '', 'user..settings']; + + yield 'leading dots' => ['..item', '', '..item']; + + yield 'trailing dots' => ['item..', '', 'item..']; + + yield 'double leading dots' => ['..foo', '', '..foo']; + + yield 'three dots' => ['...', '', '...']; + + yield 'single dot' => ['.', '', '.']; + + yield 'two dots' => ['..', '', '..']; + + yield 'dots with trailing space' => ['.. ', '', '.. ']; + + yield 'spaces and dots' => [' . ', '', ' . ']; + + yield 'colon character' => ['test:stream', '', 'test:stream']; + + yield 'drive letter' => ['C:file', '', 'C:file']; + + yield 'dot prefix' => ['key', '.', '.key']; + + yield 'two dots prefix' => ['item', '..', '..item']; + + yield 'three dots prefix' => ['key', '...', '...key']; + + yield 'two dots and a space prefix' => ['key', '.. ', '.. key']; + + yield 'spaces around a dot prefix' => ['key', ' . ', ' . key']; + + yield 'space only prefix' => ['key', ' ', ' key']; + + yield 'spaces only prefix' => ['key', ' ', ' key']; + + yield 'dot but not dot-only prefix' => ['key', '.app', '.appkey']; + + yield 'colon in prefix' => ['key', 'app:', 'app:key']; + + yield 'underscore in prefix' => ['key', 'app_', 'app_key']; + + yield 'non-ASCII key' => ['zażółć_gęślą_jaźń', '', 'zażółć_gęślą_jaźń']; + } + + public function testValidateKeyHashesLongKeyBeforeValidatingName(): void + { + config('Cache')->reservedCharacters = ''; + + // A key of nothing but dots used to be rejected before hashing. + $dots = str_repeat('.', 500); + $this->assertSame(md5($dots), FileHandler::validateKey($dots)); + + // The parent hashes the key before the file name is validated. + $key = str_repeat('a', 300) . '/evil'; + $this->assertSame(md5($key), FileHandler::validateKey($key)); + + $longKey = str_repeat('a', 300); + $this->assertSame('pre_' . md5($longKey), FileHandler::validateKey($longKey, 'pre_')); + } + + public function testValidateKeyKeepsMaxLengthBoundary(): void + { + $atLimit = str_repeat('a', 255); + $this->assertSame($atLimit, FileHandler::validateKey($atLimit)); + + // One byte over the limit is hashed, so the file name stays short. + $overLimit = str_repeat('a', 256); + $this->assertSame(md5($overLimit), FileHandler::validateKey($overLimit)); + + // The prefix is counted in the limit but is never hashed. + $prefixKey = str_repeat('a', 251); + $this->assertSame('pre_' . $prefixKey, FileHandler::validateKey($prefixKey, 'pre_')); + + $prefixOver = str_repeat('a', 252); + $this->assertSame('pre_' . md5($prefixOver), FileHandler::validateKey($prefixOver, 'pre_')); + } + + public function testValidateKeyRejectsTraversalInPrefixOfHashedKey(): void + { + config('Cache')->reservedCharacters = ''; + + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('Cache key cannot contain directory separators or null bytes.'); + + // The prefix is not hashed, so a separator in it must still be rejected. + FileHandler::validateKey(str_repeat('a', 300), '../'); + } + + public function testValidateKeyHashesLongKeyWithDotPrefix(): void + { + config('Cache')->reservedCharacters = ''; + + $key = str_repeat('a', 300); + + $this->assertSame('.' . md5($key), FileHandler::validateKey($key, '.')); + } + + public function testValidateKeyRejectsEmptyKey(): void + { + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('Cache key cannot be empty.'); + + FileHandler::validateKey(''); + } + + public function testValidateKeyRejectsNonStringKey(): void + { + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('Cache key must be a string'); + + FileHandler::validateKey(42); + } + + public function testValidateKeyRejectsReservedCharacters(): void + { + // Set the default explicitly: this test documents the default reserved + // characters, so it must not depend on the configured app value. + config('Cache')->reservedCharacters = '{}()/\@:'; + + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('Cache key contains reserved characters {}()/\@:'); + + FileHandler::validateKey('sub/key'); + } + + #[DataProvider('provideValidateKeyRejectsEveryDefaultReservedCharacter')] + public function testValidateKeyRejectsEveryDefaultReservedCharacter(string $char): void + { + config('Cache')->reservedCharacters = '{}()/\@:'; + + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('Cache key contains reserved characters {}()/\@:'); + + FileHandler::validateKey('a' . $char . 'b'); + } + + /** + * @return iterable + */ + public static function provideValidateKeyRejectsEveryDefaultReservedCharacter(): iterable + { + return [ + ['{'], + ['}'], + ['('], + [')'], + ['/'], + ['\\'], + ['@'], + [':'], + ]; + } + + public function testValidateKeyAcceptsValidKeyWithDefaultConfig(): void + { + $this->assertSame('valid_key', FileHandler::validateKey('valid_key')); + } + + public function testValidateKeyAcceptsFalsyStringKey(): void + { + // "0" is falsy but a perfectly valid cache key. + $this->assertSame('0', FileHandler::validateKey('0')); + } + + public function testValidateKeySuccessWithPrefix(): void + { + $this->assertSame('prefixvalid_key', FileHandler::validateKey('valid_key', 'prefix')); + } + + public function testDottedKeySurvivesFullLifecycle(): void + { + $this->assertTrue($this->handler->save('..item', 'value')); + $this->assertSame('value', $this->handler->get('..item')); + $this->assertTrue($this->handler->delete('..item')); + } + + public function testDottedDirectoryKeyIsNotWritten(): void + { + // No regression from before the pull request: the path resolves to a + // directory, so is_file() and fopen() keep the item from being stored. + $this->assertFalse($this->handler->save('..', 'value')); + $this->assertNull($this->handler->get('..')); + $this->assertFalse($this->handler->delete('..')); + } + + public function testIncrementRejectsTraversalKey(): void + { + config('Cache')->reservedCharacters = ''; + + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('Cache key cannot contain directory separators or null bytes.'); + + $this->handler->increment('../counter'); + } + + public function testPublicApiRejectsSeparatorWithDefaultConfig(): void + { + config('Cache')->reservedCharacters = '{}()/\@:'; + + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('Cache key contains reserved characters {}()/\@:'); + + $this->handler->save('../evil', 'value'); + } + + public function testDotPrefixFromConfigIsHandledSafelyByPublicApi(): void + { + config('Cache')->reservedCharacters = ''; + + $config = new Cache(); + $config->prefix = '..'; + $config->file['storePath'] = $this->config->file['storePath']; + + $handler = CacheFactory::getHandler($config, 'file'); + + $this->assertTrue($handler->save('key', 'value')); + $this->assertSame('value', $handler->get('key')); + $this->assertTrue($handler->delete('key')); + } + + /** + * A relaxed reserved character list must not turn the public API into a way + * to read or write files outside the cache directory. + */ + public function testTraversalThroughPublicApiDoesNotLeaveCacheDirectory(): void + { + // The weakened configuration is the very scenario the separators check + // has to cover, so it must not be rejected by the reserved list instead. + config('Cache')->reservedCharacters = ''; + + $victim = dirname($this->config->file['storePath']) . DIRECTORY_SEPARATOR . 'victim_' . uniqid('', true); + $this->assertNotFalse(file_put_contents($victim, 'original')); + + try { + foreach (['../' . basename($victim), '..\\' . basename($victim)] as $key) { + try { + $this->handler->save($key, 'overwritten'); + $this->fail('save() accepted the traversal key "' . $key . '".'); + } catch (InvalidArgumentException $e) { + $this->assertSame('Cache key cannot contain directory separators or null bytes.', $e->getMessage()); + } + + try { + $this->handler->delete($key); + $this->fail('delete() accepted the traversal key "' . $key . '".'); + } catch (InvalidArgumentException $e) { + $this->assertSame('Cache key cannot contain directory separators or null bytes.', $e->getMessage()); + } + + try { + $this->handler->getMetaData($key); + $this->fail('getMetaData() accepted the traversal key "' . $key . '".'); + } catch (InvalidArgumentException $e) { + $this->assertSame('Cache key cannot contain directory separators or null bytes.', $e->getMessage()); + } + } + + $this->assertSame('original', file_get_contents($victim)); + } finally { + @unlink($victim); + } + } + + #[RequiresOperatingSystem('Linux|Darwin')] + public function testWeakenedReservedCharactersAllowsColonInFileName(): void + { + // Rejecting separators must not reject characters that are valid in + // file names, otherwise relaxing the reserved list would do nothing. + config('Cache')->reservedCharacters = ''; + + $this->assertTrue($this->handler->save('test:stream', 'value')); + $this->assertSame('value', $this->handler->get('test:stream')); + $this->assertTrue($this->handler->delete('test:stream')); + } }