--- /dev/null
+=pod
+
+=head1 NAME
+
+provider-storemgmt - The OSSL_STORE library E<lt>-E<gt> provider functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/core_dispatch.h>
+
+ /*
+ * None of these are actual functions, but are displayed like this for
+ * the function signatures for functions that are offered as function
+ * pointers in OSSL_DISPATCH arrays.
+ */
+
+ void *OSSL_FUNC_store_open(void *provctx, const char *uri);
+ void *OSSL_FUNC_store_attach(void *provctx, OSSL_CORE_BIO *bio);
+ const OSSL_PARAM *store_settable_ctx_params(void *provctx);
+ int OSSL_FUNC_store_set_ctx_params(void *loaderctx, const OSSL_PARAM[]);
+ int OSSL_FUNC_store_load(void *loaderctx,
+ OSSL_CALLBACK *object_cb, void *object_cbarg,
+ OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg);
+ int OSSL_FUNC_store_eof(void *loaderctx);
+ int OSSL_FUNC_store_close(void *loaderctx);
+
+ int OSSL_FUNC_store_export_object
+ (void *loaderctx, const void *objref, size_t objref_sz,
+ OSSL_CALLBACK *export_cb, void *export_cbarg);
+
+=head1 DESCRIPTION
+
+The STORE operation is the provider side of the L<ossl_store(7)> API.
+
+The primary responsibility of the STORE operation is to load all sorts
+of objects from a container indicated by URI. These objects are given
+to the OpenSSL library in provider-native object abstraction form (see
+L<provider-object(7)>). The OpenSSL library is then responsible for
+passing on that abstraction to suitable provided functions.
+
+Examples of functions that the OpenSSL library can pass the abstraction to
+include OSSL_FUNC_keymgmt_load() (L<provider-keymgmt(7)>),
+OSSL_FUNC_store_export_object() (which exports the object in parameterized
+form).
+
+All "functions" mentioned here are passed as function pointers between
+F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
+B<OSSL_ALGORITHM> arrays that are returned by the provider's
+provider_query_operation() function
+(see L<provider-base(7)/Provider Functions>).
+
+All these "functions" have a corresponding function type definition named
+B<OSSL_{name}_fn>, and a helper function to retrieve the function pointer
+from a B<OSSL_DISPATCH> element named B<OSSL_get_{name}>.
+For example, the "function" OSSL_FUNC_store_load() has these:
+
+ typedef void *(OSSL_OSSL_FUNC_store_load_fn)(void *provctx,
+ const OSSL_PARAM params[]);
+ static ossl_inline OSSL_OSSL_FUNC_store_load_fn
+ OSSL_OSSL_FUNC_store_load(const OSSL_DISPATCH *opf);
+
+B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as macros
+in L<openssl-core_dispatch.h(7)>, as follows:
+
+ OSSL_FUNC_store_open OSSL_FUNC_STORE_OPEN
+ OSSL_FUNC_store_attach OSSL_FUNC_STORE_ATTACH
+ OSSL_FUNC_store_settable_ctx_params OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS
+ OSSL_FUNC_store_set_ctx_params OSSL_FUNC_STORE_SET_CTX_PARAMS
+ OSSL_FUNC_store_load OSSL_FUNC_STORE_LOAD
+ OSSL_FUNC_store_eof OSSL_FUNC_STORE_EOF
+ OSSL_FUNC_store_close OSSL_FUNC_STORE_CLOSE
+ OSSL_FUNC_store_export_object OSSL_FUNC_STORE_EXPORT_OBJECT
+
+=head2 Functions
+
+OSSL_FUNC_store_open() should create a provider side context with data based
+on the input I<uri>. The implementation is entirely responsible for the
+interpretation of the URI.
+
+OSSL_FUNC_store_attach() should create a provider side context with the core
+B<BIO> I<bio> attached. This is an alternative to using a URI to find storage,
+supporting L<OSSL_STORE_attach(3)>.
+
+OSSL_FUNC_store_settable_ctx_params() should return a constant array of
+descriptor B<OSSL_PARAM>, for parameters that OSSL_FUNC_store_set_ctx_params()
+can handle.
+
+OSSL_FUNC_store_set_ctx_params() should set additional parameters, such as what
+kind of data to expect, search criteria, and so on. More on those below, in
+L</Load Parameters>. Whether unrecognised parameters are an error or simply
+ignored is at the implementation's discretion.
+
+OSSL_FUNC_store_load() loads the next object from the URI opened by
+OSSL_FUNC_store_open(), creates an object abstraction for it (see
+L<provider-object(7)>), and calls I<object_cb> with it as well as
+I<object_cbarg>. I<object_cb> will then interpret the object abstraction
+and do what it can to wrap it or decode it into an OpenSSL structure. In
+case a passphrase needs to be prompted to unlock an object, I<pw_cb> should
+be called.
+
+OSSL_FUNC_store_eof() indicates if the end of the set of objects from the
+URI has been reached. When that happens, there's no point trying to do any
+further loading.
+
+OSSL_FUNC_store_close() frees the provider side context I<ctx>.
+
+=head2 Load Parameters
+
+=over 4
+
+=item "expect" (B<OSSL_STORE_PARAM_EXPECT>) <integer>
+
+Is a hint of what type of data the OpenSSL library expects to get.
+This is only useful for optimization, as the library will check that the
+object types match the expectation too.
+
+The number that can be given through this parameter is found in
+F<< <openssl/store.h> >>, with the macros having names starting with
+C<OSSL_STORE_INFO_>. These are further described in
+L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS>.
+
+=item "subject" (B<OSSL_STORE_PARAM_SUBJECT>) <octet string>
+
+Indicates that the caller wants to search for an object with the given
+subject associated. This can be used to select specific certificates
+by subject.
+
+The contents of the octet string is expected to be in DER form.
+
+=item "issuer" (B<OSSL_STORE_PARAM_ISSUER>) <octet string>
+
+Indicates that the caller wants to search for an object with the given
+issuer associated. This can be used to select specific certificates
+by issuer.
+
+The contents of the octet string is expected to be in DER form.
+
+=item "serial" (B<OSSL_STORE_PARAM_SERIAL>) <integer>
+
+Indicates that the caller wants to search for an object with the given
+serial number associated.
+
+=item "digest" (B<OSSL_STORE_PARAM_DIGEST>) <utf8 string>
+
+=item "fingerprint" (B<OSSL_STORE_PARAM_FINGERPRINT>) <octet string>
+
+Indicates that the caller wants to search for an object with the given
+fingerprint, computed with the given digest.
+
+=item "alias" (B<OSSL_STORE_PARAM_ALIAS>) <utf8 string>
+
+Indicates that the caller wants to search for an object with the given
+alias (some call it a "friendly name").
+
+=back
+
+Several of these search criteria may be combined. For example, to
+search for a certificate by issuer+serial, both the "issuer" and the
+"serial" parameters will be given.
+
+=head1 SEE ALSO
+
+L<provider(7)>
+
+=head1 HISTORY
+
+The STORE interface was introduced in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+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
+L<https://www.openssl.org/source/license.html>.
+
+=cut
# define OSSL_OP_SIGNATURE 12
# define OSSL_OP_ASYM_CIPHER 13
/* New section for non-EVP operations */
-# define OSSL_OP_ENCODER 20
-# define OSSL_OP_DECODER 21
+# define OSSL_OP_ENCODER 20
+# define OSSL_OP_DECODER 21
+# define OSSL_OP_STORE 22
/* Highest known operation number */
-# define OSSL_OP__HIGHEST 21
+# define OSSL_OP__HIGHEST 22
/* Digests */
(void *ctx, const void *objref, size_t objref_sz,
OSSL_CALLBACK *export_cb, void *export_cbarg))
+/*-
+ * Store
+ *
+ * Objects are scanned by using the 'open', 'load', 'eof' and 'close'
+ * functions, which implement an OSSL_STORE loader.
+ *
+ * store_load() works in a way that's very similar to the decoders, in
+ * that they pass an abstract object through a callback, either as a DER
+ * octet string or as an object reference, which libcrypto will have to
+ * deal with.
+ */
+
+#define OSSL_FUNC_STORE_OPEN 1
+#define OSSL_FUNC_STORE_ATTACH 2
+#define OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS 3
+#define OSSL_FUNC_STORE_SET_CTX_PARAMS 4
+#define OSSL_FUNC_STORE_LOAD 5
+#define OSSL_FUNC_STORE_EOF 6
+#define OSSL_FUNC_STORE_CLOSE 7
+#define OSSL_FUNC_STORE_EXPORT_OBJECT 8
+OSSL_CORE_MAKE_FUNC(void *, store_open, (void *provctx, const char *uri))
+OSSL_CORE_MAKE_FUNC(void *, store_attach, (void *provctx, OSSL_CORE_BIO *in))
+OSSL_CORE_MAKE_FUNC(const OSSL_PARAM *, store_settable_ctx_params,
+ (void *provctx))
+OSSL_CORE_MAKE_FUNC(int, store_set_ctx_params,
+ (void *loaderctx, const OSSL_PARAM params[]))
+OSSL_CORE_MAKE_FUNC(int, store_load,
+ (void *loaderctx,
+ OSSL_CALLBACK *object_cb, void *object_cbarg,
+ OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg))
+OSSL_CORE_MAKE_FUNC(int, store_eof, (void *loaderctx))
+OSSL_CORE_MAKE_FUNC(int, store_close, (void *loaderctx))
+OSSL_CORE_MAKE_FUNC(int, store_export_object,
+ (void *loaderctx, const void *objref, size_t objref_sz,
+ OSSL_CALLBACK *export_cb, void *export_cbarg))
+
# ifdef __cplusplus
}
# endif
projects / openssl.git / commitdiff