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