]>
Commit | Line | Data |
---|---|---|
8704b6bf RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | provider-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 | ||
33 | The STORE operation is the provider side of the L<ossl_store(7)> API. | |
34 | ||
35 | The primary responsibility of the STORE operation is to load all sorts | |
36 | of objects from a container indicated by URI. These objects are given | |
37 | to the OpenSSL library in provider-native object abstraction form (see | |
38 | L<provider-object(7)>). The OpenSSL library is then responsible for | |
39 | passing on that abstraction to suitable provided functions. | |
40 | ||
41 | Examples of functions that the OpenSSL library can pass the abstraction to | |
42 | include OSSL_FUNC_keymgmt_load() (L<provider-keymgmt(7)>), | |
43 | OSSL_FUNC_store_export_object() (which exports the object in parameterized | |
44 | form). | |
45 | ||
46 | All "functions" mentioned here are passed as function pointers between | |
47 | F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via | |
48 | B<OSSL_ALGORITHM> arrays that are returned by the provider's | |
49 | provider_query_operation() function | |
50 | (see L<provider-base(7)/Provider Functions>). | |
51 | ||
52 | All these "functions" have a corresponding function type definition named | |
53 | B<OSSL_{name}_fn>, and a helper function to retrieve the function pointer | |
54 | from a B<OSSL_DISPATCH> element named B<OSSL_get_{name}>. | |
55 | For 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 | ||
62 | B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as macros | |
63 | in 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 | ||
76 | OSSL_FUNC_store_open() should create a provider side context with data based | |
77 | on the input I<uri>. The implementation is entirely responsible for the | |
78 | interpretation of the URI. | |
79 | ||
80 | OSSL_FUNC_store_attach() should create a provider side context with the core | |
81 | B<BIO> I<bio> attached. This is an alternative to using a URI to find storage, | |
82 | supporting L<OSSL_STORE_attach(3)>. | |
83 | ||
84 | OSSL_FUNC_store_settable_ctx_params() should return a constant array of | |
85 | descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_store_set_ctx_params() | |
86 | can handle. | |
87 | ||
88 | OSSL_FUNC_store_set_ctx_params() should set additional parameters, such as what | |
89 | kind of data to expect, search criteria, and so on. More on those below, in | |
90 | L</Load Parameters>. Whether unrecognised parameters are an error or simply | |
91 | ignored is at the implementation's discretion. | |
f59612fe | 92 | Passing NULL for I<params> should return true. |
8704b6bf RL |
93 | |
94 | OSSL_FUNC_store_load() loads the next object from the URI opened by | |
95 | OSSL_FUNC_store_open(), creates an object abstraction for it (see | |
96 | L<provider-object(7)>), and calls I<object_cb> with it as well as | |
97 | I<object_cbarg>. I<object_cb> will then interpret the object abstraction | |
98 | and do what it can to wrap it or decode it into an OpenSSL structure. In | |
99 | case a passphrase needs to be prompted to unlock an object, I<pw_cb> should | |
100 | be called. | |
101 | ||
102 | OSSL_FUNC_store_eof() indicates if the end of the set of objects from the | |
103 | URI has been reached. When that happens, there's no point trying to do any | |
104 | further loading. | |
105 | ||
106 | OSSL_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 | ||
114 | Is a hint of what type of data the OpenSSL library expects to get. | |
115 | This is only useful for optimization, as the library will check that the | |
116 | object types match the expectation too. | |
117 | ||
118 | The number that can be given through this parameter is found in | |
119 | F<< <openssl/store.h> >>, with the macros having names starting with | |
120 | C<OSSL_STORE_INFO_>. These are further described in | |
121 | L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS>. | |
122 | ||
123 | =item "subject" (B<OSSL_STORE_PARAM_SUBJECT>) <octet string> | |
124 | ||
125 | Indicates that the caller wants to search for an object with the given | |
126 | subject associated. This can be used to select specific certificates | |
127 | by subject. | |
128 | ||
129 | The contents of the octet string is expected to be in DER form. | |
130 | ||
131 | =item "issuer" (B<OSSL_STORE_PARAM_ISSUER>) <octet string> | |
132 | ||
133 | Indicates that the caller wants to search for an object with the given | |
134 | issuer associated. This can be used to select specific certificates | |
135 | by issuer. | |
136 | ||
137 | The contents of the octet string is expected to be in DER form. | |
138 | ||
139 | =item "serial" (B<OSSL_STORE_PARAM_SERIAL>) <integer> | |
140 | ||
141 | Indicates that the caller wants to search for an object with the given | |
142 | serial 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 | ||
148 | Indicates that the caller wants to search for an object with the given | |
149 | fingerprint, computed with the given digest. | |
150 | ||
151 | =item "alias" (B<OSSL_STORE_PARAM_ALIAS>) <utf8 string> | |
152 | ||
153 | Indicates that the caller wants to search for an object with the given | |
154 | alias (some call it a "friendly name"). | |
155 | ||
156 | =back | |
157 | ||
158 | Several of these search criteria may be combined. For example, to | |
159 | search for a certificate by issuer+serial, both the "issuer" and the | |
160 | "serial" parameters will be given. | |
161 | ||
162 | =head1 SEE ALSO | |
163 | ||
164 | L<provider(7)> | |
165 | ||
166 | =head1 HISTORY | |
167 | ||
168 | The STORE interface was introduced in OpenSSL 3.0. | |
169 | ||
170 | =head1 COPYRIGHT | |
171 | ||
3c2bdd7d | 172 | Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. |
8704b6bf RL |
173 | |
174 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
175 | this file except in compliance with the License. You can obtain a copy | |
176 | in the file LICENSE in the source distribution or at | |
177 | L<https://www.openssl.org/source/license.html>. | |
178 | ||
179 | =cut |