d2i_X509.pod: Better document using the reuse capability for libctx setup

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/22265)

(cherry picked from commit 4ca56f51803a8ae010423180ac80ef991cf78fc5)

diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod
index 9226ef77c3946b0f5e181c03d86200ffd2957b11..00efb60358166186dad4267a84ba2629bb5abd44 100644 (file)
--- a/doc/man3/d2i_X509.pod
+++ b/doc/man3/d2i_X509.pod
@@ -390,10 +390,12 @@ to the returned structure is also written to I<*a>.  If an error occurred
 then NULL is returned.
 
 On a successful return, if I<*a> is not NULL then it is assumed that I<*a>
-contains a valid B<I<TYPE>> structure and an attempt is made to reuse it. This
-"reuse" capability is present for historical compatibility but its use is
-B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
-VALUES section).
+contains a valid B<I<TYPE>> structure and an attempt is made to reuse it.
+For B<I<TYPE>> structures where it matters it is possible to set up a library
+context on the decoded structure this way (see the B<EXAMPLES> section).
+However using the "reuse" capability for other purposes is B<strongly
+discouraged> (see B<BUGS> below, and the discussion in the B<RETURN VALUES>
+section).
 
 B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts
 to parse data from BIO I<bp>.
@@ -538,6 +540,22 @@ Alternative technique:
  if (d2i_X509(&x, &p, len) == NULL)
      /* error */
 
+Setting up a library context and property query:
+
+ X509 *x;
+ unsigned char *buf;
+ const unsigned char *p;
+ int len;
+ OSSL_LIB_CTX *libctx = ....;
+ const char *propq = ....;
+
+ /* Set up buf and len to point to the input buffer. */
+ p = buf;
+ x = X509_new_ex(libctx, propq);
+
+ if (d2i_X509(&x, &p, len) == NULL)
+     /* error, x was freed and NULL assigned to it (see RETURN VALUES) */
+
 =head1 WARNINGS
 
 Using a temporary variable is mandatory. A common