Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OSSL_STORE_LOADER(3)		    OpenSSL		  OSSL_STORE_LOADER(3)

NAME
       OSSL_STORE_LOADER, OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new,
       OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme,
       OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_ctrl,
       OSSL_STORE_LOADER_set_expect, OSSL_STORE_LOADER_set_find,
       OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof,
       OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close,
       OSSL_STORE_LOADER_free, OSSL_STORE_register_loader,
       OSSL_STORE_unregister_loader, OSSL_STORE_open_fn, OSSL_STORE_ctrl_fn,
       OSSL_STORE_expect_fn, OSSL_STORE_find_fn, OSSL_STORE_load_fn,
       OSSL_STORE_eof_fn, OSSL_STORE_error_fn, OSSL_STORE_close_fn - Types and
       functions to manipulate,	register and unregister	STORE loaders for
       different URI schemes

SYNOPSIS
	#include <openssl/store.h>

	typedef	struct ossl_store_loader_st OSSL_STORE_LOADER;

	OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE	*e, const char *scheme);
	const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER
						    *store_loader);
	const char *OSSL_STORE_LOADER_get0_scheme(const	OSSL_STORE_LOADER
						  *store_loader);

	/* struct ossl_store_loader_ctx_st is defined differently by each loader */
	typedef	struct ossl_store_loader_ctx_st	OSSL_STORE_LOADER_CTX;

	typedef	OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)(const char	*uri,
							     const UI_METHOD *ui_method,
							     void *ui_data);
	int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader,
				       OSSL_STORE_open_fn store_open_function);
	typedef	int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX	*ctx, int cmd,
					  va_list args);
	int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader,
				       OSSL_STORE_ctrl_fn store_ctrl_function);
	typedef	int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx,	int expected);
	int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader,
					 OSSL_STORE_expect_fn expect_function);
	typedef	int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX	*ctx,
					  OSSL_STORE_SEARCH *criteria);
	int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader,
				       OSSL_STORE_find_fn find_function);
	typedef	OSSL_STORE_INFO	*(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,
						       UI_METHOD *ui_method,
						       void *ui_data);
	int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *store_loader,
				       OSSL_STORE_load_fn store_load_function);
	typedef	int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx);
	int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER	*store_loader,
				      OSSL_STORE_eof_fn	store_eof_function);
	typedef	int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx);
	int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *store_loader,
					OSSL_STORE_error_fn store_error_function);
	typedef	int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx);
	int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader,
					OSSL_STORE_close_fn store_close_function);
	void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *store_loader);

	int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader);
	OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme);

DESCRIPTION
       These functions help applications and engines to	create loaders for
       schemes they support.

   Types
       OSSL_STORE_LOADER is the	type to	hold a loader.	It contains a scheme
       and the functions needed	to implement OSSL_STORE_open(),
       OSSL_STORE_load(), OSSL_STORE_eof(), OSSL_STORE_error() and
       OSSL_STORE_close() for this scheme.

       OSSL_STORE_LOADER_CTX is	a type template, to be defined by each loader
       using struct ossl_store_loader_ctx_st { ... }.

       OSSL_STORE_open_fn, OSSL_STORE_ctrl_fn, OSSL_STORE_expect_fn,
       OSSL_STORE_find_fn, OSSL_STORE_load_fn, OSSL_STORE_eof_fn, and
       OSSL_STORE_close_fn are the function pointer types used within a	STORE
       loader.	The functions pointed at define	the functionality of the given
       loader.

       OSSL_STORE_open_fn
	   This	function takes a URI and is expected to	interpret it in	the
	   best	manner possible	according to the scheme	the loader implements,
	   it also takes a UI_METHOD and associated data, to be	used any time
	   something needs to be prompted for.	Furthermore, this function is
	   expected to initialize what needs to	be initialized,	to create a
	   privata data	store (OSSL_STORE_LOADER_CTX, see above), and to
	   return it.  If something goes wrong,	this function is expected to
	   return NULL.

       OSSL_STORE_ctrl_fn
	   This	function takes a OSSL_STORE_LOADER_CTX pointer,	a command
	   number cmd and a va_list args and is	used to	manipulate loader
	   specific parameters.

	   Loader specific command numbers must	begin at
	   OSSL_STORE_C_CUSTOM_START.  Any number below	that is	reserved for
	   future globally known command numbers.

	   This	function is expected to	return 1 on success, 0 on error.

       OSSL_STORE_expect_fn
	   This	function takes a OSSL_STORE_LOADER_CTX pointer and a
	   OSSL_STORE_INFO identity expected, and is used to tell the loader
	   what	object type is expected.  expected may be zero to signify that
	   no specific object type is expected.

	   This	function is expected to	return 1 on success, 0 on error.

       OSSL_STORE_find_fn
	   This	function takes a OSSL_STORE_LOADER_CTX pointer and a
	   OSSL_STORE_SEARCH search criterion, and is used to tell the loader
	   what	to search for.

	   When	called with the	loader context being NULL, this	function is
	   expected to return 1	if the loader supports the criterion,
	   otherwise 0.

	   When	called with the	loader context being something other than
	   NULL, this function is expected to return 1 on success, 0 on	error.

       OSSL_STORE_load_fn
	   This	function takes a OSSL_STORE_LOADER_CTX pointer and a UI_METHOD
	   with	associated data.  It's expected	to load	the next available
	   data, mold it into a	data structure that can	be wrapped in a
	   OSSL_STORE_INFO using one of	the OSSL_STORE_INFO(3) functions.  If
	   no more data	is available or	an error occurs, this function is
	   expected to return NULL.  The OSSL_STORE_eof_fn and
	   OSSL_STORE_error_fn functions must indicate if it was in fact the
	   end of data or if an	error occurred.

	   Note	that this function retrieves one data item only.

       OSSL_STORE_eof_fn
	   This	function takes a OSSL_STORE_LOADER_CTX pointer and is expected
	   to return 1 to indicate that	the end	of available data has been
	   reached.  It	is otherwise expected to return	0.

       OSSL_STORE_error_fn
	   This	function takes a OSSL_STORE_LOADER_CTX pointer and is expected
	   to return 1 to indicate that	an error occurred in a previous	call
	   to the OSSL_STORE_load_fn function.	It is otherwise	expected to
	   return 0.

       OSSL_STORE_close_fn
	   This	function takes a OSSL_STORE_LOADER_CTX pointer and is expected
	   to close or shut down what needs to be closed, and finally free the
	   contents of the OSSL_STORE_LOADER_CTX pointer.  It returns 1	on
	   success and 0 on error.

   Functions
       OSSL_STORE_LOADER_new() creates a new OSSL_STORE_LOADER.	 It takes an
       ENGINE e	and a string scheme.  scheme must always be set.  Both e and
       scheme are used as is and must therefore	be alive as long as the
       created loader is.

       OSSL_STORE_LOADER_get0_engine() returns the engine of the store_loader.
       OSSL_STORE_LOADER_get0_scheme() returns the scheme of the store_loader.

       OSSL_STORE_LOADER_set_open() sets the opener function for the
       store_loader.

       OSSL_STORE_LOADER_set_ctrl() sets the control function for the
       store_loader.

       OSSL_STORE_LOADER_set_expect() sets the expect function for the
       store_loader.

       OSSL_STORE_LOADER_set_load() sets the loader function for the
       store_loader.

       OSSL_STORE_LOADER_set_eof() sets	the end	of file	checker	function for
       the store_loader.

       OSSL_STORE_LOADER_set_close() sets the closing function for the
       store_loader.

       OSSL_STORE_LOADER_free()	frees the given	store_loader.

       OSSL_STORE_register_loader() register the given store_loader and
       thereby makes it	available for use with OSSL_STORE_open(),
       OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close().

       OSSL_STORE_unregister_loader() unregister the store loader for the
       given scheme.

NOTES
       The file: scheme	has built in support.

RETURN VALUES
       The functions with the types OSSL_STORE_open_fn,	OSSL_STORE_ctrl_fn,
       OSSL_STORE_expect_fn, OSSL_STORE_load_fn, OSSL_STORE_eof_fn and
       OSSL_STORE_close_fn have	the same return	values as OSSL_STORE_open(),
       OSSL_STORE_ctrl(), OSSL_STORE_expect(), OSSL_STORE_load(),
       OSSL_STORE_eof()	and OSSL_STORE_close(),	respectively.

       OSSL_STORE_LOADER_new() returns a pointer to a OSSL_STORE_LOADER	on
       success,	or NULL	on failure.

       OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_ctrl(),
       OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_eof() and
       OSSL_STORE_LOADER_set_close() return 1 on success, or 0 on failure.

       OSSL_STORE_register_loader() returns 1 on success, or 0 on failure.

       OSSL_STORE_unregister_loader() returns the unregistered loader on
       success,	or NULL	on failure.

SEE ALSO
       ossl_store(7), OSSL_STORE_open(3)

HISTORY
       OSSL_STORE_LOADER(), OSSL_STORE_LOADER_CTX(), OSSL_STORE_LOADER_new(),
       OSSL_STORE_LOADER_set0_scheme(),	OSSL_STORE_LOADER_set_open(),
       OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(),
       OSSL_STORE_LOADER_set_eof(), OSSL_STORE_LOADER_set_close(),
       OSSL_STORE_LOADER_free(), OSSL_STORE_register_loader(),
       OSSL_STORE_unregister_loader(), OSSL_STORE_open_fn(),
       OSSL_STORE_ctrl_fn(), OSSL_STORE_load_fn(), OSSL_STORE_eof_fn() and
       OSSL_STORE_close_fn() were added	to OpenSSL 1.1.1.

COPYRIGHT
       Copyright 2016-2018 The OpenSSL Project Authors.	All Rights Reserved.

       Licensed	under the OpenSSL license (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
       <https://www.openssl.org/source/license.html>.

1.1.1a				  2018-11-20		  OSSL_STORE_LOADER(3)

NAME | SYNOPSIS | DESCRIPTION | NOTES | RETURN VALUES | SEE ALSO | HISTORY | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=OSSL_STORE_LOADER&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help