]>
Commit | Line | Data |
---|---|---|
71a5516d | 1 | /* |
454afd98 | 2 | * Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. |
71a5516d | 3 | * |
48f4ad77 | 4 | * Licensed under the Apache License 2.0 (the "License"). You may not use |
71a5516d RL |
5 | * this file except in compliance with the License. You can obtain a copy |
6 | * in the file LICENSE in the source distribution or at | |
7 | * https://www.openssl.org/source/license.html | |
8 | */ | |
9 | ||
ae4186b0 DMSP |
10 | #ifndef OPENSSL_STORE_H |
11 | # define OPENSSL_STORE_H | |
d86167ec DMSP |
12 | # pragma once |
13 | ||
14 | # include <openssl/macros.h> | |
936c2b9e | 15 | # ifndef OPENSSL_NO_DEPRECATED_3_0 |
d86167ec DMSP |
16 | # define HEADER_OSSL_STORE_H |
17 | # endif | |
71a5516d RL |
18 | |
19 | # include <stdarg.h> | |
50cd4768 | 20 | # include <openssl/types.h> |
71a5516d RL |
21 | # include <openssl/pem.h> |
22 | # include <openssl/storeerr.h> | |
23 | ||
24 | # ifdef __cplusplus | |
25 | extern "C" { | |
26 | # endif | |
27 | ||
28 | /*- | |
29 | * The main OSSL_STORE functions. | |
30 | * ------------------------------ | |
31 | * | |
32 | * These allow applications to open a channel to a resource with supported | |
33 | * data (keys, certs, crls, ...), read the data a piece at a time and decide | |
34 | * what to do with it, and finally close. | |
35 | */ | |
36 | ||
37 | typedef struct ossl_store_ctx_st OSSL_STORE_CTX; | |
38 | ||
39 | /* | |
40 | * Typedef for the OSSL_STORE_INFO post processing callback. This can be used | |
41 | * to massage the given OSSL_STORE_INFO, or to drop it entirely (by returning | |
42 | * NULL). | |
43 | */ | |
44 | typedef OSSL_STORE_INFO *(*OSSL_STORE_post_process_info_fn)(OSSL_STORE_INFO *, | |
45 | void *); | |
46 | ||
47 | /* | |
48 | * Open a channel given a URI. The given UI method will be used any time the | |
49 | * loader needs extra input, for example when a password or pin is needed, and | |
50 | * will be passed the same user data every time it's needed in this context. | |
51 | * | |
52 | * Returns a context reference which represents the channel to communicate | |
53 | * through. | |
54 | */ | |
34b80d06 RL |
55 | OSSL_STORE_CTX * |
56 | OSSL_STORE_open(const char *uri, const UI_METHOD *ui_method, void *ui_data, | |
57 | OSSL_STORE_post_process_info_fn post_process, | |
58 | void *post_process_data); | |
59 | OSSL_STORE_CTX * | |
d8652be0 MC |
60 | OSSL_STORE_open_ex(const char *uri, OPENSSL_CTX *libctx, const char *propq, |
61 | const UI_METHOD *ui_method, void *ui_data, | |
62 | OSSL_STORE_post_process_info_fn post_process, | |
63 | void *post_process_data); | |
6725682d | 64 | |
71a5516d RL |
65 | /* |
66 | * Control / fine tune the OSSL_STORE channel. |cmd| determines what is to be | |
67 | * done, and depends on the underlying loader (use OSSL_STORE_get0_scheme to | |
68 | * determine which loader is used), except for common commands (see below). | |
69 | * Each command takes different arguments. | |
70 | */ | |
a1447076 RL |
71 | DEPRECATEDIN_3_0(int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, |
72 | ... /* args */)) | |
73 | DEPRECATEDIN_3_0(int OSSL_STORE_vctrl(OSSL_STORE_CTX *ctx, int cmd, | |
74 | va_list args)) | |
75 | ||
76 | # ifndef OPENSSL_NO_DEPRECATED_3_0 | |
71a5516d RL |
77 | |
78 | /* | |
79 | * Common ctrl commands that different loaders may choose to support. | |
80 | */ | |
7852f588 RL |
81 | /* int on = 0 or 1; STORE_ctrl(ctx, STORE_C_USE_SECMEM, &on); */ |
82 | # define OSSL_STORE_C_USE_SECMEM 1 | |
71a5516d RL |
83 | /* Where custom commands start */ |
84 | # define OSSL_STORE_C_CUSTOM_START 100 | |
85 | ||
a1447076 RL |
86 | # endif |
87 | ||
71a5516d RL |
88 | /* |
89 | * Read one data item (a key, a cert, a CRL) that is supported by the OSSL_STORE | |
90 | * functionality, given a context. | |
91 | * Returns a OSSL_STORE_INFO pointer, from which OpenSSL typed data can be | |
92 | * extracted with OSSL_STORE_INFO_get0_PKEY(), OSSL_STORE_INFO_get0_CERT(), ... | |
93 | * NULL is returned on error, which may include that the data found at the URI | |
94 | * can't be figured out for certain or is ambiguous. | |
95 | */ | |
96 | OSSL_STORE_INFO *OSSL_STORE_load(OSSL_STORE_CTX *ctx); | |
97 | ||
98 | /* | |
99 | * Check if end of data (end of file) is reached | |
100 | * Returns 1 on end, 0 otherwise. | |
101 | */ | |
102 | int OSSL_STORE_eof(OSSL_STORE_CTX *ctx); | |
103 | ||
104 | /* | |
68756b12 | 105 | * Check if an error occurred |
71a5516d RL |
106 | * Returns 1 if it did, 0 otherwise. |
107 | */ | |
108 | int OSSL_STORE_error(OSSL_STORE_CTX *ctx); | |
109 | ||
110 | /* | |
111 | * Close the channel | |
112 | * Returns 1 on success, 0 on error. | |
113 | */ | |
114 | int OSSL_STORE_close(OSSL_STORE_CTX *ctx); | |
115 | ||
6ab6ecfd RL |
116 | /* |
117 | * Attach to a BIO. This works like OSSL_STORE_open() except it takes a | |
118 | * BIO instead of a uri, along with a scheme to use when reading. | |
119 | * The given UI method will be used any time the loader needs extra input, | |
120 | * for example when a password or pin is needed, and will be passed the | |
121 | * same user data every time it's needed in this context. | |
122 | * | |
123 | * Returns a context reference which represents the channel to communicate | |
124 | * through. | |
125 | * | |
126 | * Note that this function is considered unsafe, all depending on what the | |
127 | * BIO actually reads. | |
128 | */ | |
6725682d SL |
129 | OSSL_STORE_CTX *OSSL_STORE_attach(BIO *bio, const char *scheme, |
130 | OPENSSL_CTX *libctx, const char *propq, | |
6ab6ecfd RL |
131 | const UI_METHOD *ui_method, void *ui_data, |
132 | OSSL_STORE_post_process_info_fn post_process, | |
133 | void *post_process_data); | |
71a5516d RL |
134 | |
135 | /*- | |
136 | * Extracting OpenSSL types from and creating new OSSL_STORE_INFOs | |
137 | * --------------------------------------------------------------- | |
138 | */ | |
139 | ||
140 | /* | |
141 | * Types of data that can be ossl_stored in a OSSL_STORE_INFO. | |
142 | * OSSL_STORE_INFO_NAME is typically found when getting a listing of | |
143 | * available "files" / "tokens" / what have you. | |
144 | */ | |
145 | # define OSSL_STORE_INFO_NAME 1 /* char * */ | |
146 | # define OSSL_STORE_INFO_PARAMS 2 /* EVP_PKEY * */ | |
2274d22d RL |
147 | # define OSSL_STORE_INFO_PUBKEY 3 /* EVP_PKEY * */ |
148 | # define OSSL_STORE_INFO_PKEY 4 /* EVP_PKEY * */ | |
149 | # define OSSL_STORE_INFO_CERT 5 /* X509 * */ | |
150 | # define OSSL_STORE_INFO_CRL 6 /* X509_CRL * */ | |
71a5516d RL |
151 | |
152 | /* | |
153 | * Functions to generate OSSL_STORE_INFOs, one function for each type we | |
1fb2993d | 154 | * support having in them, as well as a generic constructor. |
71a5516d | 155 | * |
68756b12 | 156 | * In all cases, ownership of the object is transferred to the OSSL_STORE_INFO |
71a5516d RL |
157 | * and will therefore be freed when the OSSL_STORE_INFO is freed. |
158 | */ | |
16feca71 | 159 | OSSL_STORE_INFO *OSSL_STORE_INFO_new(int type, void *data); |
71a5516d RL |
160 | OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name); |
161 | int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc); | |
162 | OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(EVP_PKEY *params); | |
2274d22d | 163 | OSSL_STORE_INFO *OSSL_STORE_INFO_new_PUBKEY(EVP_PKEY *pubkey); |
71a5516d RL |
164 | OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey); |
165 | OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509); | |
166 | OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl); | |
167 | ||
168 | /* | |
169 | * Functions to try to extract data from a OSSL_STORE_INFO. | |
170 | */ | |
171 | int OSSL_STORE_INFO_get_type(const OSSL_STORE_INFO *info); | |
16feca71 | 172 | void *OSSL_STORE_INFO_get0_data(int type, const OSSL_STORE_INFO *info); |
71a5516d RL |
173 | const char *OSSL_STORE_INFO_get0_NAME(const OSSL_STORE_INFO *info); |
174 | char *OSSL_STORE_INFO_get1_NAME(const OSSL_STORE_INFO *info); | |
175 | const char *OSSL_STORE_INFO_get0_NAME_description(const OSSL_STORE_INFO *info); | |
176 | char *OSSL_STORE_INFO_get1_NAME_description(const OSSL_STORE_INFO *info); | |
177 | EVP_PKEY *OSSL_STORE_INFO_get0_PARAMS(const OSSL_STORE_INFO *info); | |
178 | EVP_PKEY *OSSL_STORE_INFO_get1_PARAMS(const OSSL_STORE_INFO *info); | |
2274d22d RL |
179 | EVP_PKEY *OSSL_STORE_INFO_get0_PUBKEY(const OSSL_STORE_INFO *info); |
180 | EVP_PKEY *OSSL_STORE_INFO_get1_PUBKEY(const OSSL_STORE_INFO *info); | |
71a5516d RL |
181 | EVP_PKEY *OSSL_STORE_INFO_get0_PKEY(const OSSL_STORE_INFO *info); |
182 | EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *info); | |
183 | X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *info); | |
184 | X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *info); | |
185 | X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *info); | |
186 | X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *info); | |
187 | ||
188 | const char *OSSL_STORE_INFO_type_string(int type); | |
189 | ||
190 | /* | |
191 | * Free the OSSL_STORE_INFO | |
192 | */ | |
193 | void OSSL_STORE_INFO_free(OSSL_STORE_INFO *info); | |
194 | ||
fac8673b RL |
195 | |
196 | /*- | |
197 | * Functions to construct a search URI from a base URI and search criteria | |
198 | * ----------------------------------------------------------------------- | |
199 | */ | |
200 | ||
201 | /* OSSL_STORE search types */ | |
202 | # define OSSL_STORE_SEARCH_BY_NAME 1 /* subject in certs, issuer in CRLs */ | |
203 | # define OSSL_STORE_SEARCH_BY_ISSUER_SERIAL 2 | |
204 | # define OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT 3 | |
205 | # define OSSL_STORE_SEARCH_BY_ALIAS 4 | |
206 | ||
207 | /* To check what search types the scheme handler supports */ | |
208 | int OSSL_STORE_supports_search(OSSL_STORE_CTX *ctx, int search_type); | |
209 | ||
210 | /* Search term constructors */ | |
211 | /* | |
212 | * The input is considered to be owned by the caller, and must therefore | |
213 | * remain present throughout the lifetime of the returned OSSL_STORE_SEARCH | |
214 | */ | |
215 | OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_name(X509_NAME *name); | |
216 | OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_issuer_serial(X509_NAME *name, | |
217 | const ASN1_INTEGER | |
218 | *serial); | |
219 | OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_key_fingerprint(const EVP_MD *digest, | |
220 | const unsigned char | |
221 | *bytes, size_t len); | |
222 | OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_alias(const char *alias); | |
223 | ||
224 | /* Search term destructor */ | |
225 | void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search); | |
226 | ||
227 | /* Search term accessors */ | |
228 | int OSSL_STORE_SEARCH_get_type(const OSSL_STORE_SEARCH *criterion); | |
e3c4ad28 | 229 | X509_NAME *OSSL_STORE_SEARCH_get0_name(const OSSL_STORE_SEARCH *criterion); |
fac8673b RL |
230 | const ASN1_INTEGER *OSSL_STORE_SEARCH_get0_serial(const OSSL_STORE_SEARCH |
231 | *criterion); | |
232 | const unsigned char *OSSL_STORE_SEARCH_get0_bytes(const OSSL_STORE_SEARCH | |
233 | *criterion, size_t *length); | |
234 | const char *OSSL_STORE_SEARCH_get0_string(const OSSL_STORE_SEARCH *criterion); | |
235 | const EVP_MD *OSSL_STORE_SEARCH_get0_digest(const OSSL_STORE_SEARCH *criterion); | |
236 | ||
072bfcc9 | 237 | /* |
fac8673b RL |
238 | * Add search criterion and expected return type (which can be unspecified) |
239 | * to the loading channel. This MUST happen before the first OSSL_STORE_load(). | |
072bfcc9 RL |
240 | */ |
241 | int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type); | |
e3c4ad28 | 242 | int OSSL_STORE_find(OSSL_STORE_CTX *ctx, const OSSL_STORE_SEARCH *search); |
072bfcc9 | 243 | |
71a5516d | 244 | |
c4fc564d RL |
245 | /*- |
246 | * Function to fetch a loader and extract data from it | |
247 | * --------------------------------------------------- | |
248 | */ | |
249 | ||
250 | typedef struct ossl_store_loader_st OSSL_STORE_LOADER; | |
251 | ||
252 | OSSL_STORE_LOADER *OSSL_STORE_LOADER_fetch(const char *scheme, | |
253 | OPENSSL_CTX *libctx, | |
254 | const char *properties); | |
255 | int OSSL_STORE_LOADER_up_ref(OSSL_STORE_LOADER *loader); | |
256 | void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *loader); | |
257 | const OSSL_PROVIDER *OSSL_STORE_LOADER_provider(const OSSL_STORE_LOADER * | |
258 | loader); | |
259 | const char *OSSL_STORE_LOADER_properties(const OSSL_STORE_LOADER *loader); | |
260 | int OSSL_STORE_LOADER_number(const OSSL_STORE_LOADER *loader); | |
261 | int OSSL_STORE_LOADER_is_a(const OSSL_STORE_LOADER *loader, | |
262 | const char *scheme); | |
263 | void OSSL_STORE_LOADER_do_all_provided(OPENSSL_CTX *libctx, | |
264 | void (*fn)(OSSL_STORE_LOADER *loader, | |
265 | void *arg), | |
266 | void *arg); | |
267 | void OSSL_STORE_LOADER_names_do_all(const OSSL_STORE_LOADER *loader, | |
268 | void (*fn)(const char *name, void *data), | |
269 | void *data); | |
270 | ||
71a5516d RL |
271 | /*- |
272 | * Function to register a loader for the given URI scheme. | |
273 | * ------------------------------------------------------- | |
274 | * | |
275 | * The loader receives all the main components of an URI except for the | |
276 | * scheme. | |
277 | */ | |
278 | ||
a1447076 RL |
279 | # ifndef OPENSSL_NO_DEPRECATED_3_0 |
280 | ||
71a5516d RL |
281 | /* struct ossl_store_loader_ctx_st is defined differently by each loader */ |
282 | typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX; | |
6725682d SL |
283 | typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn) |
284 | (const OSSL_STORE_LOADER *loader, const char *uri, | |
285 | const UI_METHOD *ui_method, void *ui_data); | |
d8652be0 | 286 | typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_ex_fn) |
6725682d SL |
287 | (const OSSL_STORE_LOADER *loader, |
288 | const char *uri, OPENSSL_CTX *libctx, const char *propq, | |
289 | const UI_METHOD *ui_method, void *ui_data); | |
290 | ||
c4fc564d RL |
291 | typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_attach_fn) |
292 | (const OSSL_STORE_LOADER *loader, BIO *bio, | |
293 | OPENSSL_CTX *libctx, const char *propq, | |
294 | const UI_METHOD *ui_method, void *ui_data); | |
295 | typedef int (*OSSL_STORE_ctrl_fn) | |
296 | (OSSL_STORE_LOADER_CTX *ctx, int cmd, va_list args); | |
297 | typedef int (*OSSL_STORE_expect_fn) | |
298 | (OSSL_STORE_LOADER_CTX *ctx, int expected); | |
299 | typedef int (*OSSL_STORE_find_fn) | |
300 | (OSSL_STORE_LOADER_CTX *ctx, const OSSL_STORE_SEARCH *criteria); | |
301 | typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn) | |
302 | (OSSL_STORE_LOADER_CTX *ctx, const UI_METHOD *ui_method, void *ui_data); | |
303 | typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx); | |
304 | typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx); | |
305 | typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx); | |
306 | ||
a1447076 RL |
307 | # endif |
308 | ||
309 | DEPRECATEDIN_3_0(OSSL_STORE_LOADER *OSSL_STORE_LOADER_new | |
310 | (ENGINE *e, const char *scheme)) | |
311 | DEPRECATEDIN_3_0(int OSSL_STORE_LOADER_set_open | |
312 | (OSSL_STORE_LOADER *loader, | |
313 | OSSL_STORE_open_fn open_function)) | |
d8652be0 | 314 | DEPRECATEDIN_3_0(int OSSL_STORE_LOADER_set_open_ex |
a1447076 | 315 | (OSSL_STORE_LOADER *loader, |
d8652be0 | 316 | OSSL_STORE_open_ex_fn open_ex_function)) |
a1447076 RL |
317 | DEPRECATEDIN_3_0(int OSSL_STORE_LOADER_set_attach |
318 | (OSSL_STORE_LOADER *loader, | |
319 | OSSL_STORE_attach_fn attach_function)) | |
320 | DEPRECATEDIN_3_0(int OSSL_STORE_LOADER_set_ctrl | |
321 | (OSSL_STORE_LOADER *loader, | |
322 | OSSL_STORE_ctrl_fn ctrl_function)) | |
323 | DEPRECATEDIN_3_0(int OSSL_STORE_LOADER_set_expect | |
324 | (OSSL_STORE_LOADER *loader, | |
325 | OSSL_STORE_expect_fn expect_function)) | |
326 | DEPRECATEDIN_3_0(int OSSL_STORE_LOADER_set_find | |
327 | (OSSL_STORE_LOADER *loader, | |
328 | OSSL_STORE_find_fn find_function)) | |
329 | DEPRECATEDIN_3_0(int OSSL_STORE_LOADER_set_load | |
330 | (OSSL_STORE_LOADER *loader, | |
331 | OSSL_STORE_load_fn load_function)) | |
332 | DEPRECATEDIN_3_0(int OSSL_STORE_LOADER_set_eof | |
333 | (OSSL_STORE_LOADER *loader, | |
334 | OSSL_STORE_eof_fn eof_function)) | |
335 | DEPRECATEDIN_3_0(int OSSL_STORE_LOADER_set_error | |
336 | (OSSL_STORE_LOADER *loader, | |
337 | OSSL_STORE_error_fn error_function)) | |
338 | DEPRECATEDIN_3_0(int OSSL_STORE_LOADER_set_close | |
339 | (OSSL_STORE_LOADER *loader, | |
340 | OSSL_STORE_close_fn close_function)) | |
341 | ||
342 | DEPRECATEDIN_3_0(const ENGINE *OSSL_STORE_LOADER_get0_engine | |
343 | (const OSSL_STORE_LOADER *loader)) | |
344 | DEPRECATEDIN_3_0(const char * OSSL_STORE_LOADER_get0_scheme | |
345 | (const OSSL_STORE_LOADER *loader)) | |
346 | ||
347 | DEPRECATEDIN_3_0(int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader)) | |
348 | DEPRECATEDIN_3_0(OSSL_STORE_LOADER *OSSL_STORE_unregister_loader | |
349 | (const char *scheme)) | |
71a5516d | 350 | |
f91ded1f RL |
351 | /*- |
352 | * Functions to list STORE loaders | |
353 | * ------------------------------- | |
354 | */ | |
a1447076 RL |
355 | DEPRECATEDIN_3_0(int OSSL_STORE_do_all_loaders |
356 | (void (*do_function)(const OSSL_STORE_LOADER *loader, | |
357 | void *do_arg), | |
358 | void *do_arg)) | |
f91ded1f | 359 | |
71a5516d RL |
360 | # ifdef __cplusplus |
361 | } | |
362 | # endif | |
363 | #endif |