Is SSL_R_UNEXPECTED_EOF_WHILE_READING considered to be documented?

[Matt Caswell]

On 13/01/2024 02:48, Matthew Ogilvie wrote:
> The "NOTES" section of the documentation for ERR_GET_REASON() say that
> "Applications should not make control flow decisions based on specific
> error codes... [unless] it is explicitly documented as such."
> https://www.openssl.org/docs/man3.0/man3/ERR_GET_REASON.html
> 
> SSL_R_UNEXPECTED_EOF_WHILE_READING does not appear to be documented
> in version >= 3.0.  However, it is documented as a future change
> in the BUGS section of version 1.1.1 documentation for SSL_get_error().
> https://www.openssl.org/docs/man1.1.1/man3/SSL_get_error.html
> 
> So is SSL_R_UNEXPECTED_EOF_WHILE_READING something that can
> be relied on going forward?  I'm hoping the missing documentation
> is just an oversight, and it was intended to be documented (and
> presumably will be soon) so that the ERR_GET_REASON() "NOTE" doesn't
> apply.
> 
> ----
> 
> I'm also aware of the related mailing list discussion that ultimately
> resulted in the creation of the SSL_OP_IGNORE_UNEXPECTED_EOF option,
> which is documented.  But making the decision to use this option up
> front early in a connection seems imperfect, since a higher-level
> protocol's ability to detect a truncation attack may depend on
> various details of that protocol, such as which protocol variation(s)
> are in use, or precisely where in the conversation it is truncated.
> This is certainly true of HTTP's various
> content-length/transfer-encoding:chunked/untilEOF variations for the
> end of a body...
> https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html
> https://mta.openssl.org/pipermail/openssl-project/2020-May/001975.html
> https://mta.openssl.org/pipermail/openssl-project/2020-May/001976.html
> 
> I have long had a connection abstraction that can cleanly represent
> this ambigous maybe-attack state, and can let higher-level
> protocols decide what to do on a case-by-case basis.  I would just
> like to know if I can rely on SSL_R_UNEXPECTED_EOF_WHILE_READING
> indicating I should set my version of the state, or if is likely to
> change yet again...

IMO, it should be ok to use this for control flow decisions.

I've raised a PR for a documentation update:

https://github.com/openssl/openssl/pull/23304

We shall see if other committers agree with me during the review!

Matt