mirror of
https://github.com/openssl/openssl.git
synced 2024-12-27 06:21:43 +08:00
9379bf943a
The OSSL_DECODER library used to ask each decoder implementation for certain data in form of parameters to place them correctly in the decoder chain, if at all. These parameters were duplicates of properties of those same implementations, and therefore unnecessarily redundant. Now that we have functionality to query property definition values, those duplicates are no longer needed, and are therefore not looked at any more. This adds the "global" error reason ERR_R_INVALID_PROPERTY_DEFINITION, which can be re-used elsewhere. Reviewed-by: Tomas Mraz <tomas@openssl.org> Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from https://github.com/openssl/openssl/pull/15570)
313 lines
11 KiB
Plaintext
313 lines
11 KiB
Plaintext
=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.
|
|
|
|
This property is I<mandatory>.
|
|
|
|
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.
|
|
|
|
This property is I<optional>.
|
|
|
|
Structures currently recognised 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
|
|
|
|
=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.
|
|
|
|
It's important to understand that the return value from this function is
|
|
interpreted as follows:
|
|
|
|
=over 4
|
|
|
|
=item True (1)
|
|
|
|
This means "carry on the decoding process", and is meaningful even though
|
|
this function couldn't decode the input into anything, because there may be
|
|
another decoder implementation that can decode it into something.
|
|
|
|
The I<data_cb> callback should never be called when this function can't
|
|
decode the input into anything.
|
|
|
|
=item False (0)
|
|
|
|
This means "stop the decoding process", and is meaningful when the input
|
|
could be decoded into some sort of object that this function understands,
|
|
but further treatment of that object results into errors that won't be
|
|
possible for some other decoder implementation to get a different result.
|
|
|
|
=back
|
|
|
|
The conditions to stop the decoding process are at the discretion of the
|
|
implementation.
|
|
|
|
=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 to signal that the decoding process
|
|
should continue, or 0 to signal that it should stop.
|
|
|
|
=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
|