Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 2 additions & 0 deletions docs/changelogs/v4.7.7.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
6 changes: 6 additions & 0 deletions docs/installation/upgrade_477.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Comment thread
michalsn marked this conversation as resolved.
Resolved

## Breaking Enhancements

## Project Files
Expand Down
18 changes: 17 additions & 1 deletion docs/libraries/caching.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:

Expand Down
30 changes: 30 additions & 0 deletions system/Cache/Handlers/FileHandler.php
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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);
Expand Down
Loading
Loading