provider-decoder.pod: Documentation of provider side decoder API

Fixes #13949

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14756)

2 files changed, 343 insertions, 0 deletions

diff --git a/doc/build.info b/doc/build.info
index 48730cf945..7ac089005d 100644
--- a/doc/build.info
+++ b/doc/build.info
@@ -4272,6 +4272,10 @@ DEPEND[html/man7/provider-cipher.html]=man7/provider-cipher.pod
 GENERATE[html/man7/provider-cipher.html]=man7/provider-cipher.pod
 DEPEND[man/man7/provider-cipher.7]=man7/provider-cipher.pod
 GENERATE[man/man7/provider-cipher.7]=man7/provider-cipher.pod
+DEPEND[html/man7/provider-decoder.html]=man7/provider-decoder.pod
+GENERATE[html/man7/provider-decoder.html]=man7/provider-decoder.pod
+DEPEND[man/man7/provider-decoder.7]=man7/provider-decoder.pod
+GENERATE[man/man7/provider-decoder.7]=man7/provider-decoder.pod
 DEPEND[html/man7/provider-digest.html]=man7/provider-digest.pod
 GENERATE[html/man7/provider-digest.html]=man7/provider-digest.pod
 DEPEND[man/man7/provider-digest.7]=man7/provider-digest.pod
@@ -4419,6 +4423,7 @@ html/man7/property.html \
 html/man7/provider-asym_cipher.html \
 html/man7/provider-base.html \
 html/man7/provider-cipher.html \
+html/man7/provider-decoder.html \
 html/man7/provider-digest.html \
 html/man7/provider-encoder.html \
 html/man7/provider-kdf.html \
@@ -4521,6 +4526,7 @@ man/man7/property.7 \
 man/man7/provider-asym_cipher.7 \
 man/man7/provider-base.7 \
 man/man7/provider-cipher.7 \
+man/man7/provider-decoder.7 \
 man/man7/provider-digest.7 \
 man/man7/provider-encoder.7 \
 man/man7/provider-kdf.7 \
diff --git a/doc/man7/provider-decoder.pod b/doc/man7/provider-decoder.pod
new file mode 100644
index 0000000000..73f653e063
--- /dev/null
+++ b/doc/man7/provider-decoder.pod
@@ -0,0 +1,337 @@
+=pod
+
+=head1 NAME
+
+provider-decoder - The OSSL_DECODER library E<lt>-E<gt> provider functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/core_dispatch.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.
+  */
+
+ /* Decoder parameter accessor and descriptor */
+ const OSSL_PARAM *OSSL_FUNC_decoder_gettable_params(void *provctx);
+ int OSSL_FUNC_decoder_get_params(OSSL_PARAM params[]);
+
+ /* Functions to construct / destruct / manipulate the decoder context */
+ void *OSSL_FUNC_decoder_newctx(void *provctx);
+ void OSSL_FUNC_decoder_freectx(void *ctx);
+ const OSSL_PARAM *OSSL_FUNC_decoder_settable_ctx_params(void *provctx);
+ int OSSL_FUNC_decoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
+
+ /* Functions to check selection support */
+ int OSSL_FUNC_decoder_does_selection(void *provctx, int selection);
+
+ /* Functions to decode object data */
+ int OSSL_FUNC_decoder_decode(void *ctx, OSSL_CORE_BIO *in,
+                              int selection,
+                              OSSL_CALLBACK *data_cb, void *data_cbarg,
+                              OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
+
+ /* Functions to export a decoded object */
+ void *OSSL_FUNC_decoder_export_object(void *ctx,
+                                       const void *objref, size_t objref_sz,
+                                       OSSL_CALLBACK *export_cb,
+                                       void *export_cbarg);
+
+=head1 DESCRIPTION
+
+I<The term "decode" is used throughout this manual.  This includes but is
+not limited to deserialization as individual decoders can also do
+decoding into intermediate data formats.>
+
+The DECODER operation is a generic method to create a provider-native
+object reference or intermediate decoded data from an encoded form
+read from the given B<OSSL_CORE_BIO>. If the caller wants to decode
+data from memory, it should provide a L<BIO_s_mem(3)> B<BIO>. The decoded
+data or object reference is passed along with eventual metadata
+to the I<metadata_cb> as B<OSSL_PARAM> parameters.
+
+The decoder doesn't need to know more about the B<OSSL_CORE_BIO>
+pointer than being able to pass it to the appropriate BIO upcalls (see
+L<provider-base(7)/Core functions>).
+
+The DECODER implementation may be part of a chain, where data is
+passed from one to the next.  For example, there may be an
+implementation to decode an object from PEM to DER, and another one
+that decodes DER to a provider-native object.
+
+The last decoding step in the decoding chain is usually supposed to create
+a provider-native object referenced by an object reference. To import
+that object into a different provider the OSSL_FUNC_decoder_export_object()
+can be called as the final step of the decoding process.
+
+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_FUNC_{name}_fn>, and a helper function to retrieve the
+function pointer from an B<OSSL_DISPATCH> element named
+B<OSSL_FUNC_{name}>.
+For example, the "function" OSSL_FUNC_decoder_decode() has these:
+
+ typedef int
+     (OSSL_FUNC_decoder_decode_fn)(void *ctx, OSSL_CORE_BIO *in,
+                                   int selection,
+                                   OSSL_CALLBACK *data_cb, void *data_cbarg,
+                                   OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
+ static ossl_inline OSSL_FUNC_decoder_decode_fn
+     OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf);
+
+B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
+macros in L<openssl-core_dispatch.h(7)>, as follows:
+
+ OSSL_FUNC_decoder_get_params          OSSL_FUNC_DECODER_GET_PARAMS
+ OSSL_FUNC_decoder_gettable_params     OSSL_FUNC_DECODER_GETTABLE_PARAMS
+
+ OSSL_FUNC_decoder_newctx              OSSL_FUNC_DECODER_NEWCTX
+ OSSL_FUNC_decoder_freectx             OSSL_FUNC_DECODER_FREECTX
+ OSSL_FUNC_decoder_set_ctx_params      OSSL_FUNC_DECODER_SET_CTX_PARAMS
+ OSSL_FUNC_decoder_settable_ctx_params OSSL_FUNC_DECODER_SETTABLE_CTX_PARAMS
+
+ OSSL_FUNC_decoder_does_selection      OSSL_FUNC_DECODER_DOES_SELECTION
+
+ OSSL_FUNC_decoder_decode              OSSL_FUNC_DECODER_DECODE
+
+ OSSL_FUNC_decoder_export_object       OSSL_FUNC_DECODER_EXPORT_OBJECT
+
+=head2 Names and properties
+
+The name of an implementation should match the target type of object
+it decodes. For example, an implementation that decodes an RSA key
+should be named "RSA". Likewise, an implementation that decodes DER data
+from PEM input should be named "DER".
+
+Properties can be used to further specify details about an implementation:
+
+=over 4
+
+=item input
+
+This property is used to specify what format of input the implementation
+can decode.  OpenSSL providers recognize the following input types:
+
+=over 4
+
+=item pem
+
+An implementation with that input type decodes PEM formatted data.
+
+=item der
+
+An implementation with that input type decodes DER formatted data.
+
+=item msblob
+
+An implementation with that input type decodes MSBLOB formatted data.
+
+=item pvk
+
+An implementation with that input type decodes PVK formatted data.
+
+=back
+
+=item structure
+
+This property is used to specify the structure that the decoded data is
+expected to have. An example could be C<pkcs8>, to specify explicitly that
+the object to be decoded (presumably an asymmetric key pair, in this case)
+is wrapped in a PKCS#8 structure.
+
+=back
+
+The possible values of both these properties is open ended.  A provider may
+very well specify input types and structures that libcrypto doesn't know
+anything about.
+
+=head2 Subset selections
+
+Sometimes, an object has more than one subset of data that is interesting to
+treat separately or together.  It's possible to specify what subsets are to
+be decoded, with a set of bits I<selection> that are passed in an B<int>.
+
+This set of bits depend entirely on what kind of provider-side object is
+to be decoded.  For example, those bits are assumed to be the same as those
+used with L<provider-keymgmt(7)> (see L<provider-keymgmt(7)/Key Objects>) when
+the object is an asymmetric keypair - e.g., B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY>
+if the object to be decoded is supposed to contain private key components.
+
+OSSL_FUNC_decoder_does_selection() should tell if a particular implementation
+supports any of the combinations given by I<selection>.
+
+=head2 Context functions
+
+OSSL_FUNC_decoder_newctx() returns a context to be used with the rest of
+the functions.
+
+OSSL_FUNC_decoder_freectx() frees the given I<ctx> as created by
+OSSL_FUNC_decoder_newctx().
+
+OSSL_FUNC_decoder_set_ctx_params() sets context data according to parameters
+from I<params> that it recognises.  Unrecognised parameters should be
+ignored.
+Passing NULL for I<params> should return true.
+
+OSSL_FUNC_decoder_settable_ctx_params() returns a constant B<OSSL_PARAM>
+array describing the parameters that OSSL_FUNC_decoder_set_ctx_params()
+can handle.
+
+See L<OSSL_PARAM(3)> for further details on the parameters structure used by
+OSSL_FUNC_decoder_set_ctx_params() and OSSL_FUNC_decoder_settable_ctx_params().
+
+=head2 Export function
+
+When a provider-native object is created by a decoder it would be unsuitable
+for direct use with a foreign provider. The export function allows for
+exporting the object into that foreign provider if the foreign provider
+supports the type of the object and provides an import function.
+
+OSSL_FUNC_decoder_export_object() should export the object of size I<objref_sz>
+referenced by I<objref> as an B<OSSL_PARAM> array and pass that into the
+I<export_cb> as well as the given I<export_cbarg>.
+
+=head2 Decoding functions
+
+OSSL_FUNC_decoder_decode() should decode the data as read from
+the B<OSSL_CORE_BIO> I<in> to produce decoded data or an object to be
+passed as reference in an B<OSSL_PARAM> array along with possible other
+metadata that was decoded from the input. This B<OSSL_PARAM> array is
+then passed to the I<data_cb> callback.  The I<selection> bits,
+if relevant, should determine what the input data should contain.
+The decoding 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.
+
+=head2 Decoder parameters
+
+The decoder implementation itself has parameters that can be used to
+determine how it fits in a chain of decoders:
+
+=over 4
+
+=item "input-type" (B<OSSL_DECODER_PARAM_INPUT_TYPE>) <UTF8 string>
+
+This is used to specify the input type for a decoder implementation.
+
+This parameter is I<mandatory>.
+
+Input types currently recognized by built-in decoders:
+
+=over 4
+
+=item "DER"
+
+ASN.1 DER encoded binary data
+
+=item "PEM"
+
+Base64 encoded data with PEM headers
+
+=item "MSBLOB"
+
+Private or public key encoding according to Microsoft specification
+
+=item "PVK"
+
+Encrypted private key encoding according to Microsoft specification
+
+=back
+
+=for comment If we had functionality to get the value of a specific property
+in a set of properties, it would be possible to determine the input type
+from the C<input> property.
+
+=item "input-structure" (B<OSSL_ENCODER_PARAM_INPUT_STRUCTURE>) <UTF8 string>
+
+This is used to specify the outermost input structure for a decoder
+implementation.
+
+For example, an input of type "DER" for a key pair could be structured
+using PKCS#8, or a key type specific structure, such as PKCS#1 for RSA
+keys.
+
+This parameter is I<optional>.
+
+Input structures currently recognized by built-in decoders:
+
+=over 4
+
+=item "type-specific"
+
+Type specific structure.
+
+=item "PKCS8"
+
+Structure according to the PKCS#8 specification.
+
+=item "SubjectPublicKeyInfo"
+
+Encoding of public keys according to the Subject Public Key Info of RFC 5280.
+
+=back
+
+=for comment If we had functionality to get the value of a specific property
+in a set of properties, it would be possible to determine the input
+structure from the C<structure> property.
+
+=back
+
+=head2 Decoder operation parameters
+
+There are currently no operation parameters currently recognised by the
+built-in decoders.
+
+Parameters currently recognised by the built-in pass phrase callback:
+
+=over 4
+
+=item "info" (B<OSSL_PASSPHRASE_PARAM_INFO>) <UTF8 string>
+
+A string of information that will become part of the pass phrase
+prompt.  This could be used to give the user information on what kind
+of object it's being prompted for.
+
+=back
+
+=head1 RETURN VALUES
+
+OSSL_FUNC_decoder_newctx() returns a pointer to a context, or NULL on
+failure.
+
+OSSL_FUNC_decoder_set_ctx_params() returns 1, unless a recognised
+parameter was invalid or caused an error, for which 0 is returned.
+
+OSSL_FUNC_decoder_settable_ctx_params() returns a pointer to an array of
+constant B<OSSL_PARAM> elements.
+
+OSSL_FUNC_decoder_does_selection() returns 1 if the decoder implementation
+supports any of the I<selection> bits, otherwise 0.
+
+OSSL_FUNC_decoder_decode() returns 1 on success, or 0 on failure.
+
+=head1 SEE ALSO
+
+L<provider(7)>
+
+=head1 HISTORY
+
+The DECODER interface was introduced in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019-2021 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