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_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_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
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);
using B<struct ossl_store_loader_ctx_st { ... }>.
B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>, B<OSSL_STORE_expect_fn>,
-B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn> and B<OSSL_STORE_close_fn>
+B<OSSL_STORE_find_fn>, B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn>,
+and B<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.
This function is expected to return 1 on success, 0 on error.
+=item B<OSSL_STORE_find_fn>
+
+This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a
+B<OSSL_STORE_SEARCH> search criterion, and is used to tell the loader what
+to search for.
+
+When called with the loader context being B<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 B<NULL>, this
+function is expected to return 1 on success, 0 on error.
+
=item B<OSSL_STORE_load_fn>
This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<UI_METHOD>
--- /dev/null
+=pod
+
+=head1 NAME
+
+OSSL_STORE_SEARCH,
+OSSL_STORE_SEARCH_by_name,
+OSSL_STORE_SEARCH_by_issuer_serial,
+OSSL_STORE_SEARCH_by_key_fingerprint,
+OSSL_STORE_SEARCH_by_alias,
+OSSL_STORE_SEARCH_free,
+OSSL_STORE_SEARCH_get_type,
+OSSL_STORE_SEARCH_get0_name,
+OSSL_STORE_SEARCH_get0_serial,
+OSSL_STORE_SEARCH_get0_bytes,
+OSSL_STORE_SEARCH_get0_string,
+OSSL_STORE_SEARCH_get0_digest
+- Type and functions to create OSSL_STORE search criteria
+
+=head1 SYNOPSIS
+
+ #include <openssl/store.h>
+
+ typedef struct ossl_store_search_st OSSL_STORE_SEARCH;
+
+ OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_name(X509_NAME *name);
+ OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_issuer_serial(X509_NAME *name,
+ const ASN1_INTEGER
+ *serial);
+ OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_key_fingerprint(const EVP_MD *digest,
+ const unsigned char
+ *bytes, int len);
+ OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_alias(const char *alias);
+
+ void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search);
+
+ int OSSL_STORE_SEARCH_get_type(const OSSL_STORE_SEARCH *criterion);
+ X509_NAME *OSSL_STORE_SEARCH_get0_name(OSSL_STORE_SEARCH *criterion);
+ const ASN1_INTEGER *OSSL_STORE_SEARCH_get0_serial(const OSSL_STORE_SEARCH
+ *criterion);
+ const unsigned char *OSSL_STORE_SEARCH_get0_bytes(const OSSL_STORE_SEARCH
+ *criterion, size_t *length);
+ const char *OSSL_STORE_SEARCH_get0_string(const OSSL_STORE_SEARCH *criterion);
+ const EVP_MD *OSSL_STORE_SEARCH_get0_digest(const OSSL_STORE_SEARCH
+ *criterion);
+
+=head1 DESCRIPTION
+
+These functions are use to specify search criteria to help search for specific
+objects through other names than just the URI that's given to OSSL_STORE_open().
+For example, this can be useful for an application that has received a URI
+and then wants to add on search criteria in a uniform and supported manner.
+
+=head2 Types
+
+B<OSSL_STORE_SEARCH> is an opaque type that holds the constructed search
+criterion, and that can be given to an OSSL_STORE context with
+OSSL_STORE_find().
+
+The calling application owns the allocation of an B<OSSL_STORE_SEARCH> at all
+times, and should therefore be careful not to deallocate it before
+OSSL_STORE_close() has been called for the OSSL_STORE context it was given
+to.
+
+=head2 Application Functions
+
+OSSL_STORE_SEARCH_by_name(),
+OSSL_STORE_SEARCH_by_issuer_serial(),
+OSSL_STORE_SEARCH_by_key_fingerprint(),
+and OSSL_STORE_SEARCH_by_alias()
+are used to create an B<OSSL_STORE_SEARCH> from a subject name, an issuer name
+and serial number pair, a key fingerprint, and an alias (for example a friendly
+name).
+The parameters that are provided are not copied, only referred to in a
+criterion, so they must have at least the same life time as the created
+B<OSSL_STORE_SEARCH>.
+
+OSSL_STORE_SEARCH_free() is used to free the B<OSSL_STORE_SEARCH>.
+
+=head2 Loader Functions
+
+OSSL_STORE_SEARCH_get_type() returns the criterion type for the given
+B<OSSL_STORE_SEARCH>.
+
+OSSL_STORE_SEARCH_get0_name(), OSSL_STORE_SEARCH_get0_serial(),
+OSSL_STORE_SEARCH_get0_bytes(), OSSL_STORE_SEARCH_get0_string(),
+and OSSL_STORE_SEARCH_get0_digest()
+are used to retrieve different data from a B<OSSL_STORE_SEARCH>, as
+available for each type.
+For more information, see L</SUPPORTED CRITERION TYPES> below.
+
+=head1 SUPPORTED CRITERION TYPES
+
+Currently supported criterion types are:
+
+=over 4
+
+=item OSSL_STORE_SEARCH_BY_NAME
+
+This criterion supports a search by exact match of subject name.
+The subject name itself is a B<X509_NAME> pointer.
+A criterion of this type is created with OSSL_STORE_SEARCH_by_name(),
+and the actual subject name is retrieved with OSSL_STORE_SEARCH_get0_name().
+
+=item OSSL_STORE_SEARCH_BY_ISSUER_SERIAL
+
+This criterion supports a search by exact match of both issuer name and serial
+number.
+The issuer name itself is a B<X509_NAME> pointer, and the serial number is
+a B<ASN1_INTEGER> pointer.
+A criterion of this type is created with OSSL_STORE_SEARCH_by_issuer_serial()
+and the actual issuer name and serial number are retrieved with
+OSSL_STORE_SEARCH_get0_name() and OSSL_STORE_SEARCH_get0_serial().
+
+=item OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT
+
+This criterion supports a search by exact match of key fingerprint.
+The key fingerprint in itself is a string of bytes and its length, as
+well as the algorithm that was used to compute the fingerprint.
+The digest may be left unspecified (NULL), and in that case, the
+loader has to decide on a default digest and compare fingerprints
+accordingly.
+A criterion of this type is created with OSSL_STORE_SEARCH_by_key_fingerprint()
+and the actual fingerprint and its length can be retrieved with
+OSSL_STORE_SEARCH_get0_bytes().
+The digest can be retreived with OSSL_STORE_SEARCH_get0_digest().
+
+=item OSSL_STORE_SEARCH_BY_ALIAS
+
+This criterion supports a search by match of an alias of some kind.
+The alias in itself is a simple C string.
+A criterion of this type is created with OSSL_STORE_SEARCH_by_alias()
+and the actual alias is retrieved with OSSL_STORE_SEARCH_get0_string().
+
+=back
+
+=head1 RETURN VALUES
+
+OSSL_STORE_SEARCH_by_name(),
+OSSL_STORE_SEARCH_by_issuer_serial(),
+OSSL_STORE_SEARCH_by_key_fingerprint(),
+and OSSL_STORE_SEARCH_by_alias()
+return a B<OSSL_STORE_SEARCH> pointer on success, or B<NULL> on failure.
+
+OSSL_STORE_SEARCH_get_type() returns the criterion type of the given
+B<OSSL_STORE_SEARCH>.
+There is no error value.
+
+OSSL_STORE_SEARCH_get0_name() returns a B<X509_NAME> pointer on success,
+or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type.
+
+OSSL_STORE_SEARCH_get0_serial() returns a B<ASN1_INTEGER> pointer on success,
+or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type.
+
+OSSL_STORE_SEARCH_get0_bytes() returns a B<const unsigned char> pointer and
+sets B<*length> to the strings length on success, or B<NULL> when the given
+B<OSSL_STORE_SEARCH> was of a different type.
+
+OSSL_STORE_SEARCH_get0_string() returns a B<const char> pointer on success,
+or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type.
+
+OSSL_STORE_SEARCH_get0_digest() returns a B<const EVP_MD> pointer.
+B<NULL> is a valid value and means that the store loader default will
+be used when applicable.
+
+=head1 SEE ALSO
+
+L<ossl_store(7)>, L<OSSL_STORE_supports_search(3)>, L<OSSL_STORE_find(3)>
+
+=head1 HISTORY
+
+B<OSSL_STORE_SEARCH>,
+OSSL_STORE_SEARCH_by_name(),
+OSSL_STORE_SEARCH_by_issuer_serial(),
+OSSL_STORE_SEARCH_by_key_fingerprint(),
+OSSL_STORE_SEARCH_by_alias(),
+OSSL_STORE_SEARCH_free(),
+OSSL_STORE_SEARCH_get_type(),
+OSSL_STORE_SEARCH_get0_name(),
+OSSL_STORE_SEARCH_get0_serial(),
+OSSL_STORE_SEARCH_get0_bytes(),
+and OSSL_STORE_SEARCH_get0_string()
+were added to OpenSSL 1.1.1.
+
+=head1 COPYRIGHT
+
+Copyright 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
+L<https://www.openssl.org/source/license.html>.
+
+=cut
=head1 NAME
-OSSL_STORE_expect - Specify what object type is expected
+OSSL_STORE_expect,
+OSSL_STORE_supports_search,
+OSSL_STORE_find
+- Specify what object type is expected
=head1 SYNOPSIS
int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type);
+ int OSSL_STORE_supports_search(OSSL_STORE_CTX *ctx, int criterion_type);
+
+ int OSSL_STORE_find(OSSL_STORE_CTX *ctx, OSSL_STORE_SEARCH *search);
+
=head1 DESCRIPTION
OSSL_STORE_expect() helps applications filter what OSSL_STORE_load() returns
All known object types (see L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS>)
except for B<OSSL_STORE_INFO_NAME> are supported.
-OSSL_STORE_expect() I<must> be called before the first OSSL_STORE_load()
-of a given session, or it will fail.
+OSSL_STORE_find() helps applications specify a criterion for a more fine
+grained search of objects.
+
+OSSL_STORE_supports_search() checks if the loader of the given OSSL_STORE
+context supports the given search type.
+See L<OSSL_STORE_SEARCH/SUPPORED CRITERION TYPES> for information on the
+supported search criterion types.
+
+OSSL_STORE_expect() and OSSL_STORE_find I<must> be called before the first
+OSSL_STORE_load() of a given session, or they will fail.
=head1 NOTES
OSSL_STORE_expect() returns 1 on success, or 0 on failure.
+OSSL_STORE_supports_search() returns 1 if the criterion is supported, or 0
+otherwise.
+
+OSSL_STORE_find() returns 1 on success, or 0 on failure.
+
=head1 SEE ALSO
-L<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_load(3)>
+L<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_SEARCH(3)>,
+L<OSSL_STORE_load(3)>
=head1 HISTORY
-OSSL_STORE_expect()
-was added to OpenSSL 1.1.1.
+OSSL_STORE_expect(), OSSL_STORE_supports_search() and OSSL_STORE_find()
+were added to OpenSSL 1.1.1.
=head1 COPYRIGHT
projects / oweals / openssl.git / commitdiff