mirror of
https://github.com/openssl/openssl.git
synced 2024-11-27 05:21:51 +08:00
8704b6bf32
Reviewed-by: Shane Lontis <shane.lontis@oracle.com> (Merged from https://github.com/openssl/openssl/pull/12512)
179 lines
6.7 KiB
Plaintext
179 lines
6.7 KiB
Plaintext
=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
|