diff options
| author | Tomas Mraz <tomas@openssl.org> | 2023-10-03 15:45:13 +0200 |
|---|---|---|
| committer | Tomas Mraz <tomas@openssl.org> | 2023-10-05 19:11:17 +0200 |
| commit | e941f3fcae07f5059a654c392fed4063975c8ea2 (patch) | |
| tree | b26972f59bd1d302f96d3cd6b09e430b9713ee74 | |
| parent | f41af715c110fd81b8f100ac08a99332595c5a7b (diff) | |
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)
| -rw-r--r-- | doc/man3/d2i_X509.pod | 26 |
1 files changed, 22 insertions, 4 deletions
diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod index 9226ef77c3..00efb60358 100644 --- 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 |