1=pod
2
3=head1 NAME
4
5provider-object - A specification for a provider-native object abstraction
6
7=head1 SYNOPSIS
8
9=for openssl multiple includes
10
11 #include <openssl/core_object.h>
12 #include <openssl/core_names.h>
13
14=head1 DESCRIPTION
15
16The provider-native object abstraction is a set of L<OSSL_PARAM(3)> keys and
17values that can be used to pass provider-native objects to OpenSSL library
18code or between different provider operation implementations with the help
19of OpenSSL library code.
20
21The intention is that certain provider-native operations can pass any sort
22of object that belong with other operations, or with OpenSSL library code.
23
24An object may be passed in the following manners:
25
26=over 4
27
28=item 1.
29
30I<By value>
31
32This means that the I<object data> is passed as an octet string or an UTF8
33string, which can be handled in diverse ways by other provided implementations.
34The encoding of the object depends on the context it's used in; for example,
35L<OSSL_DECODER(3)> allows multiple encodings, depending on existing decoders.
36If central OpenSSL library functionality is to handle the data directly, it
37B<must> be encoded in DER for all object types except for B<OSSL_OBJECT_NAME>
38(see L</Parameter reference> below), where it's assumed to a plain UTF8 string.
39
40=for comment A future extension might be to be able to specify encoding as a
41separate parameter.
42
43=item 2.
44
45I<By reference>
46
47This means that the I<object data> isn't passed directly, an I<object
48reference> is passed instead.  It's an octet string that only the correct
49provider understands correctly.
50
51=back
52
53Objects I<by value> can be used by anything that handles DER encoded
54objects.
55
56Objects I<by reference> need a higher level of cooperation from the
57implementation where the object originated (let's call it X) and its target
58implementation (let's call it Y):
59
60=over 4
61
62=item 1.
63
64I<An object loading function in the target implementation>
65
66The target implementation (Y) may have a function that can take an I<object
67reference>.  This can only be used if the target implementation is from the
68same provider as the one originating the object abstraction in question (X).
69
70The exact target implementation to use is determined from the I<object type>
71and possibly the I<object data type>.
72For example, when the OpenSSL library receives an object abstraction with the
73I<object type> B<OSSL_OBJECT_PKEY>, it will fetch a L<provider-keymgmt(7)>
74using the I<object data type> as its key type (the second argument in
75L<EVP_KEYMGMT_fetch(3)>).
76
77=item 2.
78
79I<An object exporter in the originating implementation>
80
81The originating implementation (X) may have an exporter function.  This
82exporter function can be used to export the object in L<OSSL_PARAM(3)> form,
83that can then be imported by the target implementation's imported function.
84
85This can be used when it's not possible to fetch the target implementation
86(Y) from the same provider.
87
88=back
89
90=head2 Parameter reference
91
92A provider-native object abstraction is an L<OSSL_PARAM(3)> with a selection
93of the following parameters:
94
95=over 4
96
97=item "data" (B<OSSL_OBJECT_PARAM_DATA>) <octet string> or <UTF8 string>
98
99The object data I<passed by value>.
100
101=item "reference" (B<OSSL_OBJECT_PARAM_REFERENCE>) <octet string>
102
103The object data I<passed by reference>.
104
105=item "type" (B<OSSL_OBJECT_PARAM_TYPE>) <integer>
106
107The I<object type>, a number that may have any of the following values (all
108defined in F<< <openssl/core_object.h> >>):
109
110=over 4
111
112=item B<OSSL_OBJECT_NAME>
113
114The object data may only be I<passed by value>, and should be a UTF8
115string.
116
117This is useful for L<provider-storemgmt(7)> when a URI load results in new
118URIs.
119
120=item B<OSSL_OBJECT_PKEY>
121
122The object data is suitable as provider-native B<EVP_PKEY> key data.  The
123object data may be I<passed by value> or I<passed by reference>.
124
125=item B<OSSL_OBJECT_CERT>
126
127The object data is suitable as B<X509> data.  The object data for this
128object type can only be I<passed by value>, and should be an octet string.
129
130Since there's no provider-native X.509 object, OpenSSL libraries that
131receive this object abstraction are expected to convert the data to a
132B<X509> object with d2i_X509().
133
134=item B<OSSL_OBJECT_CRL>
135
136The object data is suitable as B<X509_CRL> data.  The object data can
137only be I<passed by value>, and should be an octet string.
138
139Since there's no provider-native X.509 CRL object, OpenSSL libraries that
140receive this object abstraction are expected to convert the data to a
141B<X509_CRL> object with d2i_X509_CRL().
142
143=back
144
145=item "data-type" (B<OSSL_OBJECT_PARAM_DATA_TYPE>) <UTF8 string>
146
147The specific type of the object content.  Legitimate values depend on the
148object type; if it is B<OSSL_OBJECT_PKEY>, the data type is expected to be a
149key type suitable for fetching a L<provider-keymgmt(7)> that can handle the
150data.
151
152=for comment For objects with an unknown object type (OSSL_OBJECT_PARAM_TYPE
153is either missing or has the value OSSL_OBJECT_UNKNOWN), libcrypto
154interprets the object data type as the input type for a decoder.
155
156=item "data-structure" (B<OSSL_OBJECT_PARAM_DATA_STRUCTURE>) <UTF8 string>
157
158The outermost structure of the object content.  Legitimate values depend on
159the object type.
160
161=item "desc" (B<OSSL_OBJECT_PARAM_DESC>) <UTF8 string>
162
163A human readable text that describes extra details on the object.
164
165=back
166
167When a provider-native object abtraction is used, it I<must> contain object
168data in at least one form (object data I<passed by value>, i.e. the "data"
169item, or object data I<passed by reference>, i.e. the "reference" item).
170Both may be present at once, in which case the OpenSSL library code that
171receives this will use the most optimal variant.
172
173For objects with the object type B<OSSL_OBJECT_NAME>, that object type
174I<must> be given.
175
176=head1 SEE ALSO
177
178L<provider(7)>, L<OSSL_DECODER(3)>
179
180=head1 HISTORY
181
182The concept of providers and everything surrounding them was
183introduced in OpenSSL 3.0.
184
185=head1 COPYRIGHT
186
187Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
188
189Licensed under the Apache License 2.0 (the "License").  You may not use
190this file except in compliance with the License.  You can obtain a copy
191in the file LICENSE in the source distribution or at
192L<https://www.openssl.org/source/license.html>.
193
194=cut
195