diff options
author | Richard Levitte <levitte@openssl.org> | 2017-07-05 19:17:40 +0200 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2018-02-23 07:40:42 +0100 |
commit | 6ab6deccd95c97a6235f345b371664afb65f77c7 (patch) | |
tree | 7633a0cd52b2595c8554aacfff902c71ac7344db /doc/man3 | |
parent | 511e4e0d6890d552eba77971bbcfb5df51e772e2 (diff) | |
download | openssl-new-6ab6deccd95c97a6235f345b371664afb65f77c7.tar.gz |
STORE: Add documentation on search criteria
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/2688)
Diffstat (limited to 'doc/man3')
-rw-r--r-- | doc/man3/OSSL_STORE_LOADER.pod | 23 | ||||
-rw-r--r-- | doc/man3/OSSL_STORE_SEARCH.pod | 193 | ||||
-rw-r--r-- | doc/man3/OSSL_STORE_expect.pod | 33 |
3 files changed, 240 insertions, 9 deletions
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 |