]>
Commit | Line | Data |
---|---|---|
e2e603fe RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | OSSL_STORE_CTX, OSSL_STORE_post_process_info_fn, OSSL_STORE_open, | |
6 | OSSL_STORE_ctrl, OSSL_STORE_load, OSSL_STORE_eof, OSSL_STORE_error, | |
7 | OSSL_STORE_close - Types and functions to read objects from a URI | |
8 | ||
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/store.h> | |
dae2218d | 12 | |
e2e603fe RL |
13 | typedef struct ossl_store_ctx_st OSSL_STORE_CTX; |
14 | ||
15 | typedef OSSL_STORE_INFO *(*OSSL_STORE_post_process_info_fn)(OSSL_STORE_INFO *, | |
16 | void *); | |
17 | ||
18 | OSSL_STORE_CTX *OSSL_STORE_open(const char *uri, const UI_METHOD *ui_method, | |
19 | void *ui_data, | |
20 | OSSL_STORE_post_process_info_fn post_process, | |
21 | void *post_process_data); | |
22 | int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, ... /* args */); | |
23 | OSSL_STORE_INFO *OSSL_STORE_load(OSSL_STORE_CTX *ctx); | |
24 | int OSSL_STORE_eof(OSSL_STORE_CTX *ctx); | |
25 | int OSSL_STORE_error(OSSL_STORE_CTX *ctx); | |
26 | int OSSL_STORE_close(OSSL_STORE_CTX *ctx); | |
27 | ||
28 | =head1 DESCRIPTION | |
29 | ||
30 | These functions help the application to fetch supported objects (see | |
31 | L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS> for information on which those are) | |
32 | from a given URI (see L</SUPPORTED SCHEMES> for more information on | |
33 | the supported URI schemes). | |
34 | The general method to do so is to "open" the URI using OSSL_STORE_open(), | |
35 | read each available and supported object using OSSL_STORE_load() as long as | |
36 | OSSL_STORE_eof() hasn't been reached, and finish it off with OSSL_STORE_close(). | |
37 | ||
38 | The retrieved information is stored in a B<OSSL_STORE_INFO>, which is further | |
39 | described in L<OSSL_STORE_INFO(3)>. | |
40 | ||
41 | =head2 Types | |
42 | ||
43 | B<OSSL_STORE_CTX> is a context variable that holds all the internal | |
44 | information for OSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof() and | |
45 | OSSL_STORE_close() to work together. | |
46 | ||
47 | =head2 Functions | |
48 | ||
49 | OSSL_STORE_open() takes a uri or path B<uri>, password UI method | |
50 | B<ui_method> with associated data B<ui_data>, and post processing | |
51 | callback B<post_process> with associated data B<post_process_data>, | |
52 | opens a channel to the data located at that URI and returns a | |
53 | B<OSSL_STORE_CTX> with all necessary internal information. | |
54 | The given B<ui_method> and B<ui_data_data> will be reused by all | |
55 | functions that use B<OSSL_STORE_CTX> when interaction is needed. | |
56 | The given B<post_process> and B<post_process_data> will be reused by | |
57 | OSSL_STORE_load() to manipulate or drop the value to be returned. | |
33024295 RL |
58 | The B<post_process> function drops values by returning B<NULL>, which |
59 | will cause OSSL_STORE_load() to start its process over with loading | |
60 | the next object, until B<post_process> returns something other than | |
61 | B<NULL>, or the end of data is reached as indicated by OSSL_STORE_eof(). | |
e2e603fe RL |
62 | |
63 | OSSL_STORE_ctrl() takes a B<OSSL_STORE_CTX>, and command number B<cmd> and | |
64 | more arguments not specified here. | |
7852f588 RL |
65 | The available loader specific command numbers and arguments they each |
66 | take depends on the loader that's used and is documented together with | |
67 | that loader. | |
68 | ||
69 | There are also global controls available: | |
70 | ||
71 | =over 4 | |
72 | ||
73 | =item B<OSSL_STORE_C_USE_SECMEM> | |
74 | ||
75 | Controls if the loader should attempt to use secure memory for any | |
76 | allocated B<OSSL_STORE_INFO> and its contents. | |
77 | This control expects one argument, a pointer to an B<int> that is expected to | |
78 | have the value 1 (yes) or 0 (no). | |
79 | Any other value is an error. | |
80 | ||
81 | =back | |
e2e603fe RL |
82 | |
83 | OSSL_STORE_load() takes a B<OSSL_STORE_CTX>, tries to load the next available | |
84 | object and return it wrapped with B<OSSL_STORE_INFO>. | |
85 | ||
86 | OSSL_STORE_eof() takes a B<OSSL_STORE_CTX> and checks if we've reached the end | |
87 | of data. | |
88 | ||
89 | OSSL_STORE_error() takes a B<OSSL_STORE_CTX> and checks if an error occured in | |
90 | the last OSSL_STORE_load() call. | |
6fc1d33c RL |
91 | Note that it may still be meaningful to try and load more objects, unless |
92 | OSSL_STORE_eof() shows that the end of data has been reached. | |
e2e603fe RL |
93 | |
94 | OSSL_STORE_close() takes a B<OSSL_STORE_CTX>, closes the channel that was opened | |
95 | by OSSL_STORE_open() and frees all other information that was stored in the | |
96 | B<OSSL_STORE_CTX>, as well as the B<OSSL_STORE_CTX> itself. | |
97 | ||
98 | =head1 SUPPORTED SCHEMES | |
99 | ||
100 | The basic supported scheme is B<file:>. | |
101 | Any other scheme can be added dynamically, using | |
102 | OSSL_STORE_register_loader(). | |
103 | ||
104 | =head1 NOTES | |
105 | ||
1fb2993d BK |
106 | A string without a scheme prefix (that is, a non-URI string) is |
107 | implicitly interpreted as using the F<file:> scheme. | |
108 | ||
109 | There are some tools that can be used together with | |
e2e603fe RL |
110 | OSSL_STORE_open() to determine if any failure is caused by an unparsable |
111 | URI, or if it's a different error (such as memory allocation | |
112 | failures); if the URI was parsable but the scheme unregistered, the | |
113 | top error will have the reason C<OSSL_STORE_R_UNREGISTERED_SCHEME>. | |
e2e603fe RL |
114 | |
115 | =head1 RETURN VALUES | |
116 | ||
6fc1d33c RL |
117 | OSSL_STORE_open() returns a pointer to a B<OSSL_STORE_CTX> on success, or |
118 | B<NULL> on failure. | |
119 | ||
120 | OSSL_STORE_load() returns a pointer to a B<OSSL_STORE_INFO> on success, or | |
121 | B<NULL> on error or when end of data is reached. | |
122 | Use OSSL_STORE_error() and OSSL_STORE_eof() to determine the meaning of a | |
123 | returned B<NULL>. | |
e2e603fe RL |
124 | |
125 | OSSL_STORE_eof() returns 1 if the end of data has been reached, otherwise | |
126 | 0. | |
127 | ||
128 | OSSL_STORE_error() returns 1 if an error occured in a OSSL_STORE_load() call, | |
129 | otherwise 0. | |
130 | ||
131 | OSSL_STORE_ctrl() and OSSL_STORE_close() returns 1 on success, or 0 on failure. | |
132 | ||
133 | =head1 SEE ALSO | |
134 | ||
135 | L<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_register_loader(3)> | |
136 | ||
137 | =head1 HISTORY | |
138 | ||
139 | OSSL_STORE_CTX(), OSSL_STORE_post_process_info_fn(), OSSL_STORE_open(), | |
140 | OSSL_STORE_ctrl(), OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close() | |
141 | were added to OpenSSL 1.1.1. | |
142 | ||
143 | =head1 COPYRIGHT | |
144 | ||
145 | Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. | |
146 | ||
147 | Licensed under the OpenSSL license (the "License"). You may not use | |
148 | this file except in compliance with the License. You can obtain a copy | |
149 | in the file LICENSE in the source distribution or at | |
150 | L<https://www.openssl.org/source/license.html>. | |
151 | ||
152 | =cut |