--- /dev/null
+=pod
+
+=head1 NAME
+
+provider-encoder - The ENCODER 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.
+ */
+
+ /* Functions to construct / destruct / manipulate the encoder context */
+ void *OSSL_FUNC_encoder_newctx(void *provctx);
+ void OSSL_FUNC_encoder_freectx(void *ctx);
+ int OSSL_FUNC_encoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
+ const OSSL_PARAM *OSSL_FUNC_encoder_settable_ctx_params(void *provctx)
+
+ /* Functions to encode object data */
+ int OSSL_FUNC_encoder_encode_data(void *ctx, const OSSL_PARAM *data,
+ OSSL_CORE_BIO *out,
+ OSSL_PASSPHRASE_CALLBACK *cb,
+ void *cbarg);
+ int OSSL_FUNC_encoder_encode_object(void *ctx, void *obj, OSSL_CORE_BIO *out,
+ OSSL_PASSPHRASE_CALLBACK *cb,
+ void *cbarg);
+
+=head1 DESCRIPTION
+
+I<We use the wide term "encode" in this manual. This includes but is
+not limited to serialization.>
+
+The ENCODER is a generic method to encode any set of object data
+in L<OSSL_PARAM(3)> array form, or any provider side object into
+encoded form, and write it to the given OSSL_CORE_BIO. If the caller wants
+to get the encoded stream to memory, it should provide a
+L<BIO_s_membuf(3)>.
+
+The encoder 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 encoding using the L<OSSL_PARAM(3)> array form allows a
+encoder to be used for data that's been exported from another
+provider, and thereby allow them to exist independently of each
+other.
+
+The encoding 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_FUNC_{name}>.
+For example, the "function" OSSL_FUNC_encoder_encode_data() has these:
+
+ typedef int
+ (OSSL_FUNC_encoder_encode_data_fn)(void *provctx,
+ const OSSL_PARAM params[],
+ OSSL_CORE_BIO *out);
+ static ossl_inline OSSL_FUNC_encoder_encode_data_fn
+ OSSL_FUNC_encoder_encode_data(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_encoder_newctx OSSL_FUNC_ENCODER_NEWCTX
+ OSSL_FUNC_encoder_freectx OSSL_FUNC_ENCODER_FREECTX
+ OSSL_FUNC_encoder_set_ctx_params OSSL_FUNC_ENCODER_SET_CTX_PARAMS
+ OSSL_FUNC_encoder_settable_ctx_params OSSL_FUNC_ENCODER_SETTABLE_CTX_PARAMS
+
+ OSSL_FUNC_encoder_encode_data OSSL_FUNC_ENCODER_ENCODE_DATA
+ OSSL_FUNC_encoder_encode_object OSSL_FUNC_ENCODER_ENCODE_OBJECT
+
+=head2 Names and properties
+
+The name of an implementation should match the type of object it
+handles. For example, an implementation that encodes an RSA key
+should be named accordingly.
+
+To be able to specify exactly what encoding format and what type
+of data a encoder 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 key 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 parameters
+
+An implementation with that format property value outputs key
+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
+
+OSSL_FUNC_encoder_newctx() returns a context to be used with the rest of
+the functions.
+
+OSSL_FUNC_encoder_freectx() frees the given I<ctx>, if it was created by
+OSSL_FUNC_encoder_newctx().
+
+OSSL_FUNC_encoder_set_ctx_params() sets context data according to
+parameters from I<params> that it recognises. Unrecognised parameters
+should be ignored.
+
+OSSL_FUNC_encoder_settable_ctx_params() returns a constant B<OSSL_PARAM>
+array describing the parameters that OSSL_FUNC_encoder_set_ctx_params()
+can handle.
+
+See L<OSSL_PARAM(3)> for further details on the parameters structure used
+by OSSL_FUNC_encoder_set_ctx_params() and OSSL_FUNC_encoder_settable_ctx_params().
+
+=head2 Encoding functions
+
+=for comment There will be a "Decoding functions" title as well
+
+OSSL_FUNC_encoder_encode_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
+encoded form to the B<OSSL_CORE_BIO>.
+
+OSSL_FUNC_encoder_encode_object() should take a pointer to an object
+that it knows intimately, and output that object in encoded form to
+the B<OSSL_CORE_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 encoding 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 Encoder parameters
+
+Parameters currently recognised by built-in encoders are as
+follows:
+
+=over 4
+
+=item "cipher" (B<OSSL_ENCODER_PARAM_CIPHER>) <UTF8 string>
+
+The name of the encryption cipher to be used when generating encrypted
+encoding. This is used when encoding private keys, as well as
+other objects that need protection.
+
+If this name is invalid for the encoding implementation, the
+implementation should refuse to perform the encoding, i.e.
+OSSL_FUNC_encoder_encode_data() and OSSL_FUNC_encoder_encode_object()
+should return an error.
+
+=item "properties" (B<OSSL_ENCODER_PARAM_PROPERTIES>) <UTF8 string>
+
+The properties to be queried when trying to fetch the algorithm given
+with the "cipher" parameter.
+This must be given together with the "cipher" parameter to be
+considered valid.
+
+The encoding implementation isn't obligated to use this value.
+However, it is recommended that implementations that do not handle
+property strings return an error on receiving this parameter unless
+its value NULL or the empty string.
+
+=item "passphrase" (B<OSSL_ENCODER_PARAM_PASS>) <octet string>
+
+A pass phrase provided by the application. When this is given, the
+built-in encoders will not attempt to use the passphrase callback.
+
+=back
+
+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_encoder_newctx() returns a pointer to a context, or NULL on
+failure.
+
+OSSL_FUNC_encoder_set_ctx_params() returns 1, unless a recognised
+parameters was invalid or caused an error, for which 0 is returned.
+
+OSSL_FUNC_encoder_settable_ctx_params() returns a pointer to an array of
+constant B<OSSL_PARAM> elements.
+
+OSSL_FUNC_encoder_encode_data() and OSSL_FUNC_encoder_encode_object()
+return 1 on success, or 0 on failure.
+
+=head1 SEE ALSO
+
+L<provider(7)>
+
+=head1 HISTORY
+
+The ENCODER interface was introduced in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+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
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
projects / openssl.git / blobdiff