d2i_TYPE, reuse and libctx/propq

[Michael Richardson]

I found the explanation in the omnibus d2i_TYPE() manual rather confusing.
I'm replacing a call to di_X509_bio(bp, NULL) with:

x = X509_new_ex(libctx, propq);
if (d2i_X509_bio(bp, &x) == NULL)

as shown in the man page.

The text:

If a is not NULL then a pointer to
the returned structure is also written to *a. If an error occurred
then NULL is returned. The caller retains ownership of the returned
object and needs to free it when it is no longer needed, e.g. using
X509_free() for X509 objects or DSA_SIG_free() for DSA_SIG objects.

On a successful return, if *a is not NULL then it is assumed that *a
contains a valid TYPE structure and an attempt is made to reuse it.
For TYPE structures where it matters it is possible to set up a library
context on the decoded structure this way (see the EXAMPLES section).
However using the "reuse" capability for other purposes is strongly
discouraged (see BUGS below, and the discussion in the RETURN VALUES
section).

and this is just poorly written.
The distinction between `a` and `*a` is pretty subtle.
I think some of the confusion is that a goal is to indicate that *a is not
modified if the decode is not successful? I think it should instead say:

If a is not NULL, then the contents of the pointer will be examined.

If *a is not NULL, then it is assumed that caller has allocated a new TYPE
structure, and it will be used. This is the "reuse" capability.
Please see BUGS below.
If an error occurs, then the structure will not be used or modified.

If a is NULL, or *a is NULL, then a new structure will be allocated.
(A NULL libctx and a NULL propq will be provided)
If *a is not NULL, then it will be set to the newly allocated structure.

When an existing structure is reused, the reused structure is not
completely cleared. This may results in memory leaks, and reference
count leaks, particularly when errors occur. (See BUGS).
From OpenSSL 3.x onwards, the only supported use for the reuse mechanism
is to allocate the TYPE structure with one of the many _ex() routines,
such that the libctx and propq can be initialized. No other reuse is
supported.

--
] Never tell me the odds! | ipv6 mesh networks [
] Michael Richardson, Sandelman Software Works | IoT architect [
] m...@sandelman.ca http://www.sandelman.ca/ | ruby on rails [

[Viktor Dukhovni]

On Tue, Sep 02, 2025 at 07:52:40PM -0400, Michael Richardson wrote:

> I think it should instead say:
>
> If a is not NULL, then the contents of the pointer will be examined.
>
> If *a is not NULL, then it is assumed that caller has allocated a new TYPE
> structure, and it will be used. This is the "reuse" capability.
> Please see BUGS below.
> If an error occurs, then the structure will not be used or modified.
>
> If a is NULL, or *a is NULL, then a new structure will be allocated.
> (A NULL libctx and a NULL propq will be provided)
> If *a is not NULL, then it will be set to the newly allocated structure.
>
> When an existing structure is reused, the reused structure is not
> completely cleared. This may results in memory leaks, and reference
> count leaks, particularly when errors occur. (See BUGS).
> From OpenSSL 3.x onwards, the only supported use for the reuse mechanism
> is to allocate the TYPE structure with one of the many _ex() routines,
> such that the libctx and propq can be initialized. No other reuse is
> supported.

If possible, please open an issue or pull request at
<https://github.com/openssl/openssl>.

--
Viktor. 🇺🇦 Слава Україні!

[Michael Richardson]

https://github.com/openssl/openssl/pull/28456
Not sure if I<> is correct annotation for a and *a.