1OSSL_STORE_OPEN(3)                  OpenSSL                 OSSL_STORE_OPEN(3)
2
3
4

NAME

6       OSSL_STORE_CTX, OSSL_STORE_post_process_info_fn, OSSL_STORE_open,
7       OSSL_STORE_ctrl, OSSL_STORE_load, OSSL_STORE_eof, OSSL_STORE_error,
8       OSSL_STORE_close - Types and functions to read objects from a URI
9

SYNOPSIS

11        #include <openssl/store.h>
12
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

DESCRIPTION

29       These functions help the application to fetch supported objects (see
30       "SUPPORTED OBJECTS" in OSSL_STORE_INFO(3) for information on which
31       those are) from a given URI (see "SUPPORTED SCHEMES" for more
32       information on the supported URI schemes).  The general method to do so
33       is to "open" the URI using OSSL_STORE_open(), read each available and
34       supported object using OSSL_STORE_load() as long as OSSL_STORE_eof()
35       hasn't been reached, and finish it off with OSSL_STORE_close().
36
37       The retrieved information is stored in a OSSL_STORE_INFO, which is
38       further described in OSSL_STORE_INFO(3).
39
40   Types
41       OSSL_STORE_CTX is a context variable that holds all the internal
42       information for OSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof()
43       and OSSL_STORE_close() to work together.
44
45   Functions
46       OSSL_STORE_open() takes a uri or path uri, password UI method ui_method
47       with associated data ui_data, and post processing callback post_process
48       with associated data post_process_data, opens a channel to the data
49       located at that URI and returns a OSSL_STORE_CTX with all necessary
50       internal information.  The given ui_method and ui_data_data will be
51       reused by all functions that use OSSL_STORE_CTX when interaction is
52       needed.  The given post_process and post_process_data will be reused by
53       OSSL_STORE_load() to manipulate or drop the value to be returned.  The
54       post_process function drops values by returning NULL, which will cause
55       OSSL_STORE_load() to start its process over with loading the next
56       object, until post_process returns something other than NULL, or the
57       end of data is reached as indicated by OSSL_STORE_eof().
58
59       OSSL_STORE_ctrl() takes a OSSL_STORE_CTX, and command number cmd and
60       more arguments not specified here.  The available loader specific
61       command numbers and arguments they each take depends on the loader
62       that's used and is documented together with that loader.
63
64       There are also global controls available:
65
66       OSSL_STORE_C_USE_SECMEM
67           Controls if the loader should attempt to use secure memory for any
68           allocated OSSL_STORE_INFO and its contents.  This control expects
69           one argument, a pointer to an int that is expected to have the
70           value 1 (yes) or 0 (no).  Any other value is an error.
71
72       OSSL_STORE_load() takes a OSSL_STORE_CTX, tries to load the next
73       available object and return it wrapped with  OSSL_STORE_INFO.
74
75       OSSL_STORE_eof() takes a OSSL_STORE_CTX and checks if we've reached the
76       end of data.
77
78       OSSL_STORE_error() takes a OSSL_STORE_CTX and checks if an error
79       occurred in the last OSSL_STORE_load() call.  Note that it may still be
80       meaningful to try and load more objects, unless OSSL_STORE_eof() shows
81       that the end of data has been reached.
82
83       OSSL_STORE_close() takes a OSSL_STORE_CTX, closes the channel that was
84       opened by OSSL_STORE_open() and frees all other information that was
85       stored in the OSSL_STORE_CTX, as well as the OSSL_STORE_CTX itself.
86

SUPPORTED SCHEMES

88       The basic supported scheme is file:.  Any other scheme can be added
89       dynamically, using OSSL_STORE_register_loader().
90

NOTES

92       A string without a scheme prefix (that is, a non-URI string) is
93       implicitly interpreted as using the file: scheme.
94
95       There are some tools that can be used together with OSSL_STORE_open()
96       to determine if any failure is caused by an unparsable URI, or if it's
97       a different error (such as memory allocation failures); if the URI was
98       parsable but the scheme unregistered, the top error will have the
99       reason "OSSL_STORE_R_UNREGISTERED_SCHEME".
100
101       These functions make no direct assumption regarding the pass phrase
102       received from the password callback.  The loaders may make assumptions,
103       however.  For example, the file: scheme loader inherits the assumptions
104       made by OpenSSL functionality that handles the different file types;
105       this is mostly relevant for PKCS#12 objects.  See
106       passphrase-encoding(7) for further information.
107

RETURN VALUES

109       OSSL_STORE_open() returns a pointer to a OSSL_STORE_CTX on success, or
110       NULL on failure.
111
112       OSSL_STORE_load() returns a pointer to a OSSL_STORE_INFO on success, or
113       NULL on error or when end of data is reached.  Use OSSL_STORE_error()
114       and OSSL_STORE_eof() to determine the meaning of a returned NULL.
115
116       OSSL_STORE_eof() returns 1 if the end of data has been reached,
117       otherwise 0.
118
119       OSSL_STORE_error() returns 1 if an error occurred in an
120       OSSL_STORE_load() call, otherwise 0.
121
122       OSSL_STORE_ctrl() and OSSL_STORE_close() returns 1 on success, or 0 on
123       failure.
124

SEE ALSO

126       ossl_store(7), OSSL_STORE_INFO(3), OSSL_STORE_register_loader(3),
127       passphrase-encoding(7)
128

HISTORY

130       OSSL_STORE_CTX(), OSSL_STORE_post_process_info_fn(), OSSL_STORE_open(),
131       OSSL_STORE_ctrl(), OSSL_STORE_load(), OSSL_STORE_eof() and
132       OSSL_STORE_close() were added in OpenSSL 1.1.1.
133
135       Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
136
137       Licensed under the OpenSSL license (the "License").  You may not use
138       this file except in compliance with the License.  You can obtain a copy
139       in the file LICENSE in the source distribution or at
140       <https://www.openssl.org/source/license.html>.
141
142
143
1441.1.1d                            2019-10-03                OSSL_STORE_OPEN(3)
Impressum