154 lines
9.4 KiB
HTML
154 lines
9.4 KiB
HTML
|
<?xml version="1.0" ?>
|
||
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
|
<head>
|
||
|
|
<title>OSSL_STORE_open</title>
|
||
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||
|
|
<link rev="made" href="mailto:" />
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<ul id="index">
|
||
|
|
<li><a href="#NAME">NAME</a></li>
|
||
|
|
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
|
||
|
|
<li><a href="#DESCRIPTION">DESCRIPTION</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href="#Types">Types</a></li>
|
||
|
|
<li><a href="#Functions">Functions</a></li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
<li><a href="#NOTES">NOTES</a></li>
|
||
|
|
<li><a href="#RETURN-VALUES">RETURN VALUES</a></li>
|
||
|
|
<li><a href="#SEE-ALSO">SEE ALSO</a></li>
|
||
|
|
<li><a href="#HISTORY">HISTORY</a></li>
|
||
|
|
<li><a href="#COPYRIGHT">COPYRIGHT</a></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h1 id="NAME">NAME</h1>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_CTX, OSSL_STORE_post_process_info_fn, OSSL_STORE_open, OSSL_STORE_open_ex, OSSL_STORE_ctrl, OSSL_STORE_load, OSSL_STORE_eof, OSSL_STORE_delete, OSSL_STORE_error, OSSL_STORE_close - Types and functions to read objects from a URI</p>
|
||
|
|
|
||
|
|
<h1 id="SYNOPSIS">SYNOPSIS</h1>
|
||
|
|
|
||
|
|
<pre><code> #include <openssl/store.h>
|
||
|
|
|
||
|
|
typedef struct ossl_store_ctx_st OSSL_STORE_CTX;
|
||
|
|
|
||
|
|
typedef OSSL_STORE_INFO *(*OSSL_STORE_post_process_info_fn)(OSSL_STORE_INFO *,
|
||
|
|
void *);
|
||
|
|
|
||
|
|
OSSL_STORE_CTX *OSSL_STORE_open(const char *uri, const UI_METHOD *ui_method,
|
||
|
|
void *ui_data,
|
||
|
|
OSSL_STORE_post_process_info_fn post_process,
|
||
|
|
void *post_process_data);
|
||
|
|
OSSL_STORE_CTX *
|
||
|
|
OSSL_STORE_open_ex(const char *uri, OSSL_LIB_CTX *libctx, const char *propq,
|
||
|
|
const UI_METHOD *ui_method, void *ui_data,
|
||
|
|
const OSSL_PARAM params[],
|
||
|
|
OSSL_STORE_post_process_info_fn post_process,
|
||
|
|
void *post_process_data);
|
||
|
|
|
||
|
|
OSSL_STORE_INFO *OSSL_STORE_load(OSSL_STORE_CTX *ctx);
|
||
|
|
int OSSL_STORE_eof(OSSL_STORE_CTX *ctx);
|
||
|
|
int OSSL_STORE_delete(const char *uri, OSSL_LIB_CTX *libctx, const char *propq,
|
||
|
|
const UI_METHOD *ui_method, void *ui_data,
|
||
|
|
const OSSL_PARAM params[]);
|
||
|
|
int OSSL_STORE_error(OSSL_STORE_CTX *ctx);
|
||
|
|
int OSSL_STORE_close(OSSL_STORE_CTX *ctx);</code></pre>
|
||
|
|
|
||
|
|
<p>The following function has been deprecated since OpenSSL 3.0, and can be hidden entirely by defining <b>OPENSSL_API_COMPAT</b> with a suitable version value, see <a href="../man7/openssl_user_macros.html">openssl_user_macros(7)</a>:</p>
|
||
|
|
|
||
|
|
<pre><code> int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, ... /* args */);</code></pre>
|
||
|
|
|
||
|
|
<h1 id="DESCRIPTION">DESCRIPTION</h1>
|
||
|
|
|
||
|
|
<p>These functions help the application to fetch supported objects (see <a href="../man3/OSSL_STORE_INFO.html">"SUPPORTED OBJECTS" in OSSL_STORE_INFO(3)</a> for information on which those are) from a given URI. The general method to do so is to "open" the URI using OSSL_STORE_open(), read each available and supported object using OSSL_STORE_load() as long as OSSL_STORE_eof() hasn't been reached, and finish it off with OSSL_STORE_close().</p>
|
||
|
|
|
||
|
|
<p>The retrieved information is stored in a <b>OSSL_STORE_INFO</b>, which is further described in <a href="../man3/OSSL_STORE_INFO.html">OSSL_STORE_INFO(3)</a>.</p>
|
||
|
|
|
||
|
|
<h2 id="Types">Types</h2>
|
||
|
|
|
||
|
|
<p><b>OSSL_STORE_CTX</b> is a context variable that holds all the internal information for OSSL_STORE_open(), OSSL_STORE_open_ex(), OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close() to work together.</p>
|
||
|
|
|
||
|
|
<h2 id="Functions">Functions</h2>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_open_ex() takes a uri or path <i>uri</i>, password UI method <i>ui_method</i> with associated data <i>ui_data</i>, and post processing callback <i>post_process</i> with associated data <i>post_process_data</i>, a library context <i>libctx</i> with an associated property query <i>propq</i>, and opens a channel to the data located at the URI and returns a <b>OSSL_STORE_CTX</b> with all necessary internal information. The given <i>ui_method</i> and <i>ui_data</i> will be reused by all functions that use <b>OSSL_STORE_CTX</b> when interaction is needed, for instance to provide a password. The auxiliary <a href="../man3/OSSL_PARAM.html">OSSL_PARAM(3)</a> parameters in <i>params</i> can be set to further modify the store operation. The given <i>post_process</i> and <i>post_process_data</i> will be reused by OSSL_STORE_load() to manipulate or drop the value to be returned. The <i>post_process</i> function drops values by returning NULL, which will cause OSSL_STORE_load() to start its process over with loading the next object, until <i>post_process</i> returns something other than NULL, or the end of data is reached as indicated by OSSL_STORE_eof().</p>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_open() is similar to OSSL_STORE_open_ex() but uses NULL for the <i>params</i>, the library context <i>libctx</i> and property query <i>propq</i>.</p>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_ctrl() takes a <b>OSSL_STORE_CTX</b>, and command number <i>cmd</i> and more arguments not specified here. The available loader specific command numbers and arguments they each take depends on the loader that's used and is documented together with that loader.</p>
|
||
|
|
|
||
|
|
<p>There are also global controls available:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
|
||
|
|
<dt id="OSSL_STORE_C_USE_SECMEM"><b>OSSL_STORE_C_USE_SECMEM</b></dt>
|
||
|
|
<dd>
|
||
|
|
|
||
|
|
<p>Controls if the loader should attempt to use secure memory for any allocated <b>OSSL_STORE_INFO</b> and its contents. This control expects one argument, a pointer to an <i>int</i> that is expected to have the value 1 (yes) or 0 (no). Any other value is an error.</p>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_load() takes a <b>OSSL_STORE_CTX</b> and tries to load the next available object and return it wrapped with <b>OSSL_STORE_INFO</b>.</p>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_delete() deletes the object identified by <i>uri</i>.</p>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_eof() takes a <b>OSSL_STORE_CTX</b> and checks if we've reached the end of data.</p>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_error() takes a <b>OSSL_STORE_CTX</b> and checks if an error occurred in the last OSSL_STORE_load() call. Note that it may still be meaningful to try and load more objects, unless OSSL_STORE_eof() shows that the end of data has been reached.</p>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_close() takes a <b>OSSL_STORE_CTX</b>, closes the channel that was opened by OSSL_STORE_open() and frees all other information that was stored in the <b>OSSL_STORE_CTX</b>, as well as the <b>OSSL_STORE_CTX</b> itself. If <i>ctx</i> is NULL it does nothing.</p>
|
||
|
|
|
||
|
|
<h1 id="NOTES">NOTES</h1>
|
||
|
|
|
||
|
|
<p>A string without a scheme prefix (that is, a non-URI string) is implicitly interpreted as using the <i>file:</i> scheme.</p>
|
||
|
|
|
||
|
|
<p>There are some tools that can be used together with OSSL_STORE_open() to determine if any failure is caused by an unparsable URI, or if it's a different error (such as memory allocation failures); if the URI was parsable but the scheme unregistered, the top error will have the reason <code>OSSL_STORE_R_UNREGISTERED_SCHEME</code>.</p>
|
||
|
|
|
||
|
|
<p>These functions make no direct assumption regarding the pass phrase received from the password callback. The loaders may make assumptions, however. For example, the <b>file:</b> scheme loader inherits the assumptions made by OpenSSL functionality that handles the different file types; this is mostly relevant for PKCS#12 objects. See <a href="../man7/passphrase-encoding.html">passphrase-encoding(7)</a> for further information.</p>
|
||
|
|
|
||
|
|
<h1 id="RETURN-VALUES">RETURN VALUES</h1>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_open() returns a pointer to a <b>OSSL_STORE_CTX</b> on success, or NULL on failure.</p>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_load() returns a pointer to a <b>OSSL_STORE_INFO</b> on success, or NULL on error or when end of data is reached. Use OSSL_STORE_error() and OSSL_STORE_eof() to determine the meaning of a returned NULL.</p>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_eof() returns 1 if the end of data has been reached or an error occurred, 0 otherwise.</p>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_error() returns 1 if an error occurred in an OSSL_STORE_load() call, otherwise 0.</p>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_delete(), OSSL_STORE_ctrl() and OSSL_STORE_close() return 1 on success, or 0 on failure.</p>
|
||
|
|
|
||
|
|
<h1 id="SEE-ALSO">SEE ALSO</h1>
|
||
|
|
|
||
|
|
<p><a href="../man7/ossl_store.html">ossl_store(7)</a>, <a href="../man3/OSSL_STORE_INFO.html">OSSL_STORE_INFO(3)</a>, <a href="../man3/OSSL_STORE_register_loader.html">OSSL_STORE_register_loader(3)</a>, <a href="../man7/passphrase-encoding.html">passphrase-encoding(7)</a></p>
|
||
|
|
|
||
|
|
<h1 id="HISTORY">HISTORY</h1>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_delete() was added in OpenSSL 3.2.</p>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_open_ex() was added in OpenSSL 3.0.</p>
|
||
|
|
|
||
|
|
<p><b>OSSL_STORE_CTX</b>, OSSL_STORE_post_process_info_fn(), OSSL_STORE_open(), OSSL_STORE_ctrl(), OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close() were added in OpenSSL 1.1.1.</p>
|
||
|
|
|
||
|
|
<p>Handling of NULL <i>ctx</i> argument for OSSL_STORE_close() was introduced in OpenSSL 1.1.1h.</p>
|
||
|
|
|
||
|
|
<p>OSSL_STORE_ctrl() and OSSL_STORE_vctrl() were deprecated in OpenSSL 3.0.</p>
|
||
|
|
|
||
|
|
<h1 id="COPYRIGHT">COPYRIGHT</h1>
|
||
|
|
|
||
|
|
<p>Copyright 2016-2023 The OpenSSL Project Authors. All Rights Reserved.</p>
|
||
|
|
|
||
|
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
|
||
|
|
</html>
|
||
|
|
|
||
|
|
|