1=pod
2
3=head1 NAME
4
5provider-storemgmt - The OSSL_STORE library E<lt>-E<gt> provider functions
6
7=head1 SYNOPSIS
8
9 #include <openssl/core_dispatch.h>
10
11 /*
12  * None of these are actual functions, but are displayed like this for
13  * the function signatures for functions that are offered as function
14  * pointers in OSSL_DISPATCH arrays.
15  */
16
17 void *OSSL_FUNC_store_open(void *provctx, const char *uri);
18 void *OSSL_FUNC_store_attach(void *provctx, OSSL_CORE_BIO *bio);
19 const OSSL_PARAM *store_settable_ctx_params(void *provctx);
20 int OSSL_FUNC_store_set_ctx_params(void *loaderctx, const OSSL_PARAM[]);
21 int OSSL_FUNC_store_load(void *loaderctx,
22                          OSSL_CALLBACK *object_cb, void *object_cbarg,
23                          OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg);
24 int OSSL_FUNC_store_eof(void *loaderctx);
25 int OSSL_FUNC_store_close(void *loaderctx);
26
27 int OSSL_FUNC_store_export_object
28     (void *loaderctx, const void *objref, size_t objref_sz,
29      OSSL_CALLBACK *export_cb, void *export_cbarg);
30
31=head1 DESCRIPTION
32
33The STORE operation is the provider side of the L<ossl_store(7)> API.
34
35The primary responsibility of the STORE operation is to load all sorts
36of objects from a container indicated by URI.  These objects are given
37to the OpenSSL library in provider-native object abstraction form (see
38L<provider-object(7)>).  The OpenSSL library is then responsible for
39passing on that abstraction to suitable provided functions.
40
41Examples of functions that the OpenSSL library can pass the abstraction to
42include OSSL_FUNC_keymgmt_load() (L<provider-keymgmt(7)>),
43OSSL_FUNC_store_export_object() (which exports the object in parameterized
44form).
45
46All "functions" mentioned here are passed as function pointers between
47F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via
48L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's
49provider_query_operation() function
50(see L<provider-base(7)/Provider Functions>).
51
52All these "functions" have a corresponding function type definition named
53B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the function pointer
54from a L<OSSL_DISPATCH(3)> element named B<OSSL_get_{name}>.
55For example, the "function" OSSL_FUNC_store_attach() has these:
56
57 typedef void *(OSSL_FUNC_store_attach_fn)(void *provctx,
58                                           OSSL_CORE_BIO * bio);
59 static ossl_inline OSSL_FUNC_store_attach_fn
60     OSSL_FUNC_store_attach(const OSSL_DISPATCH *opf);
61
62L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as macros
63in L<openssl-core_dispatch.h(7)>, as follows:
64
65 OSSL_FUNC_store_open                 OSSL_FUNC_STORE_OPEN
66 OSSL_FUNC_store_attach               OSSL_FUNC_STORE_ATTACH
67 OSSL_FUNC_store_settable_ctx_params  OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS
68 OSSL_FUNC_store_set_ctx_params       OSSL_FUNC_STORE_SET_CTX_PARAMS
69 OSSL_FUNC_store_load                 OSSL_FUNC_STORE_LOAD
70 OSSL_FUNC_store_eof                  OSSL_FUNC_STORE_EOF
71 OSSL_FUNC_store_close                OSSL_FUNC_STORE_CLOSE
72 OSSL_FUNC_store_export_object        OSSL_FUNC_STORE_EXPORT_OBJECT
73
74=head2 Functions
75
76OSSL_FUNC_store_open() should create a provider side context with data based
77on the input I<uri>.  The implementation is entirely responsible for the
78interpretation of the URI.
79
80OSSL_FUNC_store_attach() should create a provider side context with the core
81B<BIO> I<bio> attached.  This is an alternative to using a URI to find storage,
82supporting L<OSSL_STORE_attach(3)>.
83
84OSSL_FUNC_store_settable_ctx_params() should return a constant array of
85descriptor L<OSSL_PARAM(3)>, for parameters that OSSL_FUNC_store_set_ctx_params()
86can handle.
87
88OSSL_FUNC_store_set_ctx_params() should set additional parameters, such as what
89kind of data to expect, search criteria, and so on.  More on those below, in
90L</Load Parameters>.  Whether unrecognised parameters are an error or simply
91ignored is at the implementation's discretion.
92Passing NULL for I<params> should return true.
93
94OSSL_FUNC_store_load() loads the next object from the URI opened by
95OSSL_FUNC_store_open(), creates an object abstraction for it (see
96L<provider-object(7)>), and calls I<object_cb> with it as well as
97I<object_cbarg>.  I<object_cb> will then interpret the object abstraction
98and do what it can to wrap it or decode it into an OpenSSL structure.  In
99case a passphrase needs to be prompted to unlock an object, I<pw_cb> should
100be called.
101
102OSSL_FUNC_store_eof() indicates if the end of the set of objects from the
103URI has been reached.  When that happens, there's no point trying to do any
104further loading.
105
106OSSL_FUNC_store_close() frees the provider side context I<ctx>.
107
108When a provider-native object is created by a store manager it would be unsuitable
109for direct use with a foreign provider. The export function allows for
110exporting the object to that foreign provider if the foreign provider
111supports the type of the object and provides an import function.
112
113OSSL_FUNC_store_export_object() should export the object of size I<objref_sz>
114referenced by I<objref> as an L<OSSL_PARAM(3)> array and pass that to the
115I<export_cb> as well as the given I<export_cbarg>.
116
117=head2 Load Parameters
118
119=over 4
120
121=item "expect" (B<OSSL_STORE_PARAM_EXPECT>) <integer>
122
123Is a hint of what type of data the OpenSSL library expects to get.
124This is only useful for optimization, as the library will check that the
125object types match the expectation too.
126
127The number that can be given through this parameter is found in
128F<< <openssl/store.h> >>, with the macros having names starting with
129C<OSSL_STORE_INFO_>.  These are further described in
130L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS>.
131
132=item "subject" (B<OSSL_STORE_PARAM_SUBJECT>) <octet string>
133
134Indicates that the caller wants to search for an object with the given
135subject associated.  This can be used to select specific certificates
136by subject.
137
138The contents of the octet string is expected to be in DER form.
139
140=item "issuer" (B<OSSL_STORE_PARAM_ISSUER>) <octet string>
141
142Indicates that the caller wants to search for an object with the given
143issuer associated.  This can be used to select specific certificates
144by issuer.
145
146The contents of the octet string is expected to be in DER form.
147
148=item "serial" (B<OSSL_STORE_PARAM_SERIAL>) <integer>
149
150Indicates that the caller wants to search for an object with the given
151serial number associated.
152
153=item "digest" (B<OSSL_STORE_PARAM_DIGEST>) <UTF8 string>
154
155=item "fingerprint" (B<OSSL_STORE_PARAM_FINGERPRINT>) <octet string>
156
157Indicates that the caller wants to search for an object with the given
158fingerprint, computed with the given digest.
159
160=item "alias" (B<OSSL_STORE_PARAM_ALIAS>) <UTF8 string>
161
162Indicates that the caller wants to search for an object with the given
163alias (some call it a "friendly name").
164
165=item "properties" (B<OSSL_STORE_PARAM_PROPERTIES) <utf8 string>
166
167Property string to use when querying for algorithms such as the B<OSSL_DECODER>
168decoder implementations.
169
170=item "input-type" (B<OSSL_STORE_PARAM_INPUT_TYPE) <utf8 string>
171
172Type of the input format as a hint to use when decoding the objects in the
173store.
174
175=back
176
177Several of these search criteria may be combined.  For example, to
178search for a certificate by issuer+serial, both the "issuer" and the
179"serial" parameters will be given.
180
181=head1 SEE ALSO
182
183L<provider(7)>
184
185=head1 HISTORY
186
187The STORE interface was introduced in OpenSSL 3.0.
188
189=head1 COPYRIGHT
190
191Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
192
193Licensed under the Apache License 2.0 (the "License").  You may not use
194this file except in compliance with the License.  You can obtain a copy
195in the file LICENSE in the source distribution or at
196L<https://www.openssl.org/source/license.html>.
197
198=cut
199