mirror of
https://github.com/openssl/openssl.git
synced 2024-12-03 05:41:46 +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)
190 lines
5.9 KiB
Plaintext
190 lines
5.9 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
provider-object - A specification for a provider-native object abstraction
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
=for openssl multiple includes
|
|
|
|
#include <openssl/core_object.h>
|
|
#include <openssl/core_names.h>
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The provider-native object abstraction is a set of L<OSSL_PARAM(3)> keys and
|
|
values that can be used to pass provider-native objects to OpenSSL library
|
|
code or between different provider operation implementations with the help
|
|
of OpenSSL library code.
|
|
|
|
The intention is that certain provider-native operations can pass any sort
|
|
of object that belong with other operations, or with OpenSSL library code.
|
|
|
|
An object may be passed in the following manners:
|
|
|
|
=over 4
|
|
|
|
=item 1.
|
|
|
|
I<By value>
|
|
|
|
This means that the I<object data> is passed as an octet string or an UTF8
|
|
string, which can be handled in diverse ways by other provided implementations.
|
|
The encoding of the object depends on the context it's used in; for example,
|
|
L<OSSL_DECODER(3)> allows multiple encodings, depending on existing decoders.
|
|
If central OpenSSL library functionality is to handle the data directly, it
|
|
B<must> be encoded in DER for all object types except for B<OSSL_OBJECT_NAME>
|
|
(see L</Parameter reference> below), where it's assumed to a plain UTF8 string.
|
|
|
|
=for comment A future extension might be to be able to specify encoding as a
|
|
separate parameter.
|
|
|
|
=item 2.
|
|
|
|
I<By reference>
|
|
|
|
This means that the I<object data> isn't passed directly, an I<object
|
|
reference> is passed instead. It's an octet string that only the correct
|
|
provider understands correctly.
|
|
|
|
=back
|
|
|
|
Objects I<by value> can be used by anything that handles DER encoded
|
|
objects.
|
|
|
|
Objects I<by reference> need a higher level of cooperation from the
|
|
implementation where the object originated (let's call it X) and its target
|
|
implementation (let's call it Y):
|
|
|
|
=over 4
|
|
|
|
=item 1.
|
|
|
|
I<An object loading function in the target implementation>
|
|
|
|
The target implementation (Y) may have a function that can take an I<object
|
|
reference>. This can only be used if the target implementation is from the
|
|
same provider as the one originating the object abstraction in question (X).
|
|
|
|
The exact target implementation to use is determined from the I<object type>
|
|
and possibly the I<object data type>.
|
|
For example, when the OpenSSL library receives an object abstraction with the
|
|
I<object type> B<OSSL_OBJECT_PKEY>, it will fetch a L<provider-keymgmt(7)>
|
|
using the I<object data type> as its key type (the second argument in
|
|
L<EVP_KEYMGMT_fetch(3)>).
|
|
|
|
=item 2.
|
|
|
|
I<An object exporter in the originating implementation>
|
|
|
|
The originating implementation (X) may have an exporter function. This
|
|
exporter function can be used to export the object in L<OSSL_PARAM(3)> form,
|
|
that can then be imported by the target implementation's imported function.
|
|
|
|
This can be used when it's not possible to fetch the target implementation
|
|
(Y) from the same provider.
|
|
|
|
=back
|
|
|
|
=head2 Parameter reference
|
|
|
|
A provider-native object abstraction is an L<OSSL_PARAM(3)> with a selection
|
|
of the following parameters:
|
|
|
|
=over 4
|
|
|
|
=item "data" (B<OSSL_OBJECT_PARAM_DATA>) <octet string> or <utf8 string>
|
|
|
|
The object data I<passed by value>.
|
|
|
|
=item "reference" (B<OSSL_OBJECT_PARAM_REFERENCE>) <octet string>
|
|
|
|
The object data I<passed by reference>.
|
|
|
|
=item "type" (B<OSSL_OBJECT_PARAM_TYPE>) <integer>
|
|
|
|
The I<object type>, a number that may have any of the following values (all
|
|
defined in F<< <openssl/core_object.h> >>):
|
|
|
|
=over 4
|
|
|
|
=item B<OSSL_OBJECT_NAME>
|
|
|
|
The object data may only be I<passed by value>, and should be a UTF8
|
|
string.
|
|
|
|
This is useful for L<provider-storemgmt(7)> when a URI load results in new
|
|
URIs.
|
|
|
|
=item B<OSSL_OBJECT_PKEY>
|
|
|
|
The object data is suitable as provider-native B<EVP_PKEY> key data. The
|
|
object data may be I<passed by value> or I<passed by reference>.
|
|
|
|
=item B<OSSL_OBJECT_CERT>
|
|
|
|
The object data is suitable as B<X509> data. The object data for this
|
|
object type can only be I<passed by value>, and should be an octet string.
|
|
|
|
Since there's no provider-native X.509 object, OpenSSL libraries that
|
|
receive this object abstraction are expected to convert the data to a
|
|
B<X509> object with d2i_X509().
|
|
|
|
=item B<OSSL_OBJECT_CRL>
|
|
|
|
The object data is suitable as B<X509_CRL> data. The object data can
|
|
only be I<passed by value>, and should be an octet string.
|
|
|
|
Since there's no provider-native X.509 CRL object, OpenSSL libraries that
|
|
receive this object abstraction are expected to convert the data to a
|
|
B<X509_CRL> object with d2i_X509_CRL().
|
|
|
|
=back
|
|
|
|
=item "data-type" (B<OSSL_OBJECT_PARAM_DATA_TYPE>) <utf8 string>
|
|
|
|
The specific type of the object content. Legitimate values depend on the
|
|
object type; if it is B<OSSL_OBJECT_PKEY>, the data type is expected to be a
|
|
key type suitable for fetching a L<provider-keymgmt(7)> that can handle the
|
|
data.
|
|
|
|
=for comment For objects with an unknown object type (OSSL_OBJECT_PARAM_TYPE
|
|
is either missing or has the value OSSL_OBJECT_UNKNOWN), libcrypto
|
|
interprets the object data type as the input type for a decoder.
|
|
|
|
=item "desc" (B<OSSL_OBJECT_PARAM_DESC>) <utf8 string>
|
|
|
|
A human readable text that describes extra details on the object.
|
|
|
|
=back
|
|
|
|
When a provider-native object abtraction is used, it I<must> contain object
|
|
data in at least one form (object data I<passed by value>, i.e. the "data"
|
|
item, or object data I<passed by reference>, i.e. the "reference" item).
|
|
Both may be present at once, in which case the OpenSSL library code that
|
|
receives this will use the most optimal variant.
|
|
|
|
For objects with the object type B<OSSL_OBJECT_NAME>, that object type
|
|
I<must> be given.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<provider(7)>, L<OSSL_DECODER(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
The concept of providers and everything surrounding them was
|
|
introduced 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
|