STORE: Add documentation on search criteria

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/2688)

5 files changed, 278 insertions, 11 deletions

diff --git a/doc/man1/storeutl.pod b/doc/man1/storeutl.pod
index 5b4faf4a25..3f26ab500b 100644
--- a/doc/man1/storeutl.pod
+++ b/doc/man1/storeutl.pod
@@ -18,6 +18,12 @@ B<openssl> B<storeutl>
 [B<-certs>]
 [B<-keys>]
 [B<-crls>]
+[B<-subject arg>]
+[B<-issuer arg>]
+[B<-serial arg>]
+[B<-alias arg>]
+[B<-fingerprint arg>]
+[B<-I<digest>>]
 B<uri> ...
 
 =head1 DESCRIPTION
@@ -73,6 +79,35 @@ Only select the certificates, keys or CRLs from the given URI.
 However, if this URI would return a set of names (URIs), those are always
 returned.
 
+=item B<-subject arg>
+
+Search for an object having the subject name B<arg>.
+The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
+characters may be escaped by \ (backslash), no spaces are skipped.
+
+=item B<-issuer arg>
+
+=item B<-serial arg>
+
+Search for an object having the given issuer name and serial number.
+These two options I<must> be used together.
+The issuer arg must be formatted as I</type0=value0/type1=value1/type2=...>,
+characters may be escaped by \ (backslash), no spaces are skipped.
+The serial arg may be specified as a decimal value or a hex value if preceded
+by B<0x>.
+
+=item B<-alias arg>
+
+Search for an object having the given alias.
+
+=item B<-fingerprint arg>
+
+Search for an object having the given fingerprint.
+
+=item B<-I<digest>>
+
+The digest that was used to compute the fingerprint given with B<-fingerprint>.
+
 =back
 
 =head1 SEE ALSO
diff --git a/doc/man3/OSSL_STORE_LOADER.pod b/doc/man3/OSSL_STORE_LOADER.pod
index aa64f2d773..e827434192 100644
--- a/doc/man3/OSSL_STORE_LOADER.pod
+++ b/doc/man3/OSSL_STORE_LOADER.pod
@@ -5,12 +5,12 @@
 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
@@ -42,6 +42,10 @@ 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);
@@ -77,7 +81,8 @@ B<OSSL_STORE_LOADER_CTX> is a type template, to be defined by each loader
 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.
 
@@ -122,6 +127,18 @@ B<expected> may be zero to signify that no specific object type is expected.
 
 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>
diff --git a/doc/man3/OSSL_STORE_SEARCH.pod b/doc/man3/OSSL_STORE_SEARCH.pod
new file mode 100644
index 0000000000..411664d4ce
--- /dev/null
+++ b/doc/man3/OSSL_STORE_SEARCH.pod
@@ -0,0 +1,193 @@
+=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
diff --git a/doc/man3/OSSL_STORE_expect.pod b/doc/man3/OSSL_STORE_expect.pod
index ef97ec85c4..ab0e8784c2 100644
--- a/doc/man3/OSSL_STORE_expect.pod
+++ b/doc/man3/OSSL_STORE_expect.pod
@@ -2,7 +2,10 @@
 
 =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
 
@@ -10,6 +13,10 @@ OSSL_STORE_expect - Specify what object type is expected
 
  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
@@ -20,8 +27,16 @@ that it expects the type B<OSSL_STORE_INFO_CERT>.
 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
 
@@ -37,14 +52,20 @@ method is usually preferable.
 
 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
 
diff --git a/doc/man7/ossl_store.pod b/doc/man7/ossl_store.pod
index 80debebafc..98cc04f79a 100644
--- a/doc/man7/ossl_store.pod
+++ b/doc/man7/ossl_store.pod
@@ -87,11 +87,12 @@ only).
 =head1 SEE ALSO
 
 L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>,
-L<OSSL_STORE_open(3)>, L<OSSL_STORE_expect(3)>
+L<OSSL_STORE_open(3)>, L<OSSL_STORE_expect(3)>,
+L<OSSL_STORE_SEARCH(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-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