From 6ab6deccd95c97a6235f345b371664afb65f77c7 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Wed, 5 Jul 2017 19:17:40 +0200 Subject: [PATCH] STORE: Add documentation on search criteria Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/2688) --- doc/man1/storeutl.pod | 35 ++++++ doc/man3/OSSL_STORE_LOADER.pod | 23 +++- doc/man3/OSSL_STORE_SEARCH.pod | 193 +++++++++++++++++++++++++++++++++ doc/man3/OSSL_STORE_expect.pod | 33 +++++- doc/man7/ossl_store.pod | 5 +- util/private.num | 2 + 6 files changed, 280 insertions(+), 11 deletions(-) create mode 100644 doc/man3/OSSL_STORE_SEARCH.pod 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 B [B<-certs>] [B<-keys>] [B<-crls>] +[B<-subject arg>] +[B<-issuer arg>] +[B<-serial arg>] +[B<-alias arg>] +[B<-fingerprint arg>] +[B<-I>] B ... =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. +The arg must be formatted as I, +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 be used together. +The issuer arg must be formatted as I, +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> + +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 is a type template, to be defined by each loader using B. B, B, B, -B, B and B +B, B, B, +and B 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 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 + +This function takes a B pointer and a +B search criterion, and is used to tell the loader what +to search for. + +When called with the loader context being B, 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, this +function is expected to return 1 on success, 0 on error. + =item B This function takes a B pointer and a B 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 + + 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 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 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 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_free() is used to free the B. + +=head2 Loader Functions + +OSSL_STORE_SEARCH_get_type() returns the criterion type for the given +B. + +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, as +available for each type. +For more information, see L 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 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 pointer, and the serial number is +a B 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 pointer on success, or B on failure. + +OSSL_STORE_SEARCH_get_type() returns the criterion type of the given +B. +There is no error value. + +OSSL_STORE_SEARCH_get0_name() returns a B pointer on success, +or B when the given B was of a different type. + +OSSL_STORE_SEARCH_get0_serial() returns a B pointer on success, +or B when the given B was of a different type. + +OSSL_STORE_SEARCH_get0_bytes() returns a B pointer and +sets B<*length> to the strings length on success, or B when the given +B was of a different type. + +OSSL_STORE_SEARCH_get0_string() returns a B pointer on success, +or B when the given B was of a different type. + +OSSL_STORE_SEARCH_get0_digest() returns a B pointer. +B is a valid value and means that the store loader default will +be used when applicable. + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +B, +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. + +=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. All known object types (see L) except for B are supported. -OSSL_STORE_expect() I 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 for information on the +supported search criterion types. + +OSSL_STORE_expect() and OSSL_STORE_find I 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, L, L +L, L, L, +L =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, L, -L, L +L, L, +L =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 diff --git a/util/private.num b/util/private.num index 48665577c9..c106e60899 100644 --- a/util/private.num +++ b/util/private.num @@ -31,9 +31,11 @@ OSSL_STORE_CTX datatype OSSL_STORE_INFO datatype OSSL_STORE_LOADER datatype OSSL_STORE_LOADER_CTX datatype +OSSL_STORE_SEARCH datatype OSSL_STORE_close_fn datatype OSSL_STORE_ctrl_fn datatype OSSL_STORE_expect_fn datatype +OSSL_STORE_find_fn datatype OSSL_STORE_eof_fn datatype OSSL_STORE_error_fn datatype OSSL_STORE_load_fn datatype -- GitLab