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

[Tomas Mraz]

Hello Thomas,

I've created a pull request that should clarify the matter:

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

Please look there.

Tomas Mraz, OpenSSL

On Mon, 2023-10-02 at 09:41 +0200, Thomas Bailleux wrote:
> 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

-- 
Tomáš Mráz, OpenSSL