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)

diff --git a/doc/man3/OSSL_DECODER_CTX.pod b/doc/man3/OSSL_DECODER_CTX.pod
index 33b09c836db867df8b2cce977332bd42c27b2759..96111c4e32ddff5286e76de2d223a9e4944e617b 100644 (file)
--- 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 e55212ad554b9ebc6ab5e5b71a601d43be53a28b..9539f21ccf92fca6f1c74588079a5eb6aea54bae 100644 (file)
--- 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 e9248c356a055149105151883dce54b70cac76ee..ab1bfa9c0c3588864ca58184250833dcb62ce9f3 100644 (file)
--- 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 3bf9c10e374e551719c3295ac299b1398f1e6ef5..072659d07ecec5367e0e2f7a047d8d6dae5073fb 100644 (file)
--- 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