12 files changed, 172 insertions, 52 deletions
diff --git a/doc/man3/BIO_s_bio.pod b/doc/man3/BIO_s_bio.pod
index 653fe4785a49..494b3632ee93 100644
--- a/doc/man3/BIO_s_bio.pod
+++ b/doc/man3/BIO_s_bio.pod
@@ -5,7 +5,8 @@
 BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
 BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair,
 BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request,
-BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
+BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request,
+BIO_nread0, BIO_nread, BIO_nwrite0, BIO_nwrite - BIO pair BIO
 
 =head1 SYNOPSIS
 
@@ -28,6 +29,11 @@ BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
  size_t BIO_ctrl_get_read_request(BIO *b);
  int BIO_ctrl_reset_read_request(BIO *b);
 
+ int BIO_nread0(BIO *bio, char **buf);
+ int BIO_nread(BIO *bio, char **buf, int num);
+ int BIO_nwrite0(BIO *bio, char **buf);
+ int BIO_nwrite(BIO *bio, char **buf, int num);
+
 =head1 DESCRIPTION
 
 BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink
@@ -98,6 +104,44 @@ than that returned by BIO_get_write_guarantee().
 BIO_ctrl_reset_read_request() can also be used to reset the value returned by
 BIO_get_read_request() to zero.
 
+=head2 Non-copying Interface
+
+BIO_nread0(), BIO_nread(), BIO_nwrite0(), and BIO_nwrite() provide a non-copying
+interface for reading from and writing to BIO pairs. These functions allow
+direct access to the internal buffer, avoiding the overhead of copying data.
+
+BIO_nread0() returns in B<*buf> a pointer to the start of the available data
+in the peer's write buffer and returns the number of bytes available.
+This allows reading directly from the buffer without copying.
+It does not consume the data; a subsequent call to BIO_nread() is needed
+to advance the buffer position.
+
+BIO_nread() is similar to BIO_nread0() but also advances the read position
+by up to B<num> bytes. The actual number of bytes consumed is returned.
+The B<*buf> pointer is set to the start of the data that was consumed.
+Since the data is considered consumed after this call, the pointer returned
+by BIO_nread() should not be used afterwards unless the caller also
+controls the writing side. The typical pattern is to call BIO_nread0() first,
+use the data, and then call BIO_nread() to consume it.
+
+BIO_nwrite0() returns in B<*buf> a pointer to the start of the available
+space in the write buffer and returns the number of bytes that can be written.
+This allows writing directly to the buffer without copying.
+It does not commit the data; a subsequent call to BIO_nwrite() is needed
+to update the buffer length.
+
+BIO_nwrite() is similar to BIO_nwrite0() but also commits up to B<num> bytes
+as written. The actual number of bytes committed is returned.
+The B<*buf> pointer is set to the start of the region that was committed.
+BIO_nwrite() should only be called after the data has actually been written
+to the buffer obtained from BIO_nwrite0(), since committing signals data
+availability to the reading side.
+
+Note that due to the ring buffer implementation, if wrapping around would be
+required, BIO_nread0() and BIO_nwrite0() may return less than the total
+available space. In such cases, a second call may be needed to access the
+remaining data or space.
+
 =head1 NOTES
 
 Both halves of a BIO pair should be freed. That is even if one half is implicit
@@ -133,6 +177,17 @@ locations for B<bio1> and B<bio2>. Check the error stack for more information.
 
 [XXXXX: More return values need to be added here]
 
+BIO_nread0() returns the number of bytes available for reading, 0 if the peer
+has closed and no data remains (EOF), or -1 if no data is currently available
+(retry may be appropriate). If the BIO is not initialized, -2 is returned.
+
+BIO_nwrite0() returns the number of bytes of space available for writing, or -1
+if no space is currently available (retry may be appropriate) or the BIO has
+been closed. If the BIO is not initialized, -2 is returned.
+
+BIO_nread() and BIO_nwrite() return the number of bytes consumed or committed
+respectively, or the same error values as BIO_nread0() and BIO_nwrite0().
+
 =head1 EXAMPLES
 
 The BIO pair can be used to have full control over the network access of an
@@ -176,6 +231,30 @@ and must be transferred to the network. Use BIO_ctrl_get_read_request() to
 find out, how many bytes must be written into the buffer before the
 SSL_operation() can successfully be continued.
 
+A typical usage pattern for the non-copying write interface is:
+
+ int ret;
+ char *buf;
+
+ ret = BIO_nwrite0(bio, &buf);
+ if (ret > 0) {
+     /* write up to 'ret' bytes directly to 'buf' */
+     memcpy(buf, data, len);
+     BIO_nwrite(bio, &buf, len);  /* commit the write */
+ }
+
+A typical usage pattern for the non-copying read interface is:
+
+ int ret;
+ char *buf;
+
+ ret = BIO_nread0(bio, &buf);
+ if (ret > 0) {
+     /* read up to 'ret' bytes directly from 'buf' */
+     process_data(buf, ret);
+     BIO_nread(bio, &buf, ret);  /* consume the data */
+ }
+
 =head1 WARNINGS
 
 As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ
@@ -191,7 +270,7 @@ L<BIO_should_retry(3)>, L<BIO_read_ex(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2026 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/BN_add.pod b/doc/man3/BN_add.pod
index 46966d996379..a7ff19565f49 100644
--- a/doc/man3/BN_add.pod
+++ b/doc/man3/BN_add.pod
@@ -108,8 +108,10 @@ BN_gcd() computes the greatest common divisor of I<a> and I<b> and
 places the result in I<r>. I<r> may be the same B<BIGNUM> as I<a> or
 I<b>.
 
-For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
-temporary variables; see L<BN_CTX_new(3)>.
+For all functions that take a I<ctx> parameter, it must be a previously
+allocated B<BN_CTX> used for temporary variables; see L<BN_CTX_new(3)>.
+Unless stated otherwise in the documentation for a specific function,
+the I<ctx> parameter must not be NULL.
 
 Unless noted otherwise, the result B<BIGNUM> must be different from
 the arguments.
@@ -135,7 +137,7 @@ L<BN_add_word(3)>, L<BN_set_bit(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2026 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/CMS_decrypt.pod b/doc/man3/CMS_decrypt.pod
index 121b74a30a10..4e40b37f214a 100644
--- a/doc/man3/CMS_decrypt.pod
+++ b/doc/man3/CMS_decrypt.pod
@@ -68,7 +68,7 @@ then the above behaviour is modified and an error B<is> returned if no
 recipient encrypted key can be decrypted B<without> generating a random
 content encryption key. Applications should use this flag with
 B<extreme caution> especially in automated gateways as it can leave them
-open to attack.
+open to attack. See L<EVP_PKEY_decrypt(3)> for more details.
 
 It is possible to determine the correct recipient key by other means (for
 example looking them up in a database) and setting them in the CMS structure
@@ -103,7 +103,7 @@ mentioned in CMS_verify() also applies to CMS_decrypt().
 
 =head1 SEE ALSO
 
-L<ERR_get_error(3)>, L<CMS_encrypt(3)>
+L<ERR_get_error(3)>, L<CMS_encrypt(3)>, L<EVP_PKEY_decrypt(3)>
 
 =head1 HISTORY
 
@@ -112,7 +112,7 @@ were added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2008-2026 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 2af4ebec91f9..46cff34f075c 100644
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -413,7 +413,8 @@ encrypted data.
 For most ciphers and modes, the amount of data written can be anything
 from zero bytes to (inl + cipher_block_size - 1) bytes.
 For wrap cipher modes, the amount of data written can be anything
-from zero bytes to (inl + cipher_block_size) bytes.
+from zero bytes to (inl rounded up to cipher_block_size + cipher_block_size)
+bytes.
 For stream ciphers, the amount of data written can be anything from zero
 bytes to inl bytes.
 Thus, the buffer pointed to by I<out> must contain sufficient room for the
diff --git a/doc/man3/OSSL_HTTP_REQ_CTX.pod b/doc/man3/OSSL_HTTP_REQ_CTX.pod
index 210f33801cae..b8db1724c6f4 100644
--- a/doc/man3/OSSL_HTTP_REQ_CTX.pod
+++ b/doc/man3/OSSL_HTTP_REQ_CTX.pod
@@ -86,9 +86,12 @@ For backward compatibility, I<path> may begin with C<http://> and thus convey
 an absoluteURI. In this case it indicates HTTP proxy use and provides also the
 server (and optionally the port) that the proxy shall forward the request to.
 In this case the I<server> and I<port> arguments must be NULL.
+The I<server>, I<port>, and I<path> arguments must not contain CR or LF
+characters.
 
 OSSL_HTTP_REQ_CTX_add1_header() adds header I<name> with value I<value> to the
 context I<rctx>. It can be called more than once to add multiple header lines.
+The I<name> and I<value> arguments must not contain CR or LF characters.
 For example, to add a C<Host> header for C<example.com> you would call:
 
  OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com");
@@ -143,6 +146,7 @@ The HTTP header C<Content-Length> is filled out with the length of the request.
 I<content_type> must be NULL if I<req> is NULL.
 If I<content_type> isn't NULL,
 the HTTP header C<Content-Type> is also added with the given string value.
+The I<content_type> argument must not contain CR or LF characters.
 The header lines are added to the internal memory B<BIO> for the request header.
 
 OSSL_HTTP_REQ_CTX_nbio() attempts to send the request prepared in I<rctx>
@@ -299,7 +303,7 @@ All other functions described here were added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2015-2025 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2026 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/OSSL_HTTP_parse_url.pod b/doc/man3/OSSL_HTTP_parse_url.pod
index bc29fb18d14b..60d9fcdd6401 100644
--- a/doc/man3/OSSL_HTTP_parse_url.pod
+++ b/doc/man3/OSSL_HTTP_parse_url.pod
@@ -32,7 +32,9 @@ see L<openssl_user_macros(7)>:
 
 =head1 DESCRIPTION
 
-OSSL_HTTP_adapt_proxy() takes an optional proxy hostname I<proxy>
+OSSL_HTTP_adapt_proxy() determines whether a proxy should be used
+when connecting to the given I<server>.
+It takes an optional proxy hostname I<proxy>
 and returns it transformed according to the optional I<no_proxy> parameter,
 I<server>, I<use_ssl>, and the applicable environment variable, as follows.
 If I<proxy> is NULL, take any default value from the C<http_proxy>
@@ -40,11 +42,13 @@ environment variable, or from C<https_proxy> if I<use_ssl> is nonzero.
 If this still does not yield a proxy hostname,
 take any further default value from the C<HTTP_PROXY>
 environment variable, or from C<HTTPS_PROXY> if I<use_ssl> is nonzero.
-If I<no_proxy> is NULL, take any default exclusion value from the C<no_proxy>
-environment variable, or else from C<NO_PROXY>.
-Return the determined proxy host unless the exclusion value,
-which is a list of proxy hosts separated by C<,> and/or whitespace,
-contains I<server>.
+Return the determined proxy host if I<server> is the empty string
+or I<server> is not in the exclusion list.
+The exclusion list is a list of server hosts separated by C<,>
+and/or whitespace.
+They may be given via the I<no_proxy> parameter.
+If it is NULL, the exclusion list is taken from the C<no_proxy>
+environment variable if set, otherwise from C<NO_PROXY>.
 Otherwise return NULL.
 When I<server> is a string delimited by C<[> and C<]>, which are used for IPv6
 addresses, the enclosing C<[> and C<]> are stripped prior to comparison.
@@ -102,7 +106,7 @@ OCSP_parse_url() was deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2026 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod
index eaa0986666fc..b854756ffd46 100644
--- a/doc/man3/OSSL_HTTP_transfer.pod
+++ b/doc/man3/OSSL_HTTP_transfer.pod
@@ -158,6 +158,7 @@ pre-established with a TLS proxy using the HTTP CONNECT method,
 optionally using proxy client credentials I<proxyuser> and I<proxypass>,
 to connect with TLS protection ultimately to I<server> and I<port>.
 If the I<port> argument is NULL or the empty string it defaults to "443".
+The I<server> and I<port> arguments must not contain CR or LF characters.
 If the I<timeout> parameter is > 0 this indicates the maximum number of
 seconds the connection setup is allowed to take.
 A value <= 0 enables waiting indefinitely, i.e., no timeout.
@@ -178,6 +179,8 @@ else HTTP POST with the contents of I<req> and optional I<content_type>, where
 the length of the data in I<req> does not need to be determined in advance: the
 BIO will be read on-the-fly while sending the request, which supports streaming.
 The optional list I<headers> may contain additional custom HTTP header lines.
+The I<path>, I<headers> names and values, and I<content_type> must not contain
+CR or LF characters.
 The I<max_resp_len> parameter specifies the maximum allowed
 response content length, where the value 0 indicates no limit.
 For the meaning of the I<expected_content_type>, I<expect_asn1>, I<timeout>,
@@ -275,7 +278,7 @@ All the functions described here were added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2026 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/PKCS7_decrypt.pod b/doc/man3/PKCS7_decrypt.pod
index aea15937ab86..751556501b91 100644
--- a/doc/man3/PKCS7_decrypt.pod
+++ b/doc/man3/PKCS7_decrypt.pod
@@ -22,6 +22,14 @@ B<flags> is an optional set of flags.
 Although the recipients certificate is not needed to decrypt the data it is needed
 to locate the appropriate (of possible several) recipients in the PKCS#7 structure.
 
+When RSA PKCS#1 v1.5 Key Transport is in use, the invoked EVP_PKEY_decrypt()
+will use implicit rejection mechanism. It always returns the result of RSA
+decryption of the symmetric key to avoid Marvin attack. This result is
+deterministic and can happen to match the symmetric cipher used for the content
+encryption. In case when the certificate is not provided, the last
+RecipientInfo producing the key looking valid will be used. It may cause
+getting garbage content on decryption.
+
 The following flags can be passed in the B<flags> parameter.
 
 If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted
@@ -38,16 +46,13 @@ The error can be obtained from ERR_get_error(3)
 PKCS7_decrypt() must be passed the correct recipient key and certificate. It would
 be better if it could look up the correct key and certificate from a database.
 
-The lack of single pass processing and need to hold all data in memory as
-mentioned in PKCS7_sign() also applies to PKCS7_verify().
-
 =head1 SEE ALSO
 
-L<ERR_get_error(3)>, L<PKCS7_encrypt(3)>
+L<ERR_get_error(3)>, L<PKCS7_encrypt(3)>, L<EVP_PKEY_decrypt(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2002-2026 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/SSL_CTX_set_session_cache_mode.pod b/doc/man3/SSL_CTX_set_session_cache_mode.pod
index 25b588f58091..839f787d9d3c 100644
--- a/doc/man3/SSL_CTX_set_session_cache_mode.pod
+++ b/doc/man3/SSL_CTX_set_session_cache_mode.pod
@@ -8,8 +8,8 @@ SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable
 
  #include <openssl/ssl.h>
 
- long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode);
- long SSL_CTX_get_session_cache_mode(SSL_CTX ctx);
+ long SSL_CTX_set_session_cache_mode(SSL_CTX *ctx, long mode);
+ long SSL_CTX_get_session_cache_mode(SSL_CTX *ctx);
 
 =head1 DESCRIPTION
 
@@ -136,7 +136,7 @@ L<SSL_CTX_flush_sessions(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2001-2021 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2026 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/SSL_CTX_set_session_id_context.pod b/doc/man3/SSL_CTX_set_session_id_context.pod
index c9572bd0d83f..35b06ef2037f 100644
--- a/doc/man3/SSL_CTX_set_session_id_context.pod
+++ b/doc/man3/SSL_CTX_set_session_id_context.pod
@@ -38,9 +38,6 @@ is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and
 SSL_set_session_id_context() functions are therefore only useful on the
 server side.
 
-OpenSSL clients will check the session id context returned by the server
-when reusing a session.
-
 The maximum length of the B<sid_ctx> is limited to
 B<SSL_MAX_SID_CTX_LENGTH>.
 
@@ -51,11 +48,24 @@ certificates are used, stored sessions
 will not be reused but a fatal error will be flagged and the handshake
 will fail.
 
-If a server returns a different session id context to an OpenSSL client
-when reusing a session, an error will be flagged and the handshake will
-fail. OpenSSL servers will always return the correct session id context,
-as an OpenSSL server checks the session id context itself before reusing
-a session as described above.
+If a client attempts to resume a session and the server detects that the session
+id context associated with the session is different to the current session id
+context then the resumption will fail. The handshake will continue normally but
+no resumption will occur.
+
+It is vital that the session id context is set before any session resumption
+occurs. Sessions get created early in the handshake. If the session id context
+is not set by the time the session gets created then the session will be
+associated with an empty session id context. The already created session will
+not get updated if the  session id context is later set. In particular the
+callback set via the L<SSL_CTX_set_tlsext_servername_callback(3)> function will
+be invoked after the session gets created, so if the session id context is set
+in the callback then this will be too late for the current handshake and the
+session id context setting will be ignored with respect to resumption. Typically
+the session id context should be set before the TLS handshake starts, but it may
+occur as late as in the callback set via the L<SSL_CTX_set_client_hello_cb(3)>
+function.
+
 
 =head1 RETURN VALUES
 
@@ -82,7 +92,7 @@ L<ssl(7)>
 
 =head1 COPYRIGHT
 
-Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2026 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod
index a0a4bd636785..a1b3f58994b5 100644
--- a/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod
+++ b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod
@@ -29,7 +29,11 @@ still necessary in order to acknowledge the servername requested by the client.
 SSL_CTX_set_tlsext_servername_callback() sets the application callback B<cb>
 used by a server to perform any actions or configuration required based on
 the servername extension received in the incoming connection. When B<cb>
-is NULL, SNI is not used.
+is NULL, SNI is not used. Note that this callback occurs late in the processing
+of the ClientHello message. In particular it happens after session resumption
+has occurred, and so typically this callback should not call functions such
+as L<SSL_set_session_id_context(3)> since it is too late to affect the session
+resumption for the current handshake.
 
 The servername callback should return one of the following values:
 
@@ -169,7 +173,7 @@ NULL.
 
 =head1 COPYRIGHT
 
-Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2026 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod
index 41e76ae8379b..9f0589a87e4c 100644
--- a/doc/man3/d2i_X509.pod
+++ b/doc/man3/d2i_X509.pod
@@ -471,21 +471,29 @@ encoding.  Unlike the C structures which can have pointers to sub-objects
 within, the DER is a serialized encoding, suitable for sending over the
 network, writing to a file, and so on.
 
-B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a
-pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to
-the byte following the parsed data.  If I<a> is not NULL then a pointer
-to the returned structure is also written to I<*a>.  If an error occurred
-then NULL is returned. The caller retains ownership of the
-returned object and needs to free it when it is no longer needed, e.g.
-using X509_free() for X509 objects or DSA_SIG_free() for DSA_SIG objects.
+B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>.
+When there is no error, a pointer to a B<I<TYPE>> object is returned and I<*ppin> is
+incremented to the byte following the parsed data.
+The caller owns the returned object and needs to free it when it is no longer needed, 
+e.g., via X509_free() for B<X509> objects.
 
-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.
-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).
+If either I<a> or I<*a> is NULL, then fresh storage is allocated for the
+returned object, and if I<a> is not NULL then I<*a> is set equal to the
+returned pointer.
+
+When both I<a> and I<*a> are not NULL, I<*a> MUST be a pointer to an
+existing I<TYPE> object, which is reused to hold the decoded result.
+On error (NULL return value), the object is freed and I<*a> is set to NULL.
+
+From OpenSSL 3.x onwards, reuse is only supported when I<*a> points to a newly
+allocated, and not otherwise modified, I<TYPE> object.
+Allocation can be via one of the various _ex() routines, which make it possible
+to associate the allocated object with a chosen I<libctx> (library context)
+or I<propq> (property query), see the B<EXAMPLES> section.
+No other reuse is supported (see B<BUGS> below, and the discussion in the
+B<RETURN VALUES> section).
+The returned object is not suitable for another reuse: each reuse attempt MUST
+start with a newly allocated object.
 
 B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts
 to parse data from BIO I<bp>.
@@ -761,7 +769,7 @@ were added in OpenSSL 3.5.
 
 =head1 COPYRIGHT
 
-Copyright 1998-2025 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 1998-2026 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy