ENCODER: Refactor the OSSL_ENCODER API to be more like OSSL_DECODER

OSSL_ENCODER was developed before OSSL_DECODER, so the idea of
chaining and the resulting API came later.  This series of changes
brings the same sort of API and functionality back to OSSL_ENCODER,
making the two APIs more consistent with each other.

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/12873)

4 files changed, 215 insertions, 113 deletions

diff --git a/doc/man3/OSSL_ENCODER.pod b/doc/man3/OSSL_ENCODER.pod
index d8998310bd..a1b7c4b76c 100644
--- a/doc/man3/OSSL_ENCODER.pod
+++ b/doc/man3/OSSL_ENCODER.pod
@@ -11,7 +11,9 @@ OSSL_ENCODER_properties,
 OSSL_ENCODER_is_a,
 OSSL_ENCODER_number,
 OSSL_ENCODER_do_all_provided,
-OSSL_ENCODER_names_do_all
+OSSL_ENCODER_names_do_all,
+OSSL_ENCODER_gettable_params,
+OSSL_ENCODER_get_params
 - Encoder method routines
 
 =head1 SYNOPSIS
@@ -34,11 +36,11 @@ OSSL_ENCODER_names_do_all
  void OSSL_ENCODER_names_do_all(const OSSL_ENCODER *encoder,
                                 void (*fn)(const char *name, void *data),
                                 void *data);
+ const OSSL_PARAM *OSSL_ENCODER_gettable_params(OSSL_ENCODER *encoder);
+ int OSSL_ENCODER_get_params(OSSL_ENCODER_CTX *ctx, const OSSL_PARAM params[]);
 
 =head1 DESCRIPTION
 
-=for comment Future development should also talk about decoding
-
 B<OSSL_ENCODER> is a method for encoders, which know how to
 encode an object of some kind to a encoded form, such as PEM,
 DER, or even human readable text.
@@ -78,6 +80,13 @@ implementations by all activated providers in the library context
 I<libctx>, and for each of the implementations, calls I<fn> with the
 implementation method and I<data> as arguments.
 
+OSSL_ENCODER_gettable_params() returns an L<OSSL_PARAM(3)>
+array of parameter descriptors.
+
+OSSL_ENCODER_get_params() attempts to get parameters specified
+with an L<OSSL_PARAM(3)> array I<params>.  Parameters that the
+implementation doesn't recognise should be ignored.
+
 =head1 NOTES
 
 OSSL_ENCODER_fetch() may be called implicitly by other fetching
diff --git a/doc/man3/OSSL_ENCODER_CTX.pod b/doc/man3/OSSL_ENCODER_CTX.pod
index bf339c6a4f..ccf847db47 100644
--- a/doc/man3/OSSL_ENCODER_CTX.pod
+++ b/doc/man3/OSSL_ENCODER_CTX.pod
@@ -4,10 +4,24 @@
 
 OSSL_ENCODER_CTX,
 OSSL_ENCODER_CTX_new,
-OSSL_ENCODER_CTX_get_encoder,
 OSSL_ENCODER_settable_ctx_params,
 OSSL_ENCODER_CTX_set_params,
-OSSL_ENCODER_CTX_free
+OSSL_ENCODER_CTX_free,
+OSSL_ENCODER_CTX_set_output_type,
+OSSL_ENCODER_CTX_set_selection,
+OSSL_ENCODER_CTX_add_encoder,
+OSSL_ENCODER_CTX_add_extra,
+OSSL_ENCODER_CTX_get_num_encoders,
+OSSL_ENCODER_INSTANCE,
+OSSL_ENCODER_INSTANCE_get_encoder,
+OSSL_ENCODER_INSTANCE_get_encoder_ctx,
+OSSL_ENCODER_INSTANCE_get_input_type,
+OSSL_ENCODER_INSTANCE_get_output_type,
+OSSL_ENCODER_CONSTRUCT,
+OSSL_ENCODER_CLEANUP,
+OSSL_ENCODER_CTX_set_construct,
+OSSL_ENCODER_CTX_set_construct_data,
+OSSL_ENCODER_CTX_set_cleanup
 - Encoder context routines
 
 =head1 SYNOPSIS
@@ -16,36 +30,66 @@ OSSL_ENCODER_CTX_free
 
  typedef struct ossl_encoder_ctx_st OSSL_ENCODER_CTX;
 
- OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new(OSSL_ENCODER *encoder);
- const OSSL_ENCODER *OSSL_ENCODER_CTX_get_encoder(OSSL_ENCODER_CTX *ctx);
+ OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new();
  const OSSL_PARAM *OSSL_ENCODER_settable_ctx_params(OSSL_ENCODER *encoder);
  int OSSL_ENCODER_CTX_set_params(OSSL_ENCODER_CTX *ctx,
                                  const OSSL_PARAM params[]);
  void OSSL_ENCODER_CTX_free(OSSL_ENCODER_CTX *ctx);
 
+ int OSSL_ENCODER_CTX_set_output_type(OSSL_ENCODER_CTX *ctx,
+                                      const char *output_type);
+ int OSSL_ENCODER_CTX_set_selection(OSSL_ENCODER_CTX *ctx, int selection);
+
+ int OSSL_ENCODER_CTX_add_encoder(OSSL_ENCODER_CTX *ctx, OSSL_ENCODER *encoder);
+ int OSSL_ENCODER_CTX_add_extra(OSSL_ENCODER_CTX *ctx,
+                                OPENSSL_CTX *libctx, const char *propq);
+ int OSSL_ENCODER_CTX_get_num_encoders(OSSL_ENCODER_CTX *ctx);
+
+ typedef struct ossl_encoder_instance_st OSSL_ENCODER_INSTANCE;
+ OSSL_ENCODER *
+ OSSL_ENCODER_INSTANCE_get_encoder(OSSL_ENCODER_INSTANCE *encoder_inst);
+ void *
+ OSSL_ENCODER_INSTANCE_get_encoder_ctx(OSSL_ENCODER_INSTANCE *encoder_inst);
+ const char *
+ OSSL_ENCODER_INSTANCE_get_input_type(OSSL_ENCODER_INSTANCE *encoder_inst);
+ const char *
+ OSSL_ENCODER_INSTANCE_get_output_type(OSSL_ENCODER_INSTANCE *encoder_inst);
+
+ typedef const void *OSSL_ENCODER_CONSTRUCT(OSSL_ENCODER_INSTANCE *encoder_inst,
+                                            void *construct_data);
+ typedef void OSSL_ENCODER_CLEANUP(void *construct_data);
+
+ int OSSL_ENCODER_CTX_set_construct(OSSL_ENCODER_CTX *ctx,
+                                    OSSL_ENCODER_CONSTRUCT *construct);
+ int OSSL_ENCODER_CTX_set_construct_data(OSSL_ENCODER_CTX *ctx,
+                                         void *construct_data);
+ int OSSL_ENCODER_CTX_set_cleanup(OSSL_ENCODER_CTX *ctx,
+                                  OSSL_ENCODER_CLEANUP *cleanup);
+
 =head1 DESCRIPTION
 
-B<OSSL_ENCODER_CTX> is a context with which B<OSSL_ENCODER>
-operations are performed.  The context typically holds values, both
-internal and supplied by the application, which are useful for the
-implementations supplied by providers.
+Encoding an input object to the desired encoding may be done with a chain of
+encoder implementations, which means that the output from one encoder may be
+the input for the next in the chain.  The B<OSSL_ENCODER_CTX> holds all the
+data about these encoders.  This allows having generic format encoders such
+as DER to PEM, as well as more specialized encoders like RSA to DER.
 
-OSSL_ENCODER_CTX_new() creates a B<OSSL_ENCODER_CTX> associated
-with the encoder I<encoder>.  NULL is a valid I<encoder>, the context will
-be created anyway, it's just not very useful.  This is intentional, to
-distinguish between errors in allocating the context or assigning it
-values on one hand, and the lack of encoder support on the other.
+The final output type must be given, and a chain of encoders must end with
+an implementation that produces that output type.
 
-=begin comment
+At the beginning of the encoding process, a contructor provided by the
+caller is called to ensure that there is an appropriate provider-side object
+to start with.
+The constructor is set with OSSL_ENCODER_CTX_set_construct().
 
-The above distinction makes it possible for other routines to sense if
-they need to report an error or fall back on other methods to
-encode.
+B<OSSL_ENCODER_INSTANCE> is an opaque structure that contains data about the
+encoder that is going to be used, and that may be useful for the
+constructor.  There are some functions to extract data from this type,
+described in L</Constructor> below.
 
-=end comment
+=head2 Functions
 
-OSSL_ENCODER_CTX_get_encoder() gets the encoder method
-currently associated with the context I<ctx>.
+OSSL_ENCODER_CTX_new() creates a B<OSSL_ENCODER_CTX>.
 
 OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)>
 array of parameter descriptors.
@@ -56,22 +100,93 @@ implementation doesn't recognise should be ignored.
 
 OSSL_ENCODER_CTX_free() frees the given context I<ctx>.
 
+OSSL_ENCODER_CTX_add_encoder() populates the B<OSSL_ENCODER_CTX>
+I<ctx> with a encoder, to be used to encode an input object.
+
+OSSL_ENCODER_CTX_add_extra() finds encoders that further encodes output
+from already added encoders, and adds them as well.  This is used to build
+encoder chains.
+
+OSSL_ENCODER_CTX_set_output_type() sets the ending output type.  This must
+be specified, and determines if a complete encoder chain is available.
+
+OSSL_ENCODER_CTX_num_encoders() gets the number of encoders currently added
+to the context I<ctx>.
+
+OSSL_ENCODER_CTX_set_construct() sets the constructor I<construct>.
+
+OSSL_ENCODER_CTX_set_construct_data() sets the constructor data that is
+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)>.
+
+=head2 Constructor
+
+A B<OSSL_ENCODER_CONSTRUCT> gets the following arguments:
+
+=over 4
+
+=item I<encoder_inst>
+
+The B<OSSL_ENCODER_INSTANCE> for the encoder from which the constructor gets
+its data.
+
+=item I<construct_data>
+
+The pointer that was set with OSSL_ENCODE_CTX_set_construct_data().
+
+=back
+
+The constructor is expected to return a valid (non-NULL) pointer to a
+provider-native object that can be used as first input of an encoding chain,
+or NULL to indicate that an error has occured.
+
+These utility functions may be used by a constructor:
+
+OSSL_ENCODER_INSTANCE_encoder() can be used to get the encoder method from a
+encoder instance I<encoder_inst>.
+
+OSSL_ENCODER_INSTANCE_encoder_ctx() can be used to get the encoder method's
+provider context from a encoder instance I<encoder_inst>.
+
+OSSL_ENCODER_INSTANCE_input_type() can be used to get the input type for
+encoder method from a encoder instance I<encoder_inst>.  This may be NULL.
+
+OSSL_ENCODER_INSTANCE_output_type() can be used to get the output type for
+encoder method from a encoder instance I<encoder_inst>.  This will never be
+NULL.
+
 =head1 RETURN VALUES
 
-OSSL_ENCODER_CTX_new() returns a pointer to a
-B<OSSL_ENCODER_CTX>, or NULL if the context structure couldn't be
-allocated.
+OSSL_ENCODER_CTX_new() returns a pointer to a B<OSSL_ENCODER_CTX>, or NULL
+if the context structure couldn't be allocated.
 
-OSSL_ENCODER_CTX_get_encoder() returns a pointer to the
-encoder method associated with I<ctx>.  NULL is a valid return
-value and signifies that there is no associated encoder method.
+OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)> array, or
+NULL if none is available.
 
-OSSL_ENCODER_settable_ctx_params() returns an L<OSSL_PARAM(3)>
-array, or NULL if none is available.
+OSSL_ENCODER_CTX_set_params() returns 1 if all recognised parameters were
+valid, or 0 if one of them was invalid or caused some other failure in the
+implementation.
+
+OSSL_DECODER_CTX_add_decoder(), OSSL_DECODER_CTX_add_extra(),
+OSSL_DECODER_CTX_set_construct(), OSSL_DECODER_CTX_set_construct_data() and
+OSSL_DECODER_CTX_set_cleanup() return 1 on success, or 0 on failure.
+
+OSSL_DECODER_CTX_num_decoders() returns the current number of decoders.  It
+returns 0 if I<ctx> is NULL.
+
+OSSL_DECODER_INSTANCE_decoder() returns an B<OSSL_DECODER> pointer on
+success, or NULL on failure.
+
+OSSL_DECODER_INSTANCE_decoder_ctx() returns a provider context pointer on
+success, or NULL on failure.
+
+OSSL_ENCODER_INSTANCE_input_type() returns a string with the name of the
+input type, if relevant.  NULL is a valid returned value.
 
-OSSL_ENCODER_CTX_set_params() returns 1 if all recognised
-parameters were valid, or 0 if one of them was invalid or caused some
-other failure in the implementation.
+OSSL_ENCODER_INSTANCE_output_type() returns a string with the name of the
+output type.
 
 =head1 SEE ALSO
 
diff --git a/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod b/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod
index 2aa103fd14..a97208cbe3 100644
--- a/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod
+++ b/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod
@@ -5,25 +5,19 @@
 OSSL_ENCODER_CTX_new_by_EVP_PKEY,
 OSSL_ENCODER_CTX_set_cipher,
 OSSL_ENCODER_CTX_set_passphrase,
+OSSL_ENCODER_CTX_set_pem_password_cb,
 OSSL_ENCODER_CTX_set_passphrase_cb,
-OSSL_ENCODER_CTX_set_passphrase_ui,
-OSSL_ENCODER_PUBKEY_TO_PEM_PQ,
-OSSL_ENCODER_PrivateKey_TO_PEM_PQ,
-OSSL_ENCODER_Parameters_TO_PEM_PQ,
-OSSL_ENCODER_PUBKEY_TO_DER_PQ,
-OSSL_ENCODER_PrivateKey_TO_DER_PQ,
-OSSL_ENCODER_Parameters_TO_DER_PQ,
-OSSL_ENCODER_PUBKEY_TO_TEXT_PQ,
-OSSL_ENCODER_PrivateKey_TO_TEXT_PQ,
-OSSL_ENCODER_Parameters_TO_TEXT_PQ
+OSSL_ENCODER_CTX_set_passphrase_ui
 - Encoder routines to encode EVP_PKEYs
 
 =head1 SYNOPSIS
 
  #include <openssl/encoder.h>
 
- OSSL_ENCODER_CTX *OSSL_ENCODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey,
-                                                    const char *propquery);
+ OSSL_ENCODER_CTX *
+ OSSL_ENCODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey,
+                                  const char *output_type, int selection,
+                                  OPENSSL_CTX *libctx, const char *propquery);
 
  int OSSL_ENCODER_CTX_set_cipher(OSSL_ENCODER_CTX *ctx,
                                  const char *cipher_name,
@@ -31,45 +25,39 @@ OSSL_ENCODER_Parameters_TO_TEXT_PQ
  int OSSL_ENCODER_CTX_set_passphrase(OSSL_ENCODER_CTX *ctx,
                                      const unsigned char *kstr,
                                      size_t klen);
- int OSSL_ENCODER_CTX_set_passphrase_cb(OSSL_ENCODER_CTX *ctx,
-                                        pem_password_cb *cb, void *cbarg);
+ int OSSL_ENCODER_CTX_set_pem_password_cb(OSSL_ENCODER_CTX *ctx,
+                                          pem_password_cb *cb, void *cbarg);
  int OSSL_ENCODER_CTX_set_passphrase_ui(OSSL_ENCODER_CTX *ctx,
                                         const UI_METHOD *ui_method,
                                         void *ui_data);
-
- #define OSSL_ENCODER_PUBKEY_TO_PEM_PQ "format=pem,type=public"
- #define OSSL_ENCODER_PrivateKey_TO_PEM_PQ "format=pem,type=private"
- #define OSSL_ENCODER_Parameters_TO_PEM_PQ "format=pem,type=parameters"
-
- #define OSSL_ENCODER_PUBKEY_TO_DER_PQ "format=der,type=public"
- #define OSSL_ENCODER_PrivateKey_TO_DER_PQ "format=der,type=private"
- #define OSSL_ENCODER_Parameters_TO_DER_PQ "format=der,type=parameters"
-
- #define OSSL_ENCODER_PUBKEY_TO_TEXT_PQ "format=text,type=public"
- #define OSSL_ENCODER_PrivateKey_TO_TEXT_PQ "format=text,type=private"
- #define OSSL_ENCODER_Parameters_TO_TEXT_PQ "format=text,type=parameters"
+ int OSSL_ENCODER_CTX_set_passphrase_cb(OSSL_ENCODER_CTX *ctx,
+                                        OSSL_PASSPHRASE_CALLBACK *cb,
+                                        void *cbarg);
 
 =head1 DESCRIPTION
 
-OSSL_ENCODER_CTX_new_by_EVP_PKEY() creates a B<OSSL_ENCODER_CTX>
-with a suitable attached output routine for B<EVP_PKEY>s.  It will
-search for a encoder implementation that matches the algorithm of
-the B<EVP_PKEY> and the property query given with I<propquery>.  It
-will prefer to find a encoder from the same provider as the key
-data of the B<EVP_PKEY> itself, but failing that, it will choose the
-first encoder that supplies a generic encoding function.
-
-If no suitable encoder was found, OSSL_ENCODER_CTX_new_by_EVP_PKEY()
-still creates a B<OSSL_ENCODER_CTX>, but with no associated
-encoder (L<OSSL_ENCODER_CTX_get_encoder(3)> returns NULL).
-This helps the caller distinguish between an error when creating
-the B<OSSL_ENCODER_CTX>, and the lack the encoder support and
+OSSL_ENCODER_CTX_new_by_EVP_PKEY() is a utility function that creates a
+B<OSSL_ENCODER_CTX>, finds all applicable encoder implementations and sets
+them up, so almost all the caller has to do next is call functions like
+L<OSSL_ENCODER_to_bio(3)>.
+
+Internally, OSSL_ENCODER_CTX_new_by_EVP_PKEY() uses the names from the
+L<EVP_KEYMGMT(3)> implementation associated with I<pkey> to build a list of
+applicable encoder implementations that are used to process the I<pkey> into
+the encoding named by I<output_type>.  All these implementations are
+implicitly fetched using I<libctx> and I<propquery>.
+
+If no suitable encoder implementation is found,
+OSSL_ENCODER_CTX_new_by_EVP_PKEY() still creates a B<OSSL_ENCODER_CTX>, but
+with no associated encoder (L<OSSL_ENCODER_CTX_get_num_encoders(3)> returns
+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.
 
 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
-implementation dependent.  The implementation may implement the digest
+implementation dependent.  The implementation may implement the cipher
 directly itself or by other implementations, or it may choose to fetch
 it.  If the implementation supports fetching the cipher, then it may
 use I<propquery> as properties to be queried for when fetching.
@@ -81,48 +69,30 @@ pass phrase to use when encrypting the encoded private key.
 Alternatively, a pass phrase callback may be specified with the
 following functions.
 
-OSSL_ENCODER_CTX_set_passphrase_cb() and
-OSSL_ENCODER_CTX_set_passphrase_ui() sets up a callback method that
-the implementation can use to prompt for a pass phrase.
-
-=for comment Note that the callback method is called indirectly,
+OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui()
+and OSSL_ENCODER_CTX_set_passphrase_cb() sets up a callback method that the
+implementation can use to prompt for a pass phrase, giving the caller the
+choice of prefered pass phrase callback form.  These are called indirectly,
 through an internal B<OSSL_PASSPHRASE_CALLBACK> function.
 
-The macros B<OSSL_ENCODER_PUBKEY_TO_PEM_PQ>,
-B<OSSL_ENCODER_PrivateKey_TO_PEM_PQ>,
-B<OSSL_ENCODER_Parameters_TO_PEM_PQ>,
-B<OSSL_ENCODER_PUBKEY_TO_DER_PQ>,
-B<OSSL_ENCODER_PrivateKey_TO_DER_PQ>,
-B<OSSL_ENCODER_Parameters_TO_DER_PQ>,
-B<OSSL_ENCODER_PUBKEY_TO_TEXT_PQ>,
-B<OSSL_ENCODER_PrivateKey_TO_TEXT_PQ>,
-B<OSSL_ENCODER_Parameters_TO_TEXT_PQ> are convenience macros with
-property queries to encode the B<EVP_PKEY> as a public key, private
-key or parameters to B<PEM>, to B<DER>, or to text.
-
 =head1 RETURN VALUES
 
 OSSL_ENCODER_CTX_new_by_EVP_PKEY() returns a pointer to a
 B<OSSL_ENCODER_CTX>, or NULL if it couldn't be created.
 
-OSSL_ENCODER_CTX_set_cipher(),
-OSSL_ENCODER_CTX_set_passphrase(),
-OSSL_ENCODER_CTX_set_passphrase_cb(), and
-OSSL_ENCODER_CTX_set_passphrase_ui() all return 1 on success, or 0
-on failure.
+OSSL_ENCODER_CTX_set_cipher(), OSSL_ENCODER_CTX_set_passphrase(),
+OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui()
+and OSSL_ENCODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on
+failure.
 
 =head1 NOTES
 
-Parts of the function and macro names are made to match already
-existing OpenSSL names.
-
-B<EVP_PKEY> in OSSL_ENCODER_CTX_new_by_EVP_PKEY() matches the type
-name, thus making for the naming pattern
-B<OSSL_ENCODER_CTX_new_by_I<TYPE>>() when new types are handled.
+Parts of the function names are made to match already existing OpenSSL
+names.
 
-B<PUBKEY>, B<PrivateKey> and B<Parameters> in the macro names match
-the B<I<TYPE>> part of B<PEM_write_bio_I<TYPE>> functions as well
-as B<i2d_I<TYPE>_bio> functions.
+B<EVP_PKEY> in OSSL_ENCODER_CTX_new_by_EVP_PKEY() matches the type name,
+thus making for the naming pattern B<OSSL_ENCODER_CTX_new_by_I<TYPE>>() when
+new types are handled.
 
 =head1 SEE ALSO
 
diff --git a/doc/man3/OSSL_ENCODER_to_bio.pod b/doc/man3/OSSL_ENCODER_to_bio.pod
index ee9998b2eb..6f75f592e4 100644
--- a/doc/man3/OSSL_ENCODER_to_bio.pod
+++ b/doc/man3/OSSL_ENCODER_to_bio.pod
@@ -4,7 +4,7 @@
 
 OSSL_ENCODER_to_bio,
 OSSL_ENCODER_to_fp
-- Encoder file output routines
+- Routines to perform an encoding
 
 =head1 SYNOPSIS
 
@@ -24,10 +24,10 @@ is undefined.
 
 =head1 DESCRIPTION
 
-OSSL_ENCODER_to_bio() runs the encoding process for the
-context I<ctx>, with the output going to the B<BIO> I<out>.  The
-application is required to set up the B<BIO> properly, for example to
-have it in text or binary mode if that's appropriate.
+OSSL_ENCODER_to_bio() runs the encoding process for the context I<ctx>, with
+the output going to the B<BIO> I<out>.  The application is required to set
+up the B<BIO> properly, for example to have it in text or binary mode if
+that's appropriate.
 
 =for comment Know your encoder!
 
@@ -36,8 +36,16 @@ except that the output is going to the B<FILE> I<fp>.
 
 =head1 RETURN VALUES
 
-OSSL_ENCODER_to_bio() and OSSL_ENCODER_to_fp() return 1 on
-success, or 0 on failure.
+OSSL_ENCODER_to_bio() and OSSL_ENCODER_to_fp() return 1 on success, or 0 on
+failure.
+
+=begin comment TODO(3.0) Add examples!
+
+=head1 EXAMPLES
+
+Text, because pod2xxx doesn't like empty sections
+
+=end comment
 
 =head1 SEE ALSO
 
@@ -49,7 +57,7 @@ The functions described here were added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2020 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