Make it possible to tell the file loader to use secure memory
[openssl.git] / doc / man3 / OSSL_STORE_open.pod
index b63156a..14ce9d2 100644 (file)
@@ -58,8 +58,23 @@ OSSL_STORE_load() to manipulate or drop the value to be returned.
 
 OSSL_STORE_ctrl() takes a B<OSSL_STORE_CTX>, and command number B<cmd> and
 more arguments not specified here.
-The available command numbers and arguments they each take depends on
-the loader that's used and is documented together with that loader.
+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.
+
+There are also global controls available:
+
+=over 4
+
+=item B<OSSL_STORE_C_USE_SECMEM>
+
+Controls if the loader should attempt to use secure memory for any
+allocated B<OSSL_STORE_INFO> and its contents.
+This control expects one argument, a pointer to an B<int> that is expected to
+have the value 1 (yes) or 0 (no).
+Any other value is an error.
+
+=back
 
 OSSL_STORE_load() takes a B<OSSL_STORE_CTX>, tries to load the next available
 object and return it wrapped with  B<OSSL_STORE_INFO>.
@@ -69,6 +84,8 @@ of data.
 
 OSSL_STORE_error() takes a B<OSSL_STORE_CTX> and checks if an error occured 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.
 
 OSSL_STORE_close() takes a B<OSSL_STORE_CTX>, closes the channel that was opened
 by OSSL_STORE_open() and frees all other information that was stored in the
@@ -105,8 +122,13 @@ should be taken or not.
 
 =head1 RETURN VALUES
 
-OSSL_STORE_open() and OSSL_STORE_load() return a pointer to a B<OSSL_STORE_CTX>
-on success, or B<NULL> on failure.
+OSSL_STORE_open() returns a pointer to a B<OSSL_STORE_CTX> on success, or
+B<NULL> on failure.
+
+OSSL_STORE_load() returns a pointer to a B<OSSL_STORE_INFO> on success, or
+B<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 B<NULL>.
 
 OSSL_STORE_eof() returns 1 if the end of data has been reached, otherwise
 0.