d2i_PKCS12_fp() documentation issues

[Matthew Ogilvie]

1: When is argument freed?

The (generic "TYPE") man page for d2i_PKCS12_fp() BUGS section mentions:
"Additionally, in versions of OpenSSL prior to 1.1.0, when the 'reuse'
behaviour is used and an error occurs the behaviour is inconsistent. Some
functions behaved as described here, while some did not free *a on error
and did not set *a to NULL."

In my testing of d2i_PKCS12_fp() under Open SSL 3.0.11, it still seems
to have this bug.  I haven't tested other TYPE's, etc.  My workaround is
that after a NULL error is returned, I'll explicitly call PKCS12_free()
with the same variable/argument.  Hopefully this will work with
d2i_PKCS12_fp() both "as implemented" and "as documented" since free
does nothing when passed NULL.

------

2: Online man pages with '*':

The online version of the man pages seem to sometimes misinterpret
asterisk as an "italicize" command.  For example, in the web version
of the page above, it says "... while some did not free a on error...",
without the "*" before the "a", and stuff before it italicized.
There is similar corruption in the 4the paragraph of the description
that starts "On a successful return...", and probably other
pages as well.
https://www.openssl.org/docs/man3.0/man3/d2i_PKCS12_fp.html

In contrast, the actual installed man page ("man d2i_PKCS12_fp") seems
to get this right.  Also, online paragraphs that only have one
asterisk seem to work.

===========

3. As a very minor followup to my previous question about
OPENSSL_thread_stop() vs "_ex()":

Thanks.  I can call both as easily as one in my applications since
I only use one extra global OSSL_LIB_CTX besides the default. (I only
use the extra for reading P12 files with legacy encryption enabled,
which still seem to be commonly generated by other tools.)

--
FUTURE/consider documentation changes:

However, tracking/arranging multiple OPENSSL_thread_stop_ex() calls
might be trickier in other applications structured differently than
mine.

Also, as I mentioned before, a quick glance suggests the code looks
somewhat inconsistent with the documentation (the "...is the same
as..." part you quoted), such that OPENSSL_thread_stop() seems to
clean up all OSSL_LIB_CTX?  (Untested: Might cause problems if you
still want to use other explicit OSSL_LIB_CTX's after an
OPENSSL_thread_stop(), from the same thread?)

Perhaps the OPENSSL_thread_stop_ex() could be deprecated?  Only
really needed internally when destroying an OSSL_LIB_CTX long before
a thread exits, to satisfy the documented "If OSSL_LIB_CTX_free()
is called OPENSSL_thread_stop_ex will be called automatically for the
current thread".  That is useful and probably intended to allow
continued use of other OSSL_LIB_CTX's from the same thread, but
I don't know why you should ever need to call it externally.  (If
a thread is actually exiting, then it makes more sense to
cleanup everything, which OPENSSL_thread_stop() looks like it
does already...)


- Matthew Ogilvie