1PROVIDER-STOREMGMT(7ossl) OpenSSL PROVIDER-STOREMGMT(7ossl)
2
6 provider-storemgmt - The OSSL_STORE library <-> provider functions
7
9 #include <openssl/core_dispatch.h>
10 /*
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 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 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
32 The STORE operation is the provider side of the ossl_store(7) API.
33 The primary responsibility of the STORE operation is to load all sorts
35 of objects from a container indicated by URI. These objects are given
36 to the OpenSSL library in provider-native object abstraction form (see
37 provider-object(7)). The OpenSSL library is then responsible for
38 passing on that abstraction to suitable provided functions.
39 Examples of functions that the OpenSSL library can pass the abstraction
41 to include OSSL_FUNC_keymgmt_load() (provider-keymgmt(7)),
42 OSSL_FUNC_store_export_object() (which exports the object in
43 parameterized form).
44 All "functions" mentioned here are passed as function pointers between
46 libcrypto and the provider in OSSL_DISPATCH(3) arrays via
47 OSSL_ALGORITHM(3) arrays that are returned by the provider's
48 provider_query_operation() function (see "Provider Functions" in
49 provider-base(7)).
50 All these "functions" have a corresponding function type definition
52 named OSSL_FUNC_{name}_fn, and a helper function to retrieve the
53 function pointer from a OSSL_DISPATCH(3) element named OSSL_get_{name}.
54 For example, the "function" OSSL_FUNC_store_attach() has these:
55 typedef void *(OSSL_FUNC_store_attach_fn)(void *provctx,
57 OSSL_CORE_BIO * bio);
58 static ossl_inline OSSL_FUNC_store_attach_fn
59 OSSL_FUNC_store_attach(const OSSL_DISPATCH *opf);
60 OSSL_DISPATCH(3) arrays are indexed by numbers that are provided as
62 macros in openssl-core_dispatch.h(7), as follows:
63 OSSL_FUNC_store_open OSSL_FUNC_STORE_OPEN
65 OSSL_FUNC_store_attach OSSL_FUNC_STORE_ATTACH
66 OSSL_FUNC_store_settable_ctx_params OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS
67 OSSL_FUNC_store_set_ctx_params OSSL_FUNC_STORE_SET_CTX_PARAMS
68 OSSL_FUNC_store_load OSSL_FUNC_STORE_LOAD
69 OSSL_FUNC_store_eof OSSL_FUNC_STORE_EOF
70 OSSL_FUNC_store_close OSSL_FUNC_STORE_CLOSE
71 OSSL_FUNC_store_export_object OSSL_FUNC_STORE_EXPORT_OBJECT
72 Functions
74 OSSL_FUNC_store_open() should create a provider side context with data
75 based on the input uri. The implementation is entirely responsible for
76 the interpretation of the URI.
77 OSSL_FUNC_store_attach() should create a provider side context with the
79 core BIO bio attached. This is an alternative to using a URI to find
80 storage, supporting OSSL_STORE_attach(3).
81 OSSL_FUNC_store_settable_ctx_params() should return a constant array of
83 descriptor OSSL_PARAM(3), for parameters that
84 OSSL_FUNC_store_set_ctx_params() can handle.
85 OSSL_FUNC_store_set_ctx_params() should set additional parameters, such
87 as what kind of data to expect, search criteria, and so on. More on
88 those below, in "Load Parameters". Whether unrecognised parameters are
89 an error or simply ignored is at the implementation's discretion.
90 Passing NULL for params should return true.
91 OSSL_FUNC_store_load() loads the next object from the URI opened by
93 OSSL_FUNC_store_open(), creates an object abstraction for it (see
94 provider-object(7)), and calls object_cb with it as well as
95 object_cbarg. object_cb will then interpret the object abstraction and
96 do what it can to wrap it or decode it into an OpenSSL structure. In
97 case a passphrase needs to be prompted to unlock an object, pw_cb
98 should be called.
99 OSSL_FUNC_store_eof() indicates if the end of the set of objects from
101 the URI has been reached. When that happens, there's no point trying
102 to do any further loading.
103 OSSL_FUNC_store_close() frees the provider side context ctx.
105 When a provider-native object is created by a store manager it would be
107 unsuitable for direct use with a foreign provider. The export function
108 allows for exporting the object to that foreign provider if the foreign
109 provider supports the type of the object and provides an import
110 function.
111 OSSL_FUNC_store_export_object() should export the object of size
113 objref_sz referenced by objref as an OSSL_PARAM(3) array and pass that
114 to the export_cb as well as the given export_cbarg.
115 Load Parameters
117 "expect" (OSSL_STORE_PARAM_EXPECT) <integer>
118 Is a hint of what type of data the OpenSSL library expects to get.
119 This is only useful for optimization, as the library will check
120 that the object types match the expectation too.
121 The number that can be given through this parameter is found in
123 <openssl/store.h>, with the macros having names starting with
124 "OSSL_STORE_INFO_". These are further described in "SUPPORTED
125 OBJECTS" in OSSL_STORE_INFO(3).
126 "subject" (OSSL_STORE_PARAM_SUBJECT) <octet string>
128 Indicates that the caller wants to search for an object with the
129 given subject associated. This can be used to select specific
130 certificates by subject.
131 The contents of the octet string is expected to be in DER form.
133 "issuer" (OSSL_STORE_PARAM_ISSUER) <octet string>
135 Indicates that the caller wants to search for an object with the
136 given issuer associated. This can be used to select specific
137 certificates by issuer.
138 The contents of the octet string is expected to be in DER form.
140 "serial" (OSSL_STORE_PARAM_SERIAL) <integer>
142 Indicates that the caller wants to search for an object with the
143 given serial number associated.
144 "digest" (OSSL_STORE_PARAM_DIGEST) <UTF8 string>
146 "fingerprint" (OSSL_STORE_PARAM_FINGERPRINT) <octet string>
147 Indicates that the caller wants to search for an object with the
148 given fingerprint, computed with the given digest.
149 "alias" (OSSL_STORE_PARAM_ALIAS) <UTF8 string>
151 Indicates that the caller wants to search for an object with the
152 given alias (some call it a "friendly name").
153 "properties" (OSSL_STORE_PARAM_PROPERTIES) <utf8 string
155 Property string to use when querying for algorithms such as the
156 OSSL_DECODER decoder implementations.
157 "input-type" (OSSL_STORE_PARAM_INPUT_TYPE) <utf8 string
159 Type of the input format as a hint to use when decoding the objects
160 in the store.
161 Several of these search criteria may be combined. For example, to
163 search for a certificate by issuer+serial, both the "issuer" and the
164 "serial" parameters will be given.
165
167 provider(7)
168
170 The STORE interface was introduced in OpenSSL 3.0.
171
173 Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
174 Licensed under the Apache License 2.0 (the "License"). You may not use
176 this file except in compliance with the License. You can obtain a copy
177 in the file LICENSE in the source distribution or at
178 <https://www.openssl.org/source/license.html>.
1793.0.9 2023-07-27 PROVIDER-STOREMGMT(7ossl)