OpenSSL 3, "reuse" capability in `d2i_TYPE_BIO` and documentation

[Thomas Bailleux]

Hello OpenSSL,

I'm currently migrating a codebase from OpenSSL 1.1.1 to OpenSSL 3.
Since I may use OpenSSL providers in the future, I decided to use these new
`_ex` functions from OpenSSL 3.

While reading the "Old functions that should be changed" from the migration
guide[1], I came across an oddity: it is claimed that in order to use a
non-default library context when parsing an `X509` or an `EVP_PKEY`,
`TYPE_new_ex` must be used (e.g. `X509_new_ex`), and then we have to use
the "reuse" capability from the various parsing functions
(`PEM_read_bio_X509`):

Some functions can be passed an object that has already been set up with a
> library context such as d2i_X509(3), d2i_X509_CRL(3), d2i_X509_REQ(3) and
> d2i_X509_PUBKEY(3). If NULL is passed instead then the created object will
> be set up with the default library context. Use X509_new_ex(3),
> X509_CRL_new_ex(3), X509_REQ_new_ex(3) and X509_PUBKEY_new_ex(3) if a
> library context is required.


So basically we have to do the following:

BIO *bio;
> OSSL_LIB_CTX* lib_ctx;
> X509 *x509 = X509_new_ex(lib_ctx, NULL);
> if (d2i_X509_bio(bio, &x509) != NULL) {
>   // success
> } else {
>   // error
> }
>

However, in the `D2I_X509` manpage[2], the following is stated:

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.
> This "reuse" capability is present for historical compatibility but its use
> is *strongly discouraged* (see BUGS below, and the discussion in the
> RETURN VALUES section).
> …
> BUGS
> …
>
> As a result of the above issues the "reuse" behaviour is strongly
> discouraged.
>
So if I'm understanding correctly, this "reuse" capability is discouraged,
still present for historical compatibility, but in OpenSSL 3 we have to use
it if we want to use a custom library context.

This divergence between these two bits of documentation bothers me.
Do you have an opinion on this?

Regards,

- thomas


[1]:
https://www.openssl.org/docs/man3.1/man7/migration_guide.html#Using-a-Library-Context---Old-functions-that-should-be-changed
[2]: https://www.openssl.org/docs/man3.1/man3/d2i_X509.html
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mta.openssl.org/pipermail/openssl-users/attachments/20231002/858adccf/attachment.htm>