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 B<OSSL_DISPATCH> arrays via
48B<OSSL_ALGORITHM> 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 B<OSSL_DISPATCH> element named B<OSSL_get_{name}>.
55For example, the "function" OSSL_FUNC_store_load() has these:
56
57 typedef void *(OSSL_OSSL_FUNC_store_load_fn)(void *provctx,
58                                              const OSSL_PARAM params[]);
59 static ossl_inline OSSL_OSSL_FUNC_store_load_fn
60     OSSL_OSSL_FUNC_store_load(const OSSL_DISPATCH *opf);
61
62B<OSSL_DISPATCH> 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 B<OSSL_PARAM>, 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
108=head2 Load Parameters
109
110=over 4
111
112=item "expect" (B<OSSL_STORE_PARAM_EXPECT>) <integer>
113
114Is a hint of what type of data the OpenSSL library expects to get.
115This is only useful for optimization, as the library will check that the
116object types match the expectation too.
117
118The number that can be given through this parameter is found in
119F<< <openssl/store.h> >>, with the macros having names starting with
120C<OSSL_STORE_INFO_>.  These are further described in
121L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS>.
122
123=item "subject" (B<OSSL_STORE_PARAM_SUBJECT>) <octet string>
124
125Indicates that the caller wants to search for an object with the given
126subject associated.  This can be used to select specific certificates
127by subject.
128
129The contents of the octet string is expected to be in DER form.
130
131=item "issuer" (B<OSSL_STORE_PARAM_ISSUER>) <octet string>
132
133Indicates that the caller wants to search for an object with the given
134issuer associated.  This can be used to select specific certificates
135by issuer.
136
137The contents of the octet string is expected to be in DER form.
138
139=item "serial" (B<OSSL_STORE_PARAM_SERIAL>) <integer>
140
141Indicates that the caller wants to search for an object with the given
142serial number associated.
143
144=item "digest" (B<OSSL_STORE_PARAM_DIGEST>) <UTF8 string>
145
146=item "fingerprint" (B<OSSL_STORE_PARAM_FINGERPRINT>) <octet string>
147
148Indicates that the caller wants to search for an object with the given
149fingerprint, computed with the given digest.
150
151=item "alias" (B<OSSL_STORE_PARAM_ALIAS>) <UTF8 string>
152
153Indicates that the caller wants to search for an object with the given
154alias (some call it a "friendly name").
155
156=item "properties" (B<OSSL_STORE_PARAM_PROPERTIES) <utf8 string>
157
158Property string to use when querying for algorithms such as the B<OSSL_DECODER>
159decoder implementations.
160
161=item "input-type" (B<OSSL_STORE_PARAM_INPUT_TYPE) <utf8 string>
162
163Type of the input format as a hint to use when decoding the objects in the
164store.
165
166=back
167
168Several of these search criteria may be combined.  For example, to
169search for a certificate by issuer+serial, both the "issuer" and the
170"serial" parameters will be given.
171
172=head1 SEE ALSO
173
174L<provider(7)>
175
176=head1 HISTORY
177
178The STORE interface was introduced in OpenSSL 3.0.
179
180=head1 COPYRIGHT
181
182Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
183
184Licensed under the Apache License 2.0 (the "License").  You may not use
185this file except in compliance with the License.  You can obtain a copy
186in the file LICENSE in the source distribution or at
187L<https://www.openssl.org/source/license.html>.
188
189=cut
190