Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:128395
Feedback-ID: id4f946ef:Fastmail
Precedence: list
MIME-Version: 1.0
Date: Tue, 05 Aug 2025 11:14:26 +0200
To: internals@lists.php.net
Message-ID: <929642ac-2628-4bdb-acbd-7268231a6e41@app.fastmail.com>
Subject: [PHP-DEV] allowed_classes_callback option for unserialize()
Content-Type: multipart/alternative;
 boundary=fcc5eaa9933e46018c19d392fdba3ee2
From: langemeijer@php.net ("Casper Langemeijer")

--fcc5eaa9933e46018c19d392fdba3ee2
Content-Type: text/plain
Content-Transfer-Encoding: 7bit

I'm writing a this email to propose adding allowed_classes_callback option to unserialize(). 

The class name as parsed from the serialized string is passed as a parameter to the callback, it should return a boolean. true would allow the class, false would block it. This blocks classes the same way 'allowed_classes' would, but by callback instead. The callback will be triggered *after* allowed_classes is evaluated (if present). Blocking will have the same effect as allowed_classes, using __PHP_Incomplete_Class.

This callback would solve a few problems where allowed_classes is not sufficient:

- This would also allow for fixing legacy applications where it is not exactly clear what is being unserialized. In my use-case the callable returns a true value but a E_USER_DEPRECATION is triggered. This way data can be collected about what classes to allow through monitoring these deprecations, providing a non-disrupting way to secure unserialize calls. This is especially helpful in very generic unserialize usages like caches.

- It would allow for an is_subclass_of() check where for example an interface can be added to classes that are safe to get unserialized. Current allowed_classes array only matches the exact class, not it's children. 

Note that these problems are not resolvable by using unserialize_callback_func because that call only happens for unloaded classes, where the PHP Object Injection vulnerability https://owasp.org/www-community/vulnerabilities/PHP_Object_Injection affects classes that might already have been loaded.

In de pull request Jakub wrote:
> Personally I don't see any issue here and it seems quite self contained and small so I wouldn't mind to get it merged without RFC. It might be worth to email internals first to double check that there are no objections first.

Out of scope: I understand that __PHP_Incomplete_Class is not very 2025. Adding an option throw_for_unknown_classes has been suggested on this list. I'm happy to implement that, but for now I'd like to keep it at allowed_classes_callback.

Feedback is very much appreciated.

The change and some more details live here: https://github.com/php/php-src/pull/19087


--fcc5eaa9933e46018c19d392fdba3ee2
Content-Type: text/html
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE html><html><head><title></title></head><body><div>I'm writing =
a this email to propose adding allowed_classes_callback option to unseri=
alize().&nbsp;</div><div><br></div><div>The class name as parsed from th=
e serialized string is passed as a parameter to the callback, it should =
return a boolean. true would allow the class, false would block it. This=
 blocks classes the same way 'allowed_classes' would, but by callback in=
stead. The callback will be triggered *after* allowed_classes is evaluat=
ed (if present). Blocking will have the same effect as allowed_classes, =
using __PHP_Incomplete_Class.</div><div><br></div><div>This callback wou=
ld solve a few problems where allowed_classes is not sufficient:</div><d=
iv><br></div><div>- This would also allow for fixing legacy applications=
 where it is not exactly clear what is being unserialized. In my use-cas=
e the callable returns a true value but a E_USER_DEPRECATION is triggere=
d. This way data can be collected about what classes to allow through mo=
nitoring these deprecations, providing a non-disrupting way to secure un=
serialize calls. This is especially helpful in very generic unserialize =
usages like caches.</div><div><br></div><div>- It would allow for an is_=
subclass_of() check where for example an interface can be added to class=
es that are safe to get unserialized. Current allowed_classes array only=
 matches the exact class, not it's children.&nbsp;</div><div><br></div><=
div>Note that these problems are not resolvable by using unserialize_cal=
lback_func because that call only happens for unloaded classes, where th=
e PHP Object Injection vulnerability <a href=3D"https://owasp.org/www-co=
mmunity/vulnerabilities/PHP_Object_Injection">https://owasp.org/www-comm=
unity/vulnerabilities/PHP_Object_Injection</a> affects classes that migh=
t already have been loaded.</div><div><br></div><div>In de pull request =
Jakub wrote:</div><blockquote type=3D"cite"><div>Personally I don't see =
any issue here and it seems quite self contained and small so I wouldn't=
 mind to get it merged without RFC. It might be worth to email internals=
 first to double check that there are no objections first.</div></blockq=
uote><div><br></div><div>Out of scope: I understand that __PHP_Incomplet=
e_Class is not very 2025. Adding an option throw_for_unknown_classes has=
 been suggested on this list. I'm happy to implement that, but for now I=
'd like to keep it at allowed_classes_callback.</div><div><br></div><div=
>Feedback is very much appreciated.</div><div><br></div><div>The change =
and some more details live here: <a href=3D"https://github.com/php/php-s=
rc/pull/19087">https://github.com/php/php-src/pull/19087</a></div><div><=
br></div><div><br></div></body></html>
--fcc5eaa9933e46018c19d392fdba3ee2--