From: Richard Levitte Date: Wed, 22 Jul 2020 20:54:42 +0000 (+0200) Subject: STORE for providers: define libcrypto <-> provider interface X-Git-Tag: openssl-3.0.0-alpha7~491 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8704b6bf32ccc24570b57fbdfef685fbd3572635;p=thirdparty%2Fopenssl.git STORE for providers: define libcrypto <-> provider interface Reviewed-by: Shane Lontis (Merged from https://github.com/openssl/openssl/pull/12512) --- diff --git a/doc/man7/provider-storemgmt.pod b/doc/man7/provider-storemgmt.pod new file mode 100644 index 00000000000..2e5bddc5ec6 --- /dev/null +++ b/doc/man7/provider-storemgmt.pod @@ -0,0 +1,178 @@ +=pod + +=head1 NAME + +provider-storemgmt - The OSSL_STORE library E-E provider functions + +=head1 SYNOPSIS + + #include + + /* + * 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 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). 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), +OSSL_FUNC_store_export_object() (which exports the object in parameterized +form). + +All "functions" mentioned here are passed as function pointers between +F and the provider in B arrays via +B arrays that are returned by the provider's +provider_query_operation() function +(see L). + +All these "functions" have a corresponding function type definition named +B, and a helper function to retrieve the function pointer +from a B element named B. +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 arrays are indexed by numbers that are provided as macros +in L, 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. 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 I attached. This is an alternative to using a URI to find storage, +supporting L. + +OSSL_FUNC_store_settable_ctx_params() should return a constant array of +descriptor B, 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. 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), and calls I with it as well as +I. I 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 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. + +=head2 Load Parameters + +=over 4 + +=item "expect" (B) + +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<< >>, with the macros having names starting with +C. These are further described in +L. + +=item "subject" (B) + +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) + +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) + +Indicates that the caller wants to search for an object with the given +serial number associated. + +=item "digest" (B) + +=item "fingerprint" (B) + +Indicates that the caller wants to search for an object with the given +fingerprint, computed with the given digest. + +=item "alias" (B) + +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 + +=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. + +=cut diff --git a/include/openssl/core_dispatch.h b/include/openssl/core_dispatch.h index ee589eae6b2..b21fe559f77 100644 --- a/include/openssl/core_dispatch.h +++ b/include/openssl/core_dispatch.h @@ -191,10 +191,11 @@ OSSL_CORE_MAKE_FUNC(int, provider_self_test, (void *provctx)) # 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 */ @@ -760,6 +761,42 @@ OSSL_CORE_MAKE_FUNC(int, decoder_export_object, (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 diff --git a/include/openssl/core_names.h b/include/openssl/core_names.h index 9944206b849..4ca794fd50f 100644 --- a/include/openssl/core_names.h +++ b/include/openssl/core_names.h @@ -484,6 +484,34 @@ extern "C" { #define OSSL_CAPABILITY_TLS_GROUP_MIN_DTLS "tls-min-dtls" #define OSSL_CAPABILITY_TLS_GROUP_MAX_DTLS "tls-max-dtls" +/*- + * storemgmt parameters + */ + +/* + * Used by storemgmt_ctx_set_params(): + * + * - OSSL_STORE_PARAM_EXPECT is an INTEGER, and the value is any of the + * OSSL_STORE_INFO numbers. This is used to set the expected type of + * object loaded. + * + * - OSSL_STORE_PARAM_SUBJECT, OSSL_STORE_PARAM_ISSUER, + * OSSL_STORE_PARAM_SERIAL, OSSL_STORE_PARAM_FINGERPRINT, + * OSSL_STORE_PARAM_DIGEST, OSSL_STORE_PARAM_ALIAS + * are used as search criteria. + * (OSSL_STORE_PARAM_DIGEST is used with OSSL_STORE_PARAM_FINGERPRINT) + */ +#define OSSL_STORE_PARAM_EXPECT "expect" /* INTEGER */ +#define OSSL_STORE_PARAM_SUBJECT "subject" /* DER blob => OCTET_STRING */ +#define OSSL_STORE_PARAM_ISSUER "name" /* DER blob => OCTET_STRING */ +#define OSSL_STORE_PARAM_SERIAL "serial" /* INTEGER */ +#define OSSL_STORE_PARAM_DIGEST "digest" /* UTF8_STRING */ +#define OSSL_STORE_PARAM_FINGERPRINT "fingerprint" /* OCTET_STRING */ +#define OSSL_STORE_PARAM_ALIAS "alias" /* UTF8_STRING */ + +/* You may want to pass properties for the provider implementation to use */ +#define OSSL_STORE_PARAM_PROPERTIES "properties" /* utf8_string */ + # ifdef __cplusplus } # endif