mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2024-11-21 01:15:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

CORE: Define provider-native abstract objects

Browse Source 
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)
This commit is contained in:
Richard Levitte 2020-07-22 15:34:25 +02:00
parent bc8c3e1cd8
commit 14c8a3d118
9 changed files with 275 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
crypto/encode_decode/decoder_lib.c
View File

@ -407,7 +407,7 @@ static int decoder_process(const OSSL_PARAM params[], void *arg)
* If this data isn't present, decoding has failed.
*/
p = OSSL_PARAM_locate_const(params, OSSL_DECODER_PARAM_DATA);
p = OSSL_PARAM_locate_const(params, OSSL_OBJECT_PARAM_DATA);
if (p == NULL || p->data_type != OSSL_PARAM_OCTET_STRING)
goto end;
new_data.bio = BIO_new_mem_buf(p->data, (int)p->data_size);

5
crypto/encode_decode/decoder_pkey.c
View File

@ -8,6 +8,7 @@
*/
#include <openssl/core_names.h>
#include <openssl/core_object.h>
#include <openssl/evp.h>
#include <openssl/ui.h>
#include <openssl/decoder.h>
@ -128,7 +129,7 @@ static int decoder_construct_EVP_PKEY(OSSL_DECODER_INSTANCE *decoder_inst,
size_t object_ref_sz = 0;
const OSSL_PARAM *p;
p = OSSL_PARAM_locate_const(params, OSSL_DECODER_PARAM_DATA_TYPE);
p = OSSL_PARAM_locate_const(params, OSSL_OBJECT_PARAM_DATA_TYPE);
if (p != NULL) {
char *object_type = NULL;
@ -143,7 +144,7 @@ static int decoder_construct_EVP_PKEY(OSSL_DECODER_INSTANCE *decoder_inst,
* reference for the moment. This enforces that the key data itself
* remains with the provider.
*/
p = OSSL_PARAM_locate_const(params, OSSL_DECODER_PARAM_REFERENCE);
p = OSSL_PARAM_locate_const(params, OSSL_OBJECT_PARAM_REFERENCE);
if (p == NULL || p->data_type != OSSL_PARAM_OCTET_STRING)
return 0;
object_ref = p->data;

47
doc/man3/OSSL_DECODER_from_bio.pod
View File

@ -41,7 +41,7 @@ OSSL_DECODER_INSTANCE_decoder_ctx
void *OSSL_DECODER_INSTANCE_decoder_ctx(OSSL_DECODER_INSTANCE *decoder_inst);
typedef int (OSSL_DECODER_CONSTRUCT)(OSSL_DECODER_INSTANCE *decoder_inst,
const OSSL_PARAM *params,
const OSSL_PARAM *object,
void *construct_data);
typedef void (OSSL_DECODER_CLEANUP)(void *construct_data);
@ -168,9 +168,11 @@ A B<OSSL_DECODER_CONSTRUCT> gets the following arguments:
The B<OSSL_DECODER_INSTANCE> for the decoder from which
the constructor gets its data.
=item I<params>
=item I<object>
The data produced by the decoder, further described below.
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>
@ -181,45 +183,6 @@ The pointer that was set with OSSL_DECODE_CTX_set_construct_data().
The constructor is expected to return 1 when the data it receives can
be constructed, otherwise 0.
The globally known parameters that the constructor can get in I<params>
are:
=over 4
=item "data-type" (B<OSSL_DECODER_PARAM_DATA_TYPE>) <UTF8 string>
This is a detected content type that some decoders may provide.
For example, PEM input sometimes has a type specified in its header,
and some decoders may add that information as this parameter.
This is an optional parameter, but may be useful for extra checks in
the constructor.
=item "data" (B<OSSL_DECODER_PARAM_DATA>) <octet string>
The decoded data itself, as an octet string. This is produced by
decoders when it's possible to pass an object in this form. Most
often, this is simply meant to be passed to the next decoder in a
chain, but could be considered final data as well, at the discretion
of the constructor.
=item "reference" (B<OSSL_DECODER_PARAM_DATA>) <octet string>
The decoded data itself, as a reference to an object. The
reference itself is an octet string, and can be passed to other
operations and functions within the same provider as the one that
provides I<decoder>.
=back
At least one of "data" or "reference" must be present, and it's
possible that both can be. A constructor should choose to use the
"reference" parameter if possible, otherwise it should use the "data"
parameter.
If it's not possible to use the "reference" parameter, but that's
still what a constructor wants to do, it is possible to use
OSSL_DECODER_export() as a fallback.
=head1 RETURN VALUES
OSSL_DECODER_from_bio() and OSSL_DECODER_from_fp() return 1 on

189
doc/man7/provider-object.pod Normal file
View File

@ -0,0 +1,189 @@
=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

20
include/openssl/core_names.h
View File

@ -30,6 +30,23 @@ extern "C" {
#define OSSL_PROV_PARAM_SELF_TEST_TYPE "st-type" /* utf8_string */
#define OSSL_PROV_PARAM_SELF_TEST_DESC "st-desc" /* utf8_string */
/*-
* Provider-native object abstractions
*
* These are used when a provider wants to pass object data or an object
* reference back to libcrypto. This is only useful for provider functions
* that take a callback to which an OSSL_PARAM array with these parameters
* can be passed.
*
* This set of parameter names is explained in detail in provider-object(7)
* (doc/man7/provider-object.pod)
*/
#define OSSL_OBJECT_PARAM_TYPE "type" /* INTEGER */
#define OSSL_OBJECT_PARAM_DATA_TYPE "data-type" /* UTF8_STRING */
#define OSSL_OBJECT_PARAM_REFERENCE "reference" /* OCTET_STRING */
#define OSSL_OBJECT_PARAM_DATA "data" /* OCTET_STRING or UTF8_STRING */
#define OSSL_OBJECT_PARAM_DESC "desc" /* UTF8_STRING */
/*
* Algorithm parameters
* If "engine" or "properties" are specified, they should always be paired
@ -433,9 +450,6 @@ extern "C" {
#define OSSL_DECODER_PARAM_PROPERTIES OSSL_ALG_PARAM_PROPERTIES
#define OSSL_DECODER_PARAM_PASS "passphrase"
#define OSSL_DECODER_PARAM_INPUT_TYPE "input-type"
#define OSSL_DECODER_PARAM_DATA_TYPE "data-type"
#define OSSL_DECODER_PARAM_DATA "data"
#define OSSL_DECODER_PARAM_REFERENCE "reference"
/* Passphrase callback parameters */
#define OSSL_PASSPHRASE_PARAM_INFO "info"

40
include/openssl/core_object.h Normal file
View File

@ -0,0 +1,40 @@
/*
* 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
* https://www.openssl.org/source/license.html
*/
#ifndef OPENSSL_CORE_OBJECT_H
# define OPENSSL_CORE_OBJECT_H
# ifdef __cplusplus
extern "C" {
# endif
/*-
* Known object types
*
* These numbers are used as values for the OSSL_PARAM parameter
* OSSL_OBJECT_PARAM_TYPE.
*
* For most of these types, there's a corresponding libcrypto object type.
* The corresponding type is indicated with a comment after the number.
*/
# define OSSL_OBJECT_UNKNOWN 0
# define OSSL_OBJECT_NAME 1 /* char * */
# define OSSL_OBJECT_PKEY 2 /* EVP_PKEY * */
# define OSSL_OBJECT_CERT 3 /* X509 * */
# define OSSL_OBJECT_CRL 4 /* X509_CRL * */
/*
* The rest of the associated OSSL_PARAM elements is described in core_names.h
*/
# ifdef __cplusplus
}
# endif
#endif

14
providers/implementations/encode_decode/decode_der2key.c
View File

@ -15,6 +15,7 @@
#include <openssl/core_dispatch.h>
#include <openssl/core_names.h>
#include <openssl/core_object.h>
#include <openssl/crypto.h>
#include <openssl/params.h>
#include <openssl/x509.h>
@ -157,16 +158,19 @@ static int der2key_decode(void *vctx, OSSL_CORE_BIO *cin,
OPENSSL_free(der);
if (key != NULL) {
OSSL_PARAM params[3];
OSSL_PARAM params[4];
int object_type = OSSL_OBJECT_PKEY;
params[0] =
OSSL_PARAM_construct_utf8_string(OSSL_DECODER_PARAM_DATA_TYPE,
OSSL_PARAM_construct_int(OSSL_OBJECT_PARAM_TYPE, &object_type);
params[1] =
OSSL_PARAM_construct_utf8_string(OSSL_OBJECT_PARAM_DATA_TYPE,
(char *)ctx->desc->name, 0);
/* The address of the key becomes the octet string */
params[1] =
OSSL_PARAM_construct_octet_string(OSSL_DECODER_PARAM_REFERENCE,
params[2] =
OSSL_PARAM_construct_octet_string(OSSL_OBJECT_PARAM_REFERENCE,
&key, sizeof(key));
params[2] = OSSL_PARAM_construct_end();
params[3] = OSSL_PARAM_construct_end();
ok = data_cb(params, data_cbarg);
}

14
providers/implementations/encode_decode/decode_ms2key.c
View File

@ -15,6 +15,7 @@
#include <openssl/core_dispatch.h>
#include <openssl/core_names.h>
#include <openssl/core_object.h>
#include <openssl/crypto.h>
#include <openssl/params.h>
#include <openssl/x509.h>
@ -131,16 +132,19 @@ static int ms2key_post(struct ms2key_ctx_st *ctx, EVP_PKEY *pkey,
}
if (key != NULL) {
OSSL_PARAM params[3];
OSSL_PARAM params[4];
int object_type = OSSL_OBJECT_PKEY;
params[0] =
OSSL_PARAM_construct_utf8_string(OSSL_DECODER_PARAM_DATA_TYPE,
OSSL_PARAM_construct_int(OSSL_OBJECT_PARAM_TYPE, &object_type);
params[1] =
OSSL_PARAM_construct_utf8_string(OSSL_OBJECT_PARAM_DATA_TYPE,
(char *)ctx->desc->name, 0);
/* The address of the key becomes the octet string */
params[1] =
OSSL_PARAM_construct_octet_string(OSSL_DECODER_PARAM_REFERENCE,
params[2] =
OSSL_PARAM_construct_octet_string(OSSL_OBJECT_PARAM_REFERENCE,
&key, sizeof(key));
params[2] = OSSL_PARAM_construct_end();
params[3] = OSSL_PARAM_construct_end();
ok = data_cb(params, data_cbarg);
}

4
providers/implementations/encode_decode/decode_pem2der.c
View File

@ -130,10 +130,10 @@ static int pem2der_decode(void *vctx, OSSL_CORE_BIO *cin,
OSSL_PARAM params[3];
params[0] =
OSSL_PARAM_construct_utf8_string(OSSL_DECODER_PARAM_DATA_TYPE,
OSSL_PARAM_construct_utf8_string(OSSL_OBJECT_PARAM_DATA_TYPE,
pem_name, 0);
params[1] =
OSSL_PARAM_construct_octet_string(OSSL_DECODER_PARAM_DATA,
OSSL_PARAM_construct_octet_string(OSSL_OBJECT_PARAM_DATA,
der, der_len);
params[2] = OSSL_PARAM_construct_end();