1=pod 2 3=head1 NAME 4 5provider-storemgmt - The OSSL_STORE library E<lt>-E<gt> provider functions 6 7=head1 SYNOPSIS 8 9 #include <openssl/core_dispatch.h> 10 11 /* 12 * None of these are actual functions, but are displayed like this for 13 * the function signatures for functions that are offered as function 14 * pointers in OSSL_DISPATCH arrays. 15 */ 16 17 void *OSSL_FUNC_store_open(void *provctx, const char *uri); 18 void *OSSL_FUNC_store_attach(void *provctx, OSSL_CORE_BIO *bio); 19 const OSSL_PARAM *store_settable_ctx_params(void *provctx); 20 int OSSL_FUNC_store_set_ctx_params(void *loaderctx, const OSSL_PARAM[]); 21 int OSSL_FUNC_store_load(void *loaderctx, 22 OSSL_CALLBACK *object_cb, void *object_cbarg, 23 OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg); 24 int OSSL_FUNC_store_eof(void *loaderctx); 25 int OSSL_FUNC_store_close(void *loaderctx); 26 27 int OSSL_FUNC_store_export_object 28 (void *loaderctx, const void *objref, size_t objref_sz, 29 OSSL_CALLBACK *export_cb, void *export_cbarg); 30 31=head1 DESCRIPTION 32 33The STORE operation is the provider side of the L<ossl_store(7)> API. 34 35The primary responsibility of the STORE operation is to load all sorts 36of objects from a container indicated by URI. These objects are given 37to the OpenSSL library in provider-native object abstraction form (see 38L<provider-object(7)>). The OpenSSL library is then responsible for 39passing on that abstraction to suitable provided functions. 40 41Examples of functions that the OpenSSL library can pass the abstraction to 42include OSSL_FUNC_keymgmt_load() (L<provider-keymgmt(7)>), 43OSSL_FUNC_store_export_object() (which exports the object in parameterized 44form). 45 46All "functions" mentioned here are passed as function pointers between 47F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via 48L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's 49provider_query_operation() function 50(see L<provider-base(7)/Provider Functions>). 51 52All these "functions" have a corresponding function type definition named 53B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the function pointer 54from a L<OSSL_DISPATCH(3)> element named B<OSSL_get_{name}>. 55For example, the "function" OSSL_FUNC_store_attach() has these: 56 57 typedef void *(OSSL_FUNC_store_attach_fn)(void *provctx, 58 OSSL_CORE_BIO * bio); 59 static ossl_inline OSSL_FUNC_store_attach_fn 60 OSSL_FUNC_store_attach(const OSSL_DISPATCH *opf); 61 62L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as macros 63in L<openssl-core_dispatch.h(7)>, as follows: 64 65 OSSL_FUNC_store_open OSSL_FUNC_STORE_OPEN 66 OSSL_FUNC_store_attach OSSL_FUNC_STORE_ATTACH 67 OSSL_FUNC_store_settable_ctx_params OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS 68 OSSL_FUNC_store_set_ctx_params OSSL_FUNC_STORE_SET_CTX_PARAMS 69 OSSL_FUNC_store_load OSSL_FUNC_STORE_LOAD 70 OSSL_FUNC_store_eof OSSL_FUNC_STORE_EOF 71 OSSL_FUNC_store_close OSSL_FUNC_STORE_CLOSE 72 OSSL_FUNC_store_export_object OSSL_FUNC_STORE_EXPORT_OBJECT 73 74=head2 Functions 75 76OSSL_FUNC_store_open() should create a provider side context with data based 77on the input I<uri>. The implementation is entirely responsible for the 78interpretation of the URI. 79 80OSSL_FUNC_store_attach() should create a provider side context with the core 81B<BIO> I<bio> attached. This is an alternative to using a URI to find storage, 82supporting L<OSSL_STORE_attach(3)>. 83 84OSSL_FUNC_store_settable_ctx_params() should return a constant array of 85descriptor L<OSSL_PARAM(3)>, for parameters that OSSL_FUNC_store_set_ctx_params() 86can handle. 87 88OSSL_FUNC_store_set_ctx_params() should set additional parameters, such as what 89kind of data to expect, search criteria, and so on. More on those below, in 90L</Load Parameters>. Whether unrecognised parameters are an error or simply 91ignored is at the implementation's discretion. 92Passing NULL for I<params> should return true. 93 94OSSL_FUNC_store_load() loads the next object from the URI opened by 95OSSL_FUNC_store_open(), creates an object abstraction for it (see 96L<provider-object(7)>), and calls I<object_cb> with it as well as 97I<object_cbarg>. I<object_cb> will then interpret the object abstraction 98and do what it can to wrap it or decode it into an OpenSSL structure. In 99case a passphrase needs to be prompted to unlock an object, I<pw_cb> should 100be called. 101 102OSSL_FUNC_store_eof() indicates if the end of the set of objects from the 103URI has been reached. When that happens, there's no point trying to do any 104further loading. 105 106OSSL_FUNC_store_close() frees the provider side context I<ctx>. 107 108When a provider-native object is created by a store manager it would be unsuitable 109for direct use with a foreign provider. The export function allows for 110exporting the object to that foreign provider if the foreign provider 111supports the type of the object and provides an import function. 112 113OSSL_FUNC_store_export_object() should export the object of size I<objref_sz> 114referenced by I<objref> as an L<OSSL_PARAM(3)> array and pass that to the 115I<export_cb> as well as the given I<export_cbarg>. 116 117=head2 Load Parameters 118 119=over 4 120 121=item "expect" (B<OSSL_STORE_PARAM_EXPECT>) <integer> 122 123Is a hint of what type of data the OpenSSL library expects to get. 124This is only useful for optimization, as the library will check that the 125object types match the expectation too. 126 127The number that can be given through this parameter is found in 128F<< <openssl/store.h> >>, with the macros having names starting with 129C<OSSL_STORE_INFO_>. These are further described in 130L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS>. 131 132=item "subject" (B<OSSL_STORE_PARAM_SUBJECT>) <octet string> 133 134Indicates that the caller wants to search for an object with the given 135subject associated. This can be used to select specific certificates 136by subject. 137 138The contents of the octet string is expected to be in DER form. 139 140=item "issuer" (B<OSSL_STORE_PARAM_ISSUER>) <octet string> 141 142Indicates that the caller wants to search for an object with the given 143issuer associated. This can be used to select specific certificates 144by issuer. 145 146The contents of the octet string is expected to be in DER form. 147 148=item "serial" (B<OSSL_STORE_PARAM_SERIAL>) <integer> 149 150Indicates that the caller wants to search for an object with the given 151serial number associated. 152 153=item "digest" (B<OSSL_STORE_PARAM_DIGEST>) <UTF8 string> 154 155=item "fingerprint" (B<OSSL_STORE_PARAM_FINGERPRINT>) <octet string> 156 157Indicates that the caller wants to search for an object with the given 158fingerprint, computed with the given digest. 159 160=item "alias" (B<OSSL_STORE_PARAM_ALIAS>) <UTF8 string> 161 162Indicates that the caller wants to search for an object with the given 163alias (some call it a "friendly name"). 164 165=item "properties" (B<OSSL_STORE_PARAM_PROPERTIES>) <utf8 string> 166 167Property string to use when querying for algorithms such as the B<OSSL_DECODER> 168decoder implementations. 169 170=item "input-type" (B<OSSL_STORE_PARAM_INPUT_TYPE>) <utf8 string> 171 172Type of the input format as a hint to use when decoding the objects in the 173store. 174 175=back 176 177Several of these search criteria may be combined. For example, to 178search for a certificate by issuer+serial, both the "issuer" and the 179"serial" parameters will be given. 180 181=head1 SEE ALSO 182 183L<provider(7)> 184 185=head1 HISTORY 186 187The STORE interface was introduced in OpenSSL 3.0. 188 189=head1 COPYRIGHT 190 191Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved. 192 193Licensed under the Apache License 2.0 (the "License"). You may not use 194this file except in compliance with the License. You can obtain a copy 195in the file LICENSE in the source distribution or at 196L<https://www.openssl.org/source/license.html>. 197 198=cut 199