提交 ce9586b9 编写于 作者: R Richard Levitte

STORE: Add documentation on expecting specific infos

Reviewed-by: NMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/2688)
上级 9511d973
......@@ -15,6 +15,9 @@ B<openssl> B<storeutl>
[B<-text arg>]
[B<-engine id>]
[B<-r>]
[B<-certs>]
[B<-keys>]
[B<-crls>]
B<uri> ...
=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<openssl> B<storeutl> 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
......
......@@ -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<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_load_fn>,
B<OSSL_STORE_eof_fn> and B<OSSL_STORE_close_fn> are the function pointer
types used within a STORE loader.
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>
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<OSSL_STORE_expect_fn>
This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<OSSL_STORE_INFO>
identity B<expected>, and is used to tell the loader what object type is
expected.
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_load_fn>
This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<UI_METHOD>
......@@ -161,6 +175,9 @@ B<store_loader>.
OSSL_STORE_LOADER_set_ctrl() sets the control function for the
B<store_loader>.
OSSL_STORE_LOADER_set_expect() sets the expect function for the
B<store_loader>.
OSSL_STORE_LOADER_set_load() sets the loader function for the
B<store_loader>.
......@@ -186,9 +203,10 @@ The B<file:> scheme has built in support.
=head1 RETURN VALUES
The functions with the types 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> 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<OSSL_STORE_LOADER> on success,
or B<NULL> on failure.
......
=pod
=head1 NAME
OSSL_STORE_expect - Specify what object type is expected
=head1 SYNOPSIS
#include <openssl/store.h>
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<OSSL_STORE_INFO> type.
For example, if C<file:/foo/bar/store.pem> contains several different objects
and only the certificates are interesting, the application can simply say
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.
=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<OSSL_STORE_open(3)> 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<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_load(3)>
=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<https://www.openssl.org/source/license.html>.
=cut
......@@ -86,7 +86,8 @@ only).
=head1 SEE ALSO
L<OSSL_STORE_open(3)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>
L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>,
L<OSSL_STORE_open(3)>, L<OSSL_STORE_expect(3)>
=head1 COPYRIGHT
......
......@@ -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
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册