* 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);
*/
#include <openssl/core_names.h>
+#include <openssl/core_object.h>
#include <openssl/evp.h>
#include <openssl/ui.h>
#include <openssl/decoder.h>
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;
* 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;
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);
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>
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
--- /dev/null
+=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
#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
#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"
--- /dev/null
+/*
+ * 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
#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>
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);
}
#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>
}
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);
}
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();
projects / openssl.git / commitdiff