From ce9586b98c792288a57620035b7f5824563389ce Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Wed, 5 Jul 2017 16:15:48 +0200 Subject: [PATCH] STORE: Add documentation on expecting specific infos Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/2688) --- doc/man1/storeutl.pod | 15 ++++++++- doc/man3/OSSL_STORE_LOADER.pod | 28 +++++++++++++--- doc/man3/OSSL_STORE_expect.pod | 58 ++++++++++++++++++++++++++++++++++ doc/man7/ossl_store.pod | 3 +- util/private.num | 1 + 5 files changed, 98 insertions(+), 7 deletions(-) create mode 100644 doc/man3/OSSL_STORE_expect.pod diff --git a/doc/man1/storeutl.pod b/doc/man1/storeutl.pod index 74361a7630..5b4faf4a25 100644 --- a/doc/man1/storeutl.pod +++ b/doc/man1/storeutl.pod @@ -15,6 +15,9 @@ B B [B<-text arg>] [B<-engine id>] [B<-r>] +[B<-certs>] +[B<-keys>] +[B<-crls>] B ... =head1 DESCRIPTION @@ -60,6 +63,16 @@ The engine will then be set as the default for all available algorithms. Fetch objects recursively when possible. +=item B<-certs> + +=item B<-keys> + +=item B<-crls> + +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. + =back =head1 SEE ALSO @@ -72,7 +85,7 @@ B B was added to OpenSSL 1.1.1. =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/doc/man3/OSSL_STORE_LOADER.pod b/doc/man3/OSSL_STORE_LOADER.pod index 0bdd1124b6..aa64f2d773 100644 --- a/doc/man3/OSSL_STORE_LOADER.pod +++ b/doc/man3/OSSL_STORE_LOADER.pod @@ -5,10 +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_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_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 @@ -37,6 +39,9 @@ unregister STORE loaders for different URI schemes va_list args); int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader, OSSL_STORE_ctrl_fn store_ctrl_function); + 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 OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx, UI_METHOD *ui_method, void *ui_data); @@ -71,9 +76,9 @@ OSSL_STORE_close() for this scheme. B is a type template, to be defined by each loader using B. -B, B, B, -B and B are the function pointer -types used within a STORE loader. +B, 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. =over 4 @@ -108,6 +113,15 @@ numbers. This function is expected to return 1 on success, 0 on error. +=item B + +This function takes a B pointer and a B +identity B, and is used to tell the loader what object type is +expected. +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 @@ -161,6 +175,9 @@ B. OSSL_STORE_LOADER_set_ctrl() sets the control function for the B. +OSSL_STORE_LOADER_set_expect() sets the expect function for the +B. + OSSL_STORE_LOADER_set_load() sets the loader function for the B. @@ -186,9 +203,10 @@ The B scheme has built in support. =head1 RETURN VALUES The functions with the types B, B, +B, B, B and B have the -same return values as OSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof() and -OSSL_STORE_close(), respectively. +same return values as OSSL_STORE_open(), OSSL_STORE_ctrl(), OSSL_STORE_expect(), +OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close(), respectively. OSSL_STORE_LOADER_new() returns a pointer to a B on success, or B on failure. diff --git a/doc/man3/OSSL_STORE_expect.pod b/doc/man3/OSSL_STORE_expect.pod new file mode 100644 index 0000000000..ef97ec85c4 --- /dev/null +++ b/doc/man3/OSSL_STORE_expect.pod @@ -0,0 +1,58 @@ +=pod + +=head1 NAME + +OSSL_STORE_expect - Specify what object type is expected + +=head1 SYNOPSIS + + #include + + int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type); + +=head1 DESCRIPTION + +OSSL_STORE_expect() helps applications filter what OSSL_STORE_load() returns +by specifying a B type. +For example, if C contains several different objects +and only the certificates are interesting, the application can simply say +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. + +=head1 NOTES + +If a more elaborate filter is required by the application, a better choice +would be to use a post-processing function. +See L for more information. + +However, some loaders may take advantage of the knowledge of an expected type +to make object retrieval more efficient, so if a single type is expected, this +method is usually preferable. + +=head1 RETURN VALUES + +OSSL_STORE_expect() returns 1 on success, or 0 on failure. + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +OSSL_STORE_expect() +was 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/man7/ossl_store.pod b/doc/man7/ossl_store.pod index 71cb27d07f..80debebafc 100644 --- a/doc/man7/ossl_store.pod +++ b/doc/man7/ossl_store.pod @@ -86,7 +86,8 @@ only). =head1 SEE ALSO -L, L, L +L, L, +L, L =head1 COPYRIGHT diff --git a/util/private.num b/util/private.num index 099a4f70a8..48665577c9 100644 --- a/util/private.num +++ b/util/private.num @@ -33,6 +33,7 @@ OSSL_STORE_LOADER datatype OSSL_STORE_LOADER_CTX datatype OSSL_STORE_close_fn datatype OSSL_STORE_ctrl_fn datatype +OSSL_STORE_expect_fn datatype OSSL_STORE_eof_fn datatype OSSL_STORE_error_fn datatype OSSL_STORE_load_fn datatype -- GitLab