From c22facc35038085407e457bada85efffab3c3f2a Mon Sep 17 00:00:00 2001
From: Igor Ustinov <igus68@gmail.com>
Date: Tue, 11 Nov 2025 15:01:34 +0100
Subject: [PATCH] Document when OSSL_ENC/DECODER_CTX_set* functions shouldn't
 be used

Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/29122)
---
 doc/man3/OSSL_DECODER_CTX.pod              |  7 +++++++
 doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod |  4 ++++
 doc/man3/OSSL_ENCODER_CTX.pod              | 13 +++++++++++++
 doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod |  4 ++++
 4 files changed, 28 insertions(+)

diff --git a/doc/man3/OSSL_DECODER_CTX.pod b/doc/man3/OSSL_DECODER_CTX.pod
index 33b09c836db..96111c4e32d 100644
--- a/doc/man3/OSSL_DECODER_CTX.pod
+++ b/doc/man3/OSSL_DECODER_CTX.pod
@@ -167,6 +167,13 @@ I<reference>, unpacks the object which it refers to, and exports it by
 creating an L<OSSL_PARAM(3)> array that it then passes to I<export_cb>,
 along with I<export_arg>.
 
+Note that functions OSSL_DECODER_CTX_set_selection(),
+OSSL_DECODER_CTX_set_output_type(), OSSL_DECODER_CTX_set_output_structure(),
+OSSL_DECODER_CTX_add_encoder(), OSSL_DECODER_CTX_add_extra(),
+OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data(), and
+OSSL_DECODER_CTX_set_cleanup() shouldn't be used after the context is finalised,
+in particular after calling the function OSSL_DECODER_CTX_new_for_pkey().
+
 =head2 Constructor
 
 A B<OSSL_DECODER_CONSTRUCT> gets the following arguments:
diff --git a/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod b/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod
index e55212ad554..9539f21ccf9 100644
--- a/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod
+++ b/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod
@@ -71,6 +71,10 @@ zero).  This helps the caller to distinguish between an error when creating
 the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to
 act accordingly.
 
+Note that OSSL_DECODER_CTX_new_for_pkey() finalises the OSSL_DECODER_CTX;
+after that the OSSL_DECODER_CTX_set_* and OSSL_DECODER_CTX_add_* functions
+described in L<OSSL_DECODER_CTX(3)> shouldn't be called.
+
 OSSL_DECODER_CTX_set_passphrase() gives the implementation a pass phrase to
 use when decrypting the encoded private key. Alternatively, a pass phrase
 callback may be specified with the following functions.
diff --git a/doc/man3/OSSL_ENCODER_CTX.pod b/doc/man3/OSSL_ENCODER_CTX.pod
index e9248c356a0..ab1bfa9c0c3 100644
--- a/doc/man3/OSSL_ENCODER_CTX.pod
+++ b/doc/man3/OSSL_ENCODER_CTX.pod
@@ -130,6 +130,13 @@ passed to the constructor every time it's called.
 OSSL_ENCODER_CTX_set_cleanup() sets the constructor data I<cleanup>
 function.  This is called by L<OSSL_ENCODER_CTX_free(3)>.
 
+Note that functions OSSL_ENCODER_CTX_set_selection(),
+OSSL_ENCODER_CTX_set_output_type(), OSSL_ENCODER_CTX_set_output_structure(),
+OSSL_ENCODER_CTX_add_encoder(), OSSL_ENCODER_CTX_add_extra(),
+OSSL_ENCODER_CTX_set_construct(), OSSL_ENCODER_CTX_set_construct_data(), and
+OSSL_ENCODER_CTX_set_cleanup() shouldn't be used after the context is finalised,
+in particular after calling the function OSSL_ENCODER_CTX_new_for_pkey().
+
 =head2 Constructor
 
 A B<OSSL_ENCODER_CONSTRUCT> gets the following arguments:
@@ -202,6 +209,12 @@ output type.
 OSSL_ENCODER_INSTANCE_get_output_structure() returns a string with the name
 of the output structure.
 
+=head1 NOTES AND BUGS
+
+The chain mechanism in ENCODE is not yet completely implemented.
+It affects functions such as OSSL_ENCODER_CTX_add_extra and the
+inner processing loop.
+
 =head1 SEE ALSO
 
 L<provider(7)>, L<OSSL_ENCODER(3)>
diff --git a/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod b/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod
index 3bf9c10e374..072659d07ec 100644
--- a/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod
+++ b/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod
@@ -60,6 +60,10 @@ zero).  This helps the caller to distinguish between an error when creating
 the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to
 act accordingly.
 
+Note that OSSL_ENCODER_CTX_new_for_pkey() finalises the OSSL_ENCODER_CTX;
+after that the OSSL_ENCODER_CTX_set_* and OSSL_ENCODER_CTX_add_* functions
+described in L<OSSL_ENCODER_CTX(3)> shouldn't be called.
+
 OSSL_ENCODER_CTX_set_cipher() tells the implementation what cipher
 should be used to encrypt encoded keys.  The cipher is given by
 name I<cipher_name>.  The interpretation of that I<cipher_name> is
-- 
2.47.3