Hello,
I would like to introduce a TLS Session Resumption Support for Streams RFC
that is part of my stream evolution work (PHP Foundation project funded by
Sovereign Tech Fund) :
https://wiki.php.net/rfc/tls_session_resumption_api
Kind regards,
Jakub
I would like to introduce a TLS Session Resumption Support for Streams
RFC that is part of my stream evolution work (PHP Foundation project
funded by Sovereign Tech Fund) :
I have a few questions/comments:
| Client-Only Options:
|
| session_data (string) - Binary session data from a previous connection
| to resume. Data must be from a session_new_cb callback.
...
| session_new_cb (callable) - Callback invoked when a new session is
| established.
| ...
| - $sessionData: Serialized session (OpenSSL format via
| i2d_SSL_SESSION)
-
Would it be possible to ensure this data is from the callback?
-
I am asking mostly whether we think it is wise that this internal
openssl data is exposed to the user, for which this is mainly an opaque
blob of data — or in other words, an implementation detail of OpenSSL.
| Client Behavior
| ...
| 3. Server-only options (''session_get_cb'', ''session_remove_cb'',
| ''session_cache'', ''num_tickets'', etc.) are ignored
I don't think it is wise to ignore these, and I would prefer an error
situation to be caused by supplying options that have no effect.
| Server Behaviour
| ...
| With External Cache (session_get_cb provided):
| - session_new_cb becomes required (E_WARNING if missing)
| - session_context_id becomes required (E_WARNING if missing)
If is is required, it shouldn't be a warning as it is a programming
error for which an Error-type exception ought to be thrown. On many
occasions warnings appear in a logging black hole.
| - session_cache_size and session_timeout are ignored (application
| manages storage)
For similar reasons, I don't think these should be just ignored either
(again: it's a programming error).
| Backward Incompatible Changes
| ...
| - New options are ignored in older PHP versions (standard stream
| context behavior)
That's not a Backward Compatibility issue, but a Forward Compatibility
issue.
| Potential Considerations:
| ...
| - The new callbacks use resources passed as parameters - these must
| not be stored beyond the callback scope (documented limitation)
Would it be possible to do this without introducing new
resources/resource types?
cheers,
Derick
--
https://derickrethans.nl | https://xdebug.org | https://dram.io
Author of Xdebug. Like it? Consider supporting me: https://xdebug.org/support
mastodon: @derickr@phpc.social @xdebug@phpc.social
Hi,
I would like to introduce a TLS Session Resumption Support for Streams
RFC that is part of my stream evolution work (PHP Foundation project
funded by Sovereign Tech Fund) :
I have just done a significant update (version 0.2 of RFC) that introduces
OpenSSLSession class and re-implementation of the SSL_CTX creation (mainly
for server) and some other changes.
I have a few questions/comments:
| Client-Only Options:
|
| session_data (string) - Binary session data from a previous connection
| to resume. Data must be from a session_new_cb callback.
...
| session_new_cb (callable) - Callback invoked when a new session is
| established.
| ...
| - $sessionData: Serialized session (OpenSSL format via
| i2d_SSL_SESSION)
- Would it be possible to ensure this data is from the callback?
Yes, I introduced OpenSSLSession which represent the actual session so
sessionData can be only instance of this class.
- I am asking mostly whether we think it is wise that this internal
openssl data is exposed to the user, for which this is mainly an opaque
blob of data — or in other words, an implementation detail of OpenSSL.
It was ASN.1 DER representation but I agree that using object is better
which I introduced in the update. It also allows serialization /
deserialization (import / export) from DER and PEM.
Just a note that constant (not enum) is used because that constant already
exist and it's used in other function so adding enum would be out of scope
and inconsistent here (please don't ask for it :) ).
| Client Behavior
| ...
| 3. Server-only options (''session_get_cb'', ''session_remove_cb'',
| ''session_cache'', ''num_tickets'', etc.) are ignoredI don't think it is wise to ignore these, and I would prefer an error
situation to be caused by supplying options that have no effect.
There is now error thrown for some illogical combination that can be
checked easily. Unknown stream options are always ignored but I agree that
in some cases it could be confusing so throwing ValueError there.
| Server Behaviour
| ...
| With External Cache (session_get_cb provided):
| - session_new_cb becomes required (E_WARNING if missing)
| - session_context_id becomes required (E_WARNING if missing)If is is required, it shouldn't be a warning as it is a programming
error for which an Error-type exception ought to be thrown. On many
occasions warnings appear in a logging black hole.
This has been changed to exceptions
| - session_cache_size and session_timeout are ignored (application
| manages storage)For similar reasons, I don't think these should be just ignored either
(again: it's a programming error).
As I noted all unknown stream options are ignored. This has been always the
case. This would require redesign of stream option and big BC break to
change it. I removed this note from RFC because it's just how things work
there. I also addressed some missing cases that now throws but can't really
go any further as it would make things inconsistent with the rest of the
code.
| Backward Incompatible Changes
| ...
| - New options are ignored in older PHP versions (standard stream
| context behavior)That's not a Backward Compatibility issue, but a Forward Compatibility
issue.
I removed that note.
| Potential Considerations:
| ...
| - The new callbacks use resources passed as parameters - these must
| not be stored beyond the callback scope (documented limitation)Would it be possible to do this without introducing new
resources/resource types?
This was meant for provided stream but it can be actually used so I removed
it.
Cheers
Jakub
Hi
I would like to introduce a TLS Session Resumption Support for Streams RFC
that is part of my stream evolution work (PHP Foundation project funded by
Sovereign Tech Fund) :
Thank you for the RFC. The feature makes sense to me and fills a clear
gap. I'm sharing some of Derick's concerns and questions, particularly:
-
What will happen if an incorrect / outdated / malformed
session_datastring is provided? Will it silently be ignored? Will it
emit an error? Will there be issues internally in OpenSSL? -
We should avoid introducing new E_WARNINGs, particularly for clear
error situation (session_get_cb without session_new_cb).
Best regards
Tim Düsterhus
Hi,
Hi
I would like to introduce a TLS Session Resumption Support for Streams
RFC
that is part of my stream evolution work (PHP Foundation project funded
by
Sovereign Tech Fund) :Thank you for the RFC. The feature makes sense to me and fills a clear
gap. I'm sharing some of Derick's concerns and questions, particularly:
- What will happen if an incorrect / outdated / malformed
session_datastring is provided? Will it silently be ignored? Will it
emit an error? Will there be issues internally in OpenSSL?
So this changed a bit as only OpenSSLSession instance can be passed in. So
passing invalid and mallformed instance is not possible (TypeError is
thrown if different type is passed in). But if it's expired, it should just
result in warning and full handshake. This should be later covered as part
of new stream error handling as non terminating error (stored error in
exception mode).
- We should avoid introducing new E_WARNINGs, particularly for clear
error situation (session_get_cb without session_new_cb).
The programmer errors have been converted to ValueErrors and TypeErrors.
There are few new warning but those are for non programmer errors and
should be later handled by new stream error handling (another RFC that I
have).
Cheers
Jakub
Hi
Am 2026-02-13 20:22, schrieb Jakub Zelenka:
So this changed a bit as only OpenSSLSession instance can be passed in.
So
passing invalid and mallformed instance is not possible (TypeError is
thrown if different type is passed in). But if it's expired, it should
just
result in warning and full handshake. This should be later covered as
part
of new stream error handling as non terminating error (stored error in
exception mode).
Having a E_WARNING there still feels odd, but I can't comment on how
error handling for streams or OpenSSL currently works. So I trust you
there that this will consistently be fixed with a follow-up RFC :-)
For OpenSSLSession::import() and ::export() however, the RFC mentions
\Exception being thrown on failure. According to the “Throwable” policy
(https://github.com/php/policies/blob/main/coding-standards-and-naming.rst#throwables),
this should be an extension-specific Exception. Since the hierarchy to
use is clearly specified in the policy, adding:
class \Openssl\OpensslException extends \Exception { }
class \Openssl\OpensslError extends \Error { }
can be done without an RFC.
Then the ::import() function can use class \Openssl\InvalidResumptionDataException extends \Openssl\OpensslExceptoin { } or similar and for ::export() just using
OpensslException directly is probably okay.
For the OpenSSLSession class, I leave it up to you whether it makes
sense to also move it into the Openssl namespace or not (as
Openssl\Session). The policy leaves some freedom here, since it's not
directly related to any of the existing classes:
Other than the exception hierarchy, I don't have further remarks. The
proposal makes sense to me and I'm looking forward to it.
Best regards
Tim Düsterhus
Hi,
Thanks for the feedback.
For OpenSSLSession::import() and ::export() however, the RFC mentions
\Exception being thrown on failure. According to the “Throwable” policy
(
https://github.com/php/policies/blob/main/coding-standards-and-naming.rst#throwables),this should be an extension-specific Exception. Since the hierarchy to
use is clearly specified in the policy, adding:class \Openssl\OpensslException extends \Exception { } class \Openssl\OpensslError extends \Error { }can be done without an RFC.
Then the ::import() function can use
class \Openssl\InvalidResumptionDataException extends \Openssl\OpensslExceptoin { }or similar and for ::export() just using
OpensslExceptiondirectly is probably okay.For the OpenSSLSession class, I leave it up to you whether it makes
sense to also move it into theOpensslnamespace or not (as
Openssl\Session). The policy leaves some freedom here, since it's not
directly related to any of the existing classes:
The policy recommends consistency with existing symbols and there are
already OpenSSLCertificate, OpenSSLCertificateSigningRequest and
OpenSSLAsymmetricKey. So I think we should stick with no namespace here and
calls it OpenSSLSession and OpenSSLException. I will introduce that
exception as I agree it makes more sense.
Kind regards,
Jakub
Hi
The policy recommends consistency with existing symbols and there are
already OpenSSLCertificate, OpenSSLCertificateSigningRequest and
OpenSSLAsymmetricKey. So I think we should stick with no namespace here and
calls it OpenSSLSession and OpenSSLException. I will introduce that
exception as I agree it makes more sense.
The policy also states:
This is a somewhat loose guideline, and applies more strongly to functions than classes.
I don't feel strongly about the OpenSSLSession class, but I feel
strongly about the exception hierarchy:
It should immediately be introduced into the namespace, because the
exception hierarchy is relevant to the entire extension (e.g. also to
newly namespaced bits) and namespacing it later will become messy.
However since the OpenSSLSession class will also be an entirely new API
with proper methods instead of just an opaque resource object, it is
more likely to be directly used by developers. So putting it into a
namespace to follow the “latest best practices” there still makes sense
to me, even if it introduces some inconsistency. You always need to
start with something, otherwise you're never going to to the migration
for existing extensions.
Best regards
Tim Düsterhus
Hi,
Hi
The policy recommends consistency with existing symbols and there are
already OpenSSLCertificate, OpenSSLCertificateSigningRequest and
OpenSSLAsymmetricKey. So I think we should stick with no namespace here
and
calls it OpenSSLSession and OpenSSLException. I will introduce that
exception as I agree it makes more sense.The policy also states:
This is a somewhat loose guideline, and applies more strongly to
functions than classes.I don't feel strongly about the OpenSSLSession class, but I feel
strongly about the exception hierarchy:It should immediately be introduced into the namespace, because the
exception hierarchy is relevant to the entire extension (e.g. also to
newly namespaced bits) and namespacing it later will become messy.existing extensions SHOULD follow the rules for newly introduced
exceptions, but MAY diverge for consistency with existing symbols.
The consistency is the key here. I really don't like introducing a
namespace and have some classes in it and some not - that's really not a
consistency then IMO.
Kind regards,
Jakub
Hi,
Hi,
Hi
The policy recommends consistency with existing symbols and there are
already OpenSSLCertificate, OpenSSLCertificateSigningRequest and
OpenSSLAsymmetricKey. So I think we should stick with no namespace here
and
calls it OpenSSLSession and OpenSSLException. I will introduce that
exception as I agree it makes more sense.The policy also states:
This is a somewhat loose guideline, and applies more strongly to
functions than classes.I don't feel strongly about the OpenSSLSession class, but I feel
strongly about the exception hierarchy:It should immediately be introduced into the namespace, because the
exception hierarchy is relevant to the entire extension (e.g. also to
newly namespaced bits) and namespacing it later will become messy.existing extensions SHOULD follow the rules for newly introduced
exceptions, but MAY diverge for consistency with existing symbols.The consistency is the key here. I really don't like introducing a
namespace and have some classes in it and some not - that's really not a
consistency then IMO.
So I thought about this and it's really matter of taste that should not
impact the primary vote. I think it makes sense to add a secondary votes
for those namings to see what others prefer. I just did the RFC update and
implementation. I introduced OpenSSLException for now but if the secondary
vote results in namespace, I will change it before merging. In addition I
also fixed the serialize and export / import to default to PEM which is
better for PHP and more consistent with other functions.
Kind regards,
Jakub
Hi
Am 2026-03-04 23:11, schrieb Jakub Zelenka:
So I thought about this and it's really matter of taste that should not
impact the primary vote. I think it makes sense to add a secondary
votes
for those namings to see what others prefer. I just did the RFC update
and
implementation. I introduced OpenSSLException for now but if the
secondary
vote results in namespace, I will change it before merging. In addition
I
also fixed the serialize and export / import to default to PEM which is
better for PHP and more consistent with other functions.
Thank you. I'm okay with making this a secondary vote. You forgot to add
the “Abstain” option to the secondary votes, I just did that for you.
But you'll need to define the “tie breaker”. I assume you prefer to
break the tie in favor of the non-namespaced names, since this is what
the RFC uses? Either way, please note it down (it doesn't need an
explanation, “Ties are broken in favor of X” is sufficient).
Best regards
Tim Düsterhus