Debian Codegraph @

upstream/debian-unstable/man7/provider-storemgmt.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PROVIDER-STOREMGMT 7SSL"
58 .TH PROVIDER-STOREMGMT 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 provider\-storemgmt \- The OSSL_STORE library <\-> provider functions
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/core_dispatch.h>
69 \&
70 \& /*
71 \& * None of these are actual functions, but are displayed like this for
72 \& * the function signatures for functions that are offered as function
73 \& * pointers in OSSL_DISPATCH arrays.
74 \& */
75 \&
76 \& void *OSSL_FUNC_store_open(void *provctx, const char *uri);
77 \& void *OSSL_FUNC_store_attach(void *provctx, OSSL_CORE_BIO *bio);
78 \& const OSSL_PARAM *store_settable_ctx_params(void *provctx);
79 \& int OSSL_FUNC_store_set_ctx_params(void *loaderctx, const OSSL_PARAM[]);
80 \& int OSSL_FUNC_store_load(void *loaderctx,
81 \& OSSL_CALLBACK *object_cb, void *object_cbarg,
82 \& OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg);
83 \& int OSSL_FUNC_store_eof(void *loaderctx);
84 \& int OSSL_FUNC_store_close(void *loaderctx);
85 \&
86 \& int OSSL_FUNC_store_export_object
87 \& (void *loaderctx, const void *objref, size_t objref_sz,
88 \& OSSL_CALLBACK *export_cb, void *export_cbarg);
89 \& void *OSSL_FUNC_store_open_ex(void *provctx, const char *uri,
90 \& const OSSL_PARAM params[],
91 \& OSSL_PASSPHRASE_CALLBACK *pw_cb,
92 \& void *pw_cbarg);
93 \&
94 \& int OSSL_FUNC_store_delete(void *provctx, const char *uri,
95 \& const OSSL_PARAM params[],
96 \& OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg);
97 .Ve
98 .SH DESCRIPTION
99 .IX Header "DESCRIPTION"
100 The STORE operation is the provider side of the \fBossl_store\fR\|(7) API.
101 .PP
102 The primary responsibility of the STORE operation is to load all sorts
103 of objects from a container indicated by URI. These objects are given
104 to the OpenSSL library in provider-native object abstraction form (see
105 \&\fBprovider\-object\fR\|(7)). The OpenSSL library is then responsible for
106 passing on that abstraction to suitable provided functions.
107 .PP
108 Examples of functions that the OpenSSL library can pass the abstraction to
109 include \fBOSSL_FUNC_keymgmt_load()\fR (\fBprovider\-keymgmt\fR\|(7)),
110 \&\fBOSSL_FUNC_store_export_object()\fR (which exports the object in parameterized
111 form).
112 .PP
113 All "functions" mentioned here are passed as function pointers between
114 \&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via
115 \&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider's
116 \&\fBprovider_query_operation()\fR function
117 (see "Provider Functions" in \fBprovider\-base\fR\|(7)).
118 .PP
119 All these "functions" have a corresponding function type definition named
120 \&\fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the function pointer
121 from a \fBOSSL_DISPATCH\fR\|(3) element named \fBOSSL_get_{name}\fR.
122 For example, the "function" \fBOSSL_FUNC_store_attach()\fR has these:
123 .PP
124 .Vb 4
125 \& typedef void *(OSSL_FUNC_store_attach_fn)(void *provctx,
126 \& OSSL_CORE_BIO * bio);
127 \& static ossl_inline OSSL_FUNC_store_attach_fn
128 \& OSSL_FUNC_store_attach(const OSSL_DISPATCH *opf);
129 .Ve
130 .PP
131 \&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as macros
132 in \fBopenssl\-core_dispatch.h\fR\|(7), as follows:
133 .PP
134 .Vb 10
135 \& OSSL_FUNC_store_open OSSL_FUNC_STORE_OPEN
136 \& OSSL_FUNC_store_attach OSSL_FUNC_STORE_ATTACH
137 \& OSSL_FUNC_store_settable_ctx_params OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS
138 \& OSSL_FUNC_store_set_ctx_params OSSL_FUNC_STORE_SET_CTX_PARAMS
139 \& OSSL_FUNC_store_load OSSL_FUNC_STORE_LOAD
140 \& OSSL_FUNC_store_eof OSSL_FUNC_STORE_EOF
141 \& OSSL_FUNC_store_close OSSL_FUNC_STORE_CLOSE
142 \& OSSL_FUNC_store_export_object OSSL_FUNC_STORE_EXPORT_OBJECT
143 \& OSSL_FUNC_store_delete OSSL_FUNC_STORE_DELETE
144 \& OSSL_FUNC_store_open_ex OSSL_FUNC_STORE_OPEN_EX
145 .Ve
146 .SS Functions
147 .IX Subsection "Functions"
148 \&\fBOSSL_FUNC_store_open()\fR should create a provider side context with data based
149 on the input \fIuri\fR. The implementation is entirely responsible for the
150 interpretation of the URI.
151 .PP
152 \&\fBOSSL_FUNC_store_attach()\fR should create a provider side context with the core
153 \&\fBBIO\fR \fIbio\fR attached. This is an alternative to using a URI to find storage,
154 supporting \fBOSSL_STORE_attach\fR\|(3).
155 .PP
156 \&\fBOSSL_FUNC_store_settable_ctx_params()\fR should return a constant array of
157 descriptor \fBOSSL_PARAM\fR\|(3), for parameters that \fBOSSL_FUNC_store_set_ctx_params()\fR
158 can handle.
159 .PP
160 \&\fBOSSL_FUNC_store_set_ctx_params()\fR should set additional parameters, such as what
161 kind of data to expect, search criteria, and so on. More on those below, in
162 "Load Parameters". Whether unrecognised parameters are an error or simply
163 ignored is at the implementation's discretion.
164 Passing NULL for \fIparams\fR should return true.
165 .PP
166 \&\fBOSSL_FUNC_store_load()\fR loads the next object from the URI opened by
167 \&\fBOSSL_FUNC_store_open()\fR, creates an object abstraction for it (see
168 \&\fBprovider\-object\fR\|(7)), and calls \fIobject_cb\fR with it as well as
169 \&\fIobject_cbarg\fR. \fIobject_cb\fR will then interpret the object abstraction
170 and do what it can to wrap it or decode it into an OpenSSL structure. In
171 case a passphrase needs to be prompted to unlock an object, \fIpw_cb\fR should
172 be called.
173 .PP
174 \&\fBOSSL_FUNC_store_eof()\fR indicates if the end of the set of objects from the
175 URI has been reached. When that happens, there's no point trying to do any
176 further loading.
177 .PP
178 \&\fBOSSL_FUNC_store_close()\fR frees the provider side context \fIctx\fR.
179 .PP
180 When a provider-native object is created by a store manager it would be unsuitable
181 for direct use with a foreign provider. The export function allows for
182 exporting the object to that foreign provider if the foreign provider
183 supports the type of the object and provides an import function.
184 .PP
185 \&\fBOSSL_FUNC_store_export_object()\fR should export the object of size \fIobjref_sz\fR
186 referenced by \fIobjref\fR as an \fBOSSL_PARAM\fR\|(3) array and pass that to the
187 \&\fIexport_cb\fR as well as the given \fIexport_cbarg\fR.
188 .PP
189 \&\fBOSSL_FUNC_store_delete()\fR deletes the object identified by the \fIuri\fR. The
190 implementation is entirely responsible for the interpretation of the URI. In
191 case a passphrase needs to be prompted to remove an object, \fIpw_cb\fR should be
192 called.
193 .PP
194 \&\fBOSSL_FUNC_store_open_ex()\fR is an extended variant of \fBOSSL_FUNC_store_open()\fR. If
195 the provider does not implement this function the code internally falls back to
196 use the original \fBOSSL_FUNC_store_open()\fR.
197 This variant additionally accepts an \fBOSSL_PARAM\fR\|(3) object and a \fIpw_cb\fR
198 callback that can be used to request a passphrase in cases where the whole
199 store needs to be unlocked before performing any load operation.
200 .SS "Load Parameters"
201 .IX Subsection "Load Parameters"
202 .IP """expect"" (\fBOSSL_STORE_PARAM_EXPECT\fR) <integer>" 4
203 .IX Item """expect"" (OSSL_STORE_PARAM_EXPECT) <integer>"
204 Is a hint of what type of data the OpenSSL library expects to get.
205 This is only useful for optimization, as the library will check that the
206 object types match the expectation too.
207 .Sp
208 The number that can be given through this parameter is found in
209 \&\fI<openssl/store.h>\fR, with the macros having names starting with
210 \&\f(CW\*(C`OSSL_STORE_INFO_\*(C'\fR. These are further described in
211 "SUPPORTED OBJECTS" in \fBOSSL_STORE_INFO\fR\|(3).
212 .IP """subject"" (\fBOSSL_STORE_PARAM_SUBJECT\fR) <octet string>" 4
213 .IX Item """subject"" (OSSL_STORE_PARAM_SUBJECT) <octet string>"
214 Indicates that the caller wants to search for an object with the given
215 subject associated. This can be used to select specific certificates
216 by subject.
217 .Sp
218 The contents of the octet string is expected to be in DER form.
219 .IP """issuer"" (\fBOSSL_STORE_PARAM_ISSUER\fR) <octet string>" 4
220 .IX Item """issuer"" (OSSL_STORE_PARAM_ISSUER) <octet string>"
221 Indicates that the caller wants to search for an object with the given
222 issuer associated. This can be used to select specific certificates
223 by issuer.
224 .Sp
225 The contents of the octet string is expected to be in DER form.
226 .IP """serial"" (\fBOSSL_STORE_PARAM_SERIAL\fR) <integer>" 4
227 .IX Item """serial"" (OSSL_STORE_PARAM_SERIAL) <integer>"
228 Indicates that the caller wants to search for an object with the given
229 serial number associated.
230 .IP """digest"" (\fBOSSL_STORE_PARAM_DIGEST\fR) <UTF8 string>" 4
231 .IX Item """digest"" (OSSL_STORE_PARAM_DIGEST) <UTF8 string>"
232 .PD 0
233 .IP """fingerprint"" (\fBOSSL_STORE_PARAM_FINGERPRINT\fR) <octet string>" 4
234 .IX Item """fingerprint"" (OSSL_STORE_PARAM_FINGERPRINT) <octet string>"
235 .PD
236 Indicates that the caller wants to search for an object with the given
237 fingerprint, computed with the given digest.
238 .IP """alias"" (\fBOSSL_STORE_PARAM_ALIAS\fR) <UTF8 string>" 4
239 .IX Item """alias"" (OSSL_STORE_PARAM_ALIAS) <UTF8 string>"
240 Indicates that the caller wants to search for an object with the given
241 alias (some call it a "friendly name").
242 .IP """properties"" (\fBOSSL_STORE_PARAM_PROPERTIES\fR) <utf8 string>" 4
243 .IX Item """properties"" (OSSL_STORE_PARAM_PROPERTIES) <utf8 string>"
244 Property string to use when querying for algorithms such as the \fBOSSL_DECODER\fR
245 decoder implementations.
246 .IP """input-type"" (\fBOSSL_STORE_PARAM_INPUT_TYPE\fR) <utf8 string>" 4
247 .IX Item """input-type"" (OSSL_STORE_PARAM_INPUT_TYPE) <utf8 string>"
248 Type of the input format as a hint to use when decoding the objects in the
249 store.
250 .PP
251 Several of these search criteria may be combined. For example, to
252 search for a certificate by issuer+serial, both the "issuer" and the
253 "serial" parameters will be given.
254 .SH "SEE ALSO"
255 .IX Header "SEE ALSO"
256 \&\fBprovider\fR\|(7)
257 .SH HISTORY
258 .IX Header "HISTORY"
259 The STORE interface was introduced in OpenSSL 3.0.
260 .PP
261 \&\fBOSSL_FUNC_store_delete()\fR callback was added in OpenSSL 3.2
262 .SH COPYRIGHT
263 .IX Header "COPYRIGHT"
264 Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved.
265 .PP
266 Licensed under the Apache License 2.0 (the "License"). You may not use
267 this file except in compliance with the License. You can obtain a copy
268 in the file LICENSE in the source distribution or at
269 <https://www.openssl.org/source/license.html>.