xref: /openssl/doc/man3/OSSL_STORE_open.pod (revision 3dbf8243) 
1=pod
2
3=head1 NAME
4
5OSSL_STORE_CTX, OSSL_STORE_post_process_info_fn,
6OSSL_STORE_open, OSSL_STORE_open_ex,
7OSSL_STORE_ctrl, OSSL_STORE_load, OSSL_STORE_eof,
8OSSL_STORE_error, OSSL_STORE_close
9- Types and functions to read objects from a URI
10
11=head1 SYNOPSIS
12
13 #include <openssl/store.h>
14
15 typedef struct ossl_store_ctx_st OSSL_STORE_CTX;
16
17 typedef OSSL_STORE_INFO *(*OSSL_STORE_post_process_info_fn)(OSSL_STORE_INFO *,
18                                                             void *);
19
20 OSSL_STORE_CTX *OSSL_STORE_open(const char *uri, const UI_METHOD *ui_method,
21                                 void *ui_data,
22                                 OSSL_STORE_post_process_info_fn post_process,
23                                 void *post_process_data);
24 OSSL_STORE_CTX *
25 OSSL_STORE_open_ex(const char *uri, OSSL_LIB_CTX *libctx, const char *propq,
26                    const UI_METHOD *ui_method, void *ui_data,
27                    const OSSL_PARAM params[],
28                    OSSL_STORE_post_process_info_fn post_process,
29                    void *post_process_data);
30
31 OSSL_STORE_INFO *OSSL_STORE_load(OSSL_STORE_CTX *ctx);
32 int OSSL_STORE_eof(OSSL_STORE_CTX *ctx);
33 int OSSL_STORE_error(OSSL_STORE_CTX *ctx);
34 int OSSL_STORE_close(OSSL_STORE_CTX *ctx);
35
36The following function has been deprecated since OpenSSL 3.0, and can be
37hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
38see L<openssl_user_macros(7)>:
39
40 int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, ... /* args */);
41
42=head1 DESCRIPTION
43
44These functions help the application to fetch supported objects (see
45L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS> for information on which those are)
46from a given URI.
47The general method to do so is to "open" the URI using OSSL_STORE_open(),
48read each available and supported object using OSSL_STORE_load() as long as
49OSSL_STORE_eof() hasn't been reached, and finish it off with OSSL_STORE_close().
50
51The retrieved information is stored in a B<OSSL_STORE_INFO>, which is further
52described in L<OSSL_STORE_INFO(3)>.
53
54=head2 Types
55
56B<OSSL_STORE_CTX> is a context variable that holds all the internal
57information for OSSL_STORE_open(), OSSL_STORE_open_ex(),
58OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close() to work
59together.
60
61=head2 Functions
62
63OSSL_STORE_open_ex() takes a uri or path I<uri>, password UI method
64I<ui_method> with associated data I<ui_data>, and post processing
65callback I<post_process> with associated data I<post_process_data>,
66a library context I<libctx> with an associated property query I<propq>,
67and opens a channel to the data located at the URI and returns a
68B<OSSL_STORE_CTX> with all necessary internal information.
69The given I<ui_method> and I<ui_data> will be reused by all
70functions that use B<OSSL_STORE_CTX> when interaction is needed,
71for instance to provide a password.
72The auxiliary B<OSSL_PARAM> parameters in I<params> can be set to further
73modify the store operation.
74The given I<post_process> and I<post_process_data> will be reused by
75OSSL_STORE_load() to manipulate or drop the value to be returned.
76The I<post_process> function drops values by returning NULL, which
77will cause OSSL_STORE_load() to start its process over with loading
78the next object, until I<post_process> returns something other than
79NULL, or the end of data is reached as indicated by OSSL_STORE_eof().
80
81OSSL_STORE_open() is similar to OSSL_STORE_open_ex() but uses NULL for
82the I<params>, the library context I<libctx> and property query I<propq>.
83
84OSSL_STORE_ctrl() takes a B<OSSL_STORE_CTX>, and command number I<cmd> and
85more arguments not specified here.
86The available loader specific command numbers and arguments they each
87take depends on the loader that's used and is documented together with
88that loader.
89
90There are also global controls available:
91
92=over 4
93
94=item B<OSSL_STORE_C_USE_SECMEM>
95
96Controls if the loader should attempt to use secure memory for any
97allocated B<OSSL_STORE_INFO> and its contents.
98This control expects one argument, a pointer to an I<int> that is expected to
99have the value 1 (yes) or 0 (no).
100Any other value is an error.
101
102=back
103
104OSSL_STORE_load() takes a B<OSSL_STORE_CTX> and tries to load the next
105available object and return it wrapped with B<OSSL_STORE_INFO>.
106
107OSSL_STORE_eof() takes a B<OSSL_STORE_CTX> and checks if we've reached the end
108of data.
109
110OSSL_STORE_error() takes a B<OSSL_STORE_CTX> and checks if an error occurred in
111the last OSSL_STORE_load() call.
112Note that it may still be meaningful to try and load more objects, unless
113OSSL_STORE_eof() shows that the end of data has been reached.
114
115OSSL_STORE_close() takes a B<OSSL_STORE_CTX>, closes the channel that was opened
116by OSSL_STORE_open() and frees all other information that was stored in the
117B<OSSL_STORE_CTX>, as well as the B<OSSL_STORE_CTX> itself.
118If I<ctx> is NULL it does nothing.
119
120=head1 NOTES
121
122A string without a scheme prefix (that is, a non-URI string) is
123implicitly interpreted as using the F<file:> scheme.
124
125There are some tools that can be used together with
126OSSL_STORE_open() to determine if any failure is caused by an unparsable
127URI, or if it's a different error (such as memory allocation
128failures); if the URI was parsable but the scheme unregistered, the
129top error will have the reason C<OSSL_STORE_R_UNREGISTERED_SCHEME>.
130
131These functions make no direct assumption regarding the pass phrase received
132from the password callback.
133The loaders may make assumptions, however.
134For example, the B<file:> scheme loader inherits the assumptions made by
135OpenSSL functionality that handles the different file types; this is mostly
136relevant for PKCS#12 objects.
137See L<passphrase-encoding(7)> for further information.
138
139=head1 RETURN VALUES
140
141OSSL_STORE_open() returns a pointer to a B<OSSL_STORE_CTX> on success, or
142NULL on failure.
143
144OSSL_STORE_load() returns a pointer to a B<OSSL_STORE_INFO> on success, or NULL
145on error or when end of data is reached.
146Use OSSL_STORE_error() and OSSL_STORE_eof() to determine the meaning of a
147returned NULL.
148
149OSSL_STORE_eof() returns 1 if the end of data has been reached
150or an error occurred, 0 otherwise.
151
152OSSL_STORE_error() returns 1 if an error occurred in an OSSL_STORE_load() call,
153otherwise 0.
154
155OSSL_STORE_ctrl() and OSSL_STORE_close() returns 1 on success, or 0 on failure.
156
157=head1 SEE ALSO
158
159L<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_register_loader(3)>,
160L<passphrase-encoding(7)>
161
162=head1 HISTORY
163
164OSSL_STORE_open_ex() was added in OpenSSL 3.0.
165
166B<OSSL_STORE_CTX>, OSSL_STORE_post_process_info_fn(), OSSL_STORE_open(),
167OSSL_STORE_ctrl(), OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close()
168were added in OpenSSL 1.1.1.
169
170Handling of NULL I<ctx> argument for OSSL_STORE_close()
171was introduced in OpenSSL 1.1.1h.
172
173OSSL_STORE_open_ex() was added in OpenSSL 3.0.
174
175OSSL_STORE_ctrl() and OSSL_STORE_vctrl() were deprecated in OpenSSL 3.0.
176
177=head1 COPYRIGHT
178
179Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved.
180
181Licensed under the Apache License 2.0 (the "License").  You may not use
182this file except in compliance with the License.  You can obtain a copy
183in the file LICENSE in the source distribution or at
184L<https://www.openssl.org/source/license.html>.
185
186=cut
187