mirror of
https://github.com/openssl/openssl.git
synced 2024-12-09 05:51:54 +08:00
14c8a3d118
This is placed as CORE because the core of libcrypto is the authority
for what is possible to do and what's required to make these abstract
objects work.
In essence, an abstract object is an OSSL_PARAM array with well
defined parameter keys and values:
- an object type, which is a number indicating what kind of
libcrypto structure the object in question can be used with. The
currently possible numbers are defined in <openssl/core_object.h>.
- an object data type, which is a string that indicates more closely
what the contents of the object are.
- the object data, an octet string. The exact encoding used depends
on the context in which it's used. For example, the decoder
sub-system accepts any encoding, as long as there is a decoder
implementation that takes that as input. If central code is to
handle the data directly, DER encoding is assumed. (*)
- an object reference, also an octet string. This octet string is
not the object contents, just a mere reference to a provider-native
object. (**)
- an object description, which is a human readable text string that
can be displayed if some software desires to do so.
The intent is that certain provider-native operations (called X
here) are able to return any sort of object that belong with other
operations, or an object that has no provider support otherwise.
(*) A future extension might be to be able to specify encoding.
(**) The possible mechanisms for dealing with object references are:
- An object loading function in the target operation. The exact
target operation is determined by the object type (for example,
OSSL_OBJECT_PKEY implies that the target operation is a KEYMGMT)
and the implementation to be fetched by its object data type (for
an OSSL_OBJECT_PKEY, that's the KEYMGMT keytype to be fetched).
This loading function is only useful for this if the implementations
that are involved (X and KEYMGMT, for example) are from the same
provider.
- An object exporter function in the operation X implementation.
That exporter function can be used to export the object data in
OSSL_PARAM form that can be imported by a target operation's
import function. This can be used when it's not possible to fetch
the target operation implementation from the same provider.
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/12512)
240 lines
8.2 KiB
Plaintext
240 lines
8.2 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
OSSL_DECODER_from_bio,
|
|
OSSL_DECODER_from_fp,
|
|
OSSL_DECODER_CTX_set_input_type,
|
|
OSSL_DECODER_CTX_add_decoder,
|
|
OSSL_DECODER_CTX_add_extra,
|
|
OSSL_DECODER_CTX_num_decoders,
|
|
OSSL_DECODER_INSTANCE,
|
|
OSSL_DECODER_CONSTRUCT,
|
|
OSSL_DECODER_CLEANUP,
|
|
OSSL_DECODER_CTX_set_construct,
|
|
OSSL_DECODER_CTX_set_construct_data,
|
|
OSSL_DECODER_CTX_set_cleanup,
|
|
OSSL_DECODER_CTX_get_construct,
|
|
OSSL_DECODER_CTX_get_construct_data,
|
|
OSSL_DECODER_CTX_get_cleanup,
|
|
OSSL_DECODER_export,
|
|
OSSL_DECODER_INSTANCE_decoder,
|
|
OSSL_DECODER_INSTANCE_decoder_ctx
|
|
- Routines to perform a decoding
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/decoder.h>
|
|
|
|
int OSSL_DECODER_from_bio(OSSL_DECODER_CTX *ctx, BIO *in);
|
|
int OSSL_DECODER_from_fp(OSSL_DECODER_CTX *ctx, FILE *fp);
|
|
|
|
int OSSL_DECODER_CTX_set_input_type(OSSL_DECODER_CTX *ctx,
|
|
const char *input_type);
|
|
int OSSL_DECODER_CTX_add_decoder(OSSL_DECODER_CTX *ctx, OSSL_DECODER *decoder);
|
|
int OSSL_DECODER_CTX_add_extra(OSSL_DECODER_CTX *ctx);
|
|
int OSSL_DECODER_CTX_num_decoders(OSSL_DECODER_CTX *ctx);
|
|
|
|
typedef struct ossl_decoder_instance_st OSSL_DECODER_INSTANCE;
|
|
OSSL_DECODER *
|
|
OSSL_DECODER_INSTANCE_decoder(OSSL_DECODER_INSTANCE *decoder_inst);
|
|
void *OSSL_DECODER_INSTANCE_decoder_ctx(OSSL_DECODER_INSTANCE *decoder_inst);
|
|
|
|
typedef int (OSSL_DECODER_CONSTRUCT)(OSSL_DECODER_INSTANCE *decoder_inst,
|
|
const OSSL_PARAM *object,
|
|
void *construct_data);
|
|
typedef void (OSSL_DECODER_CLEANUP)(void *construct_data);
|
|
|
|
int OSSL_DECODER_CTX_set_construct(OSSL_DECODER_CTX *ctx,
|
|
OSSL_DECODER_CONSTRUCT *construct);
|
|
int OSSL_DECODER_CTX_set_construct_data(OSSL_DECODER_CTX *ctx,
|
|
void *construct_data);
|
|
int OSSL_DECODER_CTX_set_cleanup(OSSL_DECODER_CTX *ctx,
|
|
OSSL_DECODER_CLEANUP *cleanup);
|
|
OSSL_DECODER_CONSTRUCT *OSSL_DECODER_CTX_get_construct(OSSL_DECODER_CTX *ctx);
|
|
void *OSSL_DECODER_CTX_get_construct_data(OSSL_DECODER_CTX *ctx);
|
|
OSSL_DECODER_CLEANUP *OSSL_DECODER_CTX_get_cleanup(OSSL_DECODER_CTX *ctx);
|
|
|
|
int OSSL_DECODER_export(OSSL_DECODER_INSTANCE *decoder_inst,
|
|
void *reference, size_t reference_sz,
|
|
OSSL_CALLBACK *export_cb, void *export_cbarg);
|
|
|
|
Feature availability macros:
|
|
|
|
=over 4
|
|
|
|
=item OSSL_DECODER_from_fp() is only available when B<OPENSSL_NO_STDIO>
|
|
is undefined.
|
|
|
|
=back
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The B<OSSL_DECODER_CTX> holds data about multiple decoders, as
|
|
needed to figure out what the input data is and to attempt to unpack it into
|
|
one of several possible related results. This also includes chaining
|
|
decoders, so the output from one can become the input for another.
|
|
This allows having generic format decoders such as PEM to DER, as well
|
|
as more specialized decoders like DER to RSA.
|
|
|
|
The chains may be limited by specifying an input type, which is considered a
|
|
starting point.
|
|
This is both considered by OSSL_DECODER_CTX_add_extra(), which will
|
|
stop adding on more decoder implementations when it has already added
|
|
those that take the specified input type, and OSSL_DECODER_from_bio(),
|
|
which will only start the decoding process with the decoder
|
|
implementations that take that input type. For example, if the input type
|
|
is set to C<DER>, a PEM to DER decoder will be ignored.
|
|
|
|
The input type can also be NULL, which means that the caller doesn't know
|
|
what type of input they have. In this case, OSSL_DECODER_from_bio()
|
|
will simply try with one decoder implementation after the other, and
|
|
thereby discover what kind of input the caller gave it.
|
|
|
|
For every decoding done, even an intermediary one, a constructor
|
|
provided by the caller is called to attempt to construct an appropriate type
|
|
/ structure that the caller knows how to handle from the current
|
|
decoding result.
|
|
The constructor is set with OSSL_DECODER_CTX_set_construct().
|
|
|
|
B<OSSL_DECODER_INSTANCE> is an opaque structure that contains
|
|
data about the decoder that was just used, and that may be
|
|
useful for the constructor. There are some functions to extract data
|
|
from this type, described further down.
|
|
|
|
=head2 Functions
|
|
|
|
OSSL_DECODER_from_bio() runs the decoding process for the
|
|
context I<ctx>, with the input coming from the B<BIO> I<in>. Should
|
|
it make a difference, it's recommended to have the BIO set in binary
|
|
mode rather than text mode.
|
|
|
|
OSSL_DECODER_from_fp() does the same thing as OSSL_DECODER_from_bio(),
|
|
except that the input is coming from the B<FILE> I<fp>.
|
|
|
|
OSSL_DECODER_CTX_add_decoder() populates the B<OSSL_DECODER_CTX>
|
|
I<ctx> with a decoder, to be used to attempt to decode some
|
|
encoded input.
|
|
|
|
OSSL_DECODER_CTX_add_extra() finds decoders that generate
|
|
input for already added decoders, and adds them as well. This is
|
|
used to build decoder chains.
|
|
|
|
OSSL_DECODER_CTX_set_input_type() sets the starting input type. This
|
|
limits the decoder chains to be considered, as explained in the general
|
|
description above.
|
|
|
|
OSSL_DECODER_CTX_num_decoders() gets the number of
|
|
decoders currently added to the context I<ctx>.
|
|
|
|
OSSL_DECODER_CTX_set_construct() sets the constructor I<construct>.
|
|
|
|
OSSL_DECODER_CTX_set_construct_data() sets the constructor data that is
|
|
passed to the constructor every time it's called.
|
|
|
|
OSSL_DECODER_CTX_set_cleanup() sets the constructor data I<cleanup>
|
|
function. This is called by L<OSSL_DECODER_CTX_free(3)>.
|
|
|
|
OSSL_DECODER_CTX_get_construct(),
|
|
OSSL_DECODER_CTX_get_construct_data() and
|
|
OSSL_DECODER_CTX_get_cleanup()
|
|
return the values that have been set by
|
|
OSSL_DECODER_CTX_set_construct(),
|
|
OSSL_DECODER_CTX_set_construct_data() and
|
|
OSSL_DECODER_CTX_set_cleanup() respectively.
|
|
|
|
OSSL_DECODER_export() is a fallback function for constructors that
|
|
cannot use the data they get directly for diverse reasons. It takes the same
|
|
decode instance I<decoder_inst> that the constructor got and an object
|
|
I<reference>, unpacks the object which it refers to, and exports it by creating
|
|
an L<OSSL_PARAM(3)> array that it then passes to I<export_cb>, along with
|
|
I<export_arg>.
|
|
|
|
OSSL_DECODER_INSTANCE_decoder() can be used to get the
|
|
decoder method from a decoder instance I<decoder_inst>.
|
|
|
|
OSSL_DECODER_INSTANCE_decoder-ctx() can be used to get the
|
|
decoder method's provider context from a decoder instance
|
|
I<decoder_inst>.
|
|
|
|
=head2 Constructor
|
|
|
|
A B<OSSL_DECODER_CONSTRUCT> gets the following arguments:
|
|
|
|
=over 4
|
|
|
|
=item I<decoder_inst>
|
|
|
|
The B<OSSL_DECODER_INSTANCE> for the decoder from which
|
|
the constructor gets its data.
|
|
|
|
=item I<object>
|
|
|
|
A provider-native object abstraction produced by the decoder. Further
|
|
information on the provider-native object abstraction can be found in
|
|
L<provider-object(7)>.
|
|
|
|
=item I<construct_data>
|
|
|
|
The pointer that was set with OSSL_DECODE_CTX_set_construct_data().
|
|
|
|
=back
|
|
|
|
The constructor is expected to return 1 when the data it receives can
|
|
be constructed, otherwise 0.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
OSSL_DECODER_from_bio() and OSSL_DECODER_from_fp() return 1 on
|
|
success, or 0 on failure.
|
|
|
|
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_get_construct(),
|
|
OSSL_DECODER_CTX_get_construct_data() and
|
|
OSSL_DECODER_CTX_get_cleanup() return the current pointers to the
|
|
cosntructor, the constructor data and the cleanup functions, respectively.
|
|
|
|
OSSL_DECODER_CTX_num_decoders() returns the current
|
|
number of decoders. It returns 0 if I<ctx> is NULL.
|
|
|
|
OSSL_DECODER_export() returns 1 on success, or 0 on failure.
|
|
|
|
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.>
|
|
|
|
=begin comment TODO(3.0) Add examples!
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Text, because pod2xxx doesn't like empty sections
|
|
|
|
=end comment
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<provider(7)>, L<OSSL_DECODER_CTX(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
The functions described here were added in OpenSSL 3.0.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 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
|