1PROVIDER-OBJECT(7ossl) OpenSSL PROVIDER-OBJECT(7ossl)
2
6 provider-object - A specification for a provider-native object
7 abstraction
8
10 #include <openssl/core_object.h>
11 #include <openssl/core_names.h>
12
14 The provider-native object abstraction is a set of OSSL_PARAM(3) keys
15 and values that can be used to pass provider-native objects to OpenSSL
16 library code or between different provider operation implementations
17 with the help of OpenSSL library code.
18 The intention is that certain provider-native operations can pass any
20 sort of object that belong with other operations, or with OpenSSL
21 library code.
22 An object may be passed in the following manners:
24 1. By value
26 This means that the object data is passed as an octet string or an
28 UTF8 string, which can be handled in diverse ways by other provided
29 implementations. The encoding of the object depends on the context
30 it's used in; for example, OSSL_DECODER(3) allows multiple
31 encodings, depending on existing decoders. If central OpenSSL
32 library functionality is to handle the data directly, it must be
33 encoded in DER for all object types except for OSSL_OBJECT_NAME
34 (see "Parameter reference" below), where it's assumed to a plain
35 UTF8 string.
36 2. By reference
38 This means that the object data isn't passed directly, an object
40 reference is passed instead. It's an octet string that only the
41 correct provider understands correctly.
42 Objects by value can be used by anything that handles DER encoded
44 objects.
45 Objects by reference need a higher level of cooperation from the
47 implementation where the object originated (let's call it X) and its
48 target implementation (let's call it Y):
49 1. An object loading function in the target implementation
51 The target implementation (Y) may have a function that can take an
53 object reference. This can only be used if the target
54 implementation is from the same provider as the one originating the
55 object abstraction in question (X).
56 The exact target implementation to use is determined from the
58 object type and possibly the object data type. For example, when
59 the OpenSSL library receives an object abstraction with the object
60 type OSSL_OBJECT_PKEY, it will fetch a provider-keymgmt(7) using
61 the object data type as its key type (the second argument in
62 EVP_KEYMGMT_fetch(3)).
63 2. An object exporter in the originating implementation
65 The originating implementation (X) may have an exporter function.
67 This exporter function can be used to export the object in
68 OSSL_PARAM(3) form, that can then be imported by the target
69 implementation's imported function.
70 This can be used when it's not possible to fetch the target
72 implementation (Y) from the same provider.
73 Parameter reference
75 A provider-native object abstraction is an OSSL_PARAM(3) with a
76 selection of the following parameters:
77 "data" (OSSL_OBJECT_PARAM_DATA) <octet string> or <UTF8 string>
79 The object data passed by value.
80 "reference" (OSSL_OBJECT_PARAM_REFERENCE) <octet string>
82 The object data passed by reference.
83 "type" (OSSL_OBJECT_PARAM_TYPE) <integer>
85 The object type, a number that may have any of the following values
86 (all defined in <openssl/core_object.h>):
87 OSSL_OBJECT_NAME
89 The object data may only be passed by value, and should be a
90 UTF8 string.
91 This is useful for provider-storemgmt(7) when a URI load
93 results in new URIs.
94 OSSL_OBJECT_PKEY
96 The object data is suitable as provider-native EVP_PKEY key
97 data. The object data may be passed by value or passed by
98 reference.
99 OSSL_OBJECT_CERT
101 The object data is suitable as X509 data. The object data for
102 this object type can only be passed by value, and should be an
103 octet string.
104 Since there's no provider-native X.509 object, OpenSSL
106 libraries that receive this object abstraction are expected to
107 convert the data to a X509 object with d2i_X509().
108 OSSL_OBJECT_CRL
110 The object data is suitable as X509_CRL data. The object data
111 can only be passed by value, and should be an octet string.
112 Since there's no provider-native X.509 CRL object, OpenSSL
114 libraries that receive this object abstraction are expected to
115 convert the data to a X509_CRL object with d2i_X509_CRL().
116 "data-type" (OSSL_OBJECT_PARAM_DATA_TYPE) <UTF8 string>
118 The specific type of the object content. Legitimate values depend
119 on the object type; if it is OSSL_OBJECT_PKEY, the data type is
120 expected to be a key type suitable for fetching a
121 provider-keymgmt(7) that can handle the data.
122 "data-structure" (OSSL_OBJECT_PARAM_DATA_STRUCTURE) <UTF8 string>
124 The outermost structure of the object content. Legitimate values
125 depend on the object type.
126 "desc" (OSSL_OBJECT_PARAM_DESC) <UTF8 string>
128 A human readable text that describes extra details on the object.
129 When a provider-native object abtraction is used, it must contain
131 object data in at least one form (object data passed by value, i.e. the
132 "data" item, or object data passed by reference, i.e. the "reference"
133 item). Both may be present at once, in which case the OpenSSL library
134 code that receives this will use the most optimal variant.
135 For objects with the object type OSSL_OBJECT_NAME, that object type
137 must be given.
138
140 provider(7), OSSL_DECODER(3)
141
143 The concept of providers and everything surrounding them was introduced
144 in OpenSSL 3.0.
145
147 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
148 Licensed under the Apache License 2.0 (the "License"). You may not use
150 this file except in compliance with the License. You can obtain a copy
151 in the file LICENSE in the source distribution or at
152 <https://www.openssl.org/source/license.html>.
1533.0.9 2023-07-27 PROVIDER-OBJECT(7ossl)