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

[Tomas Mraz]

Clearly we need the documentation fix. If there should be a new API or
not that's a separate discussion. If you want to propose it, please
open a new GH feature request issue.

Regards,
Tomas Mraz, OpenSSL

On Wed, 2023-10-04 at 09:36 +0200, Thomas Bailleux wrote:
> Hi Tomas,
> 
> Thanks for your reply.
> 
> I wonder if we shouldn't be providing a new API for X509 instead. We
> already have `PEM_read_bio_PrivateKey_ex` and
> `d2i_PrivateKey_ex_bio`, what about having `PEM_read_bio_X509_ex` and
> `d2i_X509_ex_bio` too? 
> I feel like the documentation can be confusing with all these
> conditions (OK if using OSSL_LIB_CTX, otherwise not OK, and in both
> cases *x is freed even on error etc).
> 
> Also, we can move this discussion to the PR you just opened if you
> prefer.
> 
> Regards,
> 
> - thomas
> 
> On Tue, Oct 3, 2023 at 3:47 PM Tomas Mraz <tomas at openssl.org> wrote:
> > 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