SERIALIZER: New API for serialization of objects through providers

Serialization is needed to be able to take a provider object (such as
the provider side key data) and output it in PEM form, DER form, text
form (for display), and possibly other future forms (XML? JSON? JWK?)

The idea is that a serializer should be able to handle objects it has
intimate knowledge of, as well as object data in OSSL_PARAM form.  The
latter will allow libcrypto to serialize some object with a different
provider than the one holding the data, if exporting of that data is
allowed and there is a serializer that can handle it.

We will provide serializers for the types of objects we know about,
which should be useful together with any other provider that provides
implementations of the same type of object.

Serializers are selected by method name and a couple of additional
properties:

- format        used to tell what format the output should be in.
                Possibilities could include "format=text",
                "format=pem", "format=der", "format=pem-pkcs1"
                (traditional), "format=der-pkcs1" (traditional)
- type          used to tell exactly what type of data should be
                output, for example "type=public" (the public part of
                a key), "type=private" (the private part of a key),
                "type=domainparams" (domain parameters).

This also adds a passphrase callback function type,
OSSL_PASSPHRASE_CALLBACK, which is a bit like OSSL_CALLBACK, but it
takes a few extra arguments to place the result in.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10394)

3 files changed, 257 insertions, 1 deletions

diff --git a/doc/man7/openssl-core.h.pod b/doc/man7/openssl-core.h.pod
index b5323e9d21..28307a97d4 100644
--- a/doc/man7/openssl-core.h.pod
+++ b/doc/man7/openssl-core.h.pod
@@ -76,7 +76,7 @@ B<OSSL_PARAM> is further described in L<OSSL_PARAM(3)>
 
 =item B<OSSL_CALLBACK>
 
-This is a function type for a generic callback function:
+This is a function type for a generic feedback callback function:
 
     typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);
 
@@ -86,6 +86,27 @@ expected to build an B<OSSL_PARAM> array of data it wants or is
 expected to pass back, and pass that as I<params>, as well as
 the caller data pointer it received, as I<arg>.
 
+=item B<OSSL_PASSPHRASE_CALLBACK>
+
+This is a function type for a generic pass phrase callback function:
+
+    typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size,
+                                           size_t *pass_len,
+                                           const OSSL_PARAM params[],
+                                           void *arg);
+
+This callback can be used to prompt the user for a passphrase.  When
+calling it, a buffer to store the pass phrase needs to be given with
+I<pass>, and its size with I<pass_size>.  The length of the prompted
+pass phrase will be given back in I<*pass_len>.
+
+Additional parameters can be passed with the B<OSSL_PARAM> array
+I<params>.
+
+A function that takes a pointer of this type should also take a
+pointer to caller data, which should be passed as I<arg> to this
+callback.
+
 =back
 
 =head1 SEE ALSO
diff --git a/doc/man7/provider-serializer.pod b/doc/man7/provider-serializer.pod
new file mode 100644
index 0000000000..e43e293d60
--- /dev/null
+++ b/doc/man7/provider-serializer.pod
@@ -0,0 +1,227 @@
+=pod
+
+=head1 NAME
+
+provider-serializer - The SERIALIZER library E<lt>-E<gt> provider functions
+
+=head1 SYNOPSIS
+
+=begin comment
+
+Future development will also include deserializing functions.
+
+=end comment
+
+ #include <openssl/core_numbers.h>
+
+ /*
+  * None of these are actual functions, but are displayed like this for
+  * the function signatures for functions that are offered as function
+  * pointers in OSSL_DISPATCH arrays.
+  */
+
+ /* Functions to construct / destruct / manipulate the serializer context */
+ void *OP_serializer_newctx(void *provctx);
+ void OP_serializer_freectx(void *ctx);
+ int OP_serializer_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
+ const OSSL_PARAM *OP_serializer_settable_ctx_params(void)
+
+ /* Functions to serialize object data */
+ int OP_serializer_serialize_data(void *ctx, const OSSL_PARAM *data,
+                                  BIO *out,
+                                  OSSL_PASSPHRASE_CALLBACK *cb,
+                                  void *cbarg);
+ int OP_serializer_serialize_object(void *ctx, void *obj, BIO *out,
+                                    OSSL_PASSPHRASE_CALLBACK *cb,
+                                    void *cbarg);
+
+=head1 DESCRIPTION
+
+The SERIALIZER is a generic method to serialize any set of object data
+in L<OSSL_PARAM(3)> array form, or any provider side object into
+serialized form, and write it to the given BIO.  If the caller wants
+to get the serialized stream to memory, it should provide a
+L<BIO_s_membuf(3)>.
+
+The serializer doesn't need to know more about the B<BIO> pointer than
+being able to pass it to the appropriate BIO upcalls (see
+L<provider-base(7)/Core functions>).
+
+The serialization using the L<OSSL_PARAM(3)> array form allows a
+serializer to be used for data that's been exported from another
+provider, and thereby allow them to exist independently of each
+other.
+
+The serialization using a provider side object can only be safely used
+with provider data coming from the same provider, for example keys
+with the L<KEYMGMT|provider-keymgmt(7)> provider.
+
+All "functions" mentioned here are passed as function pointers between
+F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
+B<OSSL_ALGORITHM> arrays that are returned by the provider's
+provider_query_operation() function
+(see L<provider-base(7)/Provider Functions>).
+
+All these "functions" have a corresponding function type definition
+named B<OSSL_{name}_fn>, and a helper function to retrieve the
+function pointer from a B<OSSL_DISPATCH> element named
+B<OSSL_get_{name}>.
+For example, the "function" OP_serializer_serialize_data() has these:
+
+ typedef int
+     (OSSL_OP_serializer_serialize_data_fn)(void *provctx,
+                                            const OSSL_PARAM params[],
+                                            BIO *out);
+ static ossl_inline OSSL_OP_serializer_serialize_data_fn
+     OSSL_get_OP_serializer_serialize_data(const OSSL_DISPATCH *opf);
+
+B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
+macros in L<openssl-core_numbers.h(7)>, as follows:
+
+ OP_serializer_newctx              OSSL_FUNC_SERIALIZER_NEWCTX
+ OP_serializer_freectx             OSSL_FUNC_SERIALIZER_FREECTX
+ OP_serializer_set_ctx_params      OSSL_FUNC_SERIALIZER_SET_CTX_PARAMS
+ OP_serializer_settable_ctx_params OSSL_FUNC_SERIALIZER_SETTABLE_CTX_PARAMS
+
+ OP_serializer_serialize_data      OSSL_FUNC_SERIALIZER_SERIALIZE_DATA
+ OP_serializer_serialize_object    OSSL_FUNC_SERIALIZER_SERIALIZE_OBJECT
+
+=head2 Names and properties
+
+The name of an implementation should match the type of object it
+handles.  For example, an implementation that serializes an RSA key
+should be named accordingly.
+
+To be able to specify exactly what serialization format and what type
+of data a serializer implementation is expected to handle, two
+additional properties may be given:
+
+=over 4
+
+=item format
+
+This property is used to specify what kind of output format the
+implementation produces.  Currently known formats are:
+
+=over 4
+
+=item text
+
+An implementation with that format property value outputs human
+readable text, making that implementation suitable for C<-text> output
+in diverse L<openssl(1)> commands.
+
+=item pem
+
+An implementation with that format property value outputs PEM
+formatted data.
+
+=item der
+
+An implementation with that format property value outputs DER
+formatted data.
+
+=back
+
+=item type
+
+With objects that have multiple purposes, this can be used to specify
+the purpose type.  The currently known use cases are asymmetric keys
+and domain parameters, where the type can be one of:
+
+=over 4
+
+=item private
+
+An implementation with that format property value outputs a private
+key.
+
+=item public
+
+An implementation with that format property value outputs a public
+key.
+
+=item domainparams
+
+An implementation with that format property value outputs domain
+parameters.
+
+=back
+
+=back
+
+The possible values of both these properties is open ended.  A
+provider may very well specify other formats that libcrypto doesn't
+know anything about.
+
+=head2 Context functions
+
+OP_serializer_newctx() returns a context to be used with the rest of
+the functions.
+
+OP_serializer_freectx() frees the given I<ctx>, if it was created by
+OP_serializer_newctx().
+
+OP_serializer_set_ctx_params() sets context data according to
+parameters from I<params> that it recognises.  Unrecognised parameters
+should be ignored.
+
+OP_serializer_settable_ctx_params() returns a constant B<OSSL_PARAM>
+array describing the parameters that OP_serializer_set_ctx_params()
+can handle.
+
+See L<OSSL_PARAM(3)> for further details on the parameters structure used
+by OP_serializer_set_ctx_params() and OP_serializer_settable_ctx_params().
+
+=head2 Serializing functions
+
+=for comment There will be a "Deserializing functions" title as well
+
+OP_serializer_serialize_data() should take an array of B<OSSL_PARAM>,
+I<data>, and if it contains the data necessary for the object type
+that the implementation handles, it should output the object in
+serialized form to the B<BIO>.
+
+OP_serializer_serialize_object() should take a pointer to an object
+that it knows intimately, and output that object in serialized form to
+the B<BIO>.  The caller I<must> ensure that this function is called
+with a pointer that the provider of this function is familiar with.
+It is not suitable to use with object pointers coming from other
+providers.
+
+Both serialization functions also take an B<OSSL_PASSPHRASE_CALLBACK>
+function pointer along with a pointer to application data I<cbarg>,
+which should be used when a pass phrase prompt is needed.
+
+=head1 RETURN VALUES
+
+OP_serializer_newctx() returns a pointer to a context, or NULL on
+failure.
+
+OP_serializer_set_ctx_params() returns 1, unless a recognised
+parameters was invalid or caused an error, for which 0 is returned.
+
+OP_serializer_settable_ctx_params() returns a pointer to an array of
+constant B<OSSL_PARAM> elements.
+
+OP_serializer_serialize_data() and OP_serializer_serialize_object()
+return 1 on success, or 0 on failure.
+
+=head1 SEE ALSO
+
+L<provider(7)>
+
+=head1 HISTORY
+
+The SERIALIZER interface was introduced in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 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
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod
index c3405b6f22..b6c5e49f50 100644
--- a/doc/man7/provider.pod
+++ b/doc/man7/provider.pod
@@ -147,6 +147,14 @@ The number for this operation is B<OSSL_OP_KEYEXCH>.
 The functions the provider can offer are described in
 L<provider-keyexch(7)>
 
+=item Serialization
+
+In the OpenSSL libraries, the corresponding method object is
+B<OSSL_SERIALIZER>.
+The number for this operation is B<OSSL_OP_SERIALIZER>.
+The functions the provider can offer are described in
+L<provider-serializer(7)>
+
 =back
 
 =head2 Fetching algorithms