]>
Commit | Line | Data |
---|---|---|
ce9586b9 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
6ab6decc RL |
5 | OSSL_STORE_expect, |
6 | OSSL_STORE_supports_search, | |
7 | OSSL_STORE_find | |
8 | - Specify what object type is expected | |
ce9586b9 RL |
9 | |
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/store.h> | |
13 | ||
14 | int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type); | |
15 | ||
6ab6decc | 16 | int OSSL_STORE_supports_search(OSSL_STORE_CTX *ctx, int criterion_type); |
379cc089 | 17 | |
6ab6decc RL |
18 | int OSSL_STORE_find(OSSL_STORE_CTX *ctx, OSSL_STORE_SEARCH *search); |
19 | ||
ce9586b9 RL |
20 | =head1 DESCRIPTION |
21 | ||
22 | OSSL_STORE_expect() helps applications filter what OSSL_STORE_load() returns | |
23 | by specifying a B<OSSL_STORE_INFO> type. | |
24 | For example, if C<file:/foo/bar/store.pem> contains several different objects | |
25 | and only the certificates are interesting, the application can simply say | |
26 | that it expects the type B<OSSL_STORE_INFO_CERT>. | |
27 | All known object types (see L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS>) | |
28 | except for B<OSSL_STORE_INFO_NAME> are supported. | |
29 | ||
6ab6decc RL |
30 | OSSL_STORE_find() helps applications specify a criterion for a more fine |
31 | grained search of objects. | |
32 | ||
33 | OSSL_STORE_supports_search() checks if the loader of the given OSSL_STORE | |
34 | context supports the given search type. | |
c2969ff6 | 35 | See L<OSSL_STORE_SEARCH/SUPPORTED CRITERION TYPES> for information on the |
6ab6decc RL |
36 | supported search criterion types. |
37 | ||
38 | OSSL_STORE_expect() and OSSL_STORE_find I<must> be called before the first | |
39 | OSSL_STORE_load() of a given session, or they will fail. | |
ce9586b9 RL |
40 | |
41 | =head1 NOTES | |
42 | ||
43 | If a more elaborate filter is required by the application, a better choice | |
44 | would be to use a post-processing function. | |
45 | See L<OSSL_STORE_open(3)> for more information. | |
46 | ||
47 | However, some loaders may take advantage of the knowledge of an expected type | |
48 | to make object retrieval more efficient, so if a single type is expected, this | |
49 | method is usually preferable. | |
50 | ||
51 | =head1 RETURN VALUES | |
52 | ||
53 | OSSL_STORE_expect() returns 1 on success, or 0 on failure. | |
54 | ||
6ab6decc RL |
55 | OSSL_STORE_supports_search() returns 1 if the criterion is supported, or 0 |
56 | otherwise. | |
57 | ||
58 | OSSL_STORE_find() returns 1 on success, or 0 on failure. | |
59 | ||
ce9586b9 RL |
60 | =head1 SEE ALSO |
61 | ||
6ab6decc RL |
62 | L<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_SEARCH(3)>, |
63 | L<OSSL_STORE_load(3)> | |
ce9586b9 RL |
64 | |
65 | =head1 HISTORY | |
66 | ||
6ab6decc | 67 | OSSL_STORE_expect(), OSSL_STORE_supports_search() and OSSL_STORE_find() |
fc5ecadd | 68 | were added in OpenSSL 1.1.1. |
ce9586b9 RL |
69 | |
70 | =head1 COPYRIGHT | |
71 | ||
72 | Copyright 2018 The OpenSSL Project Authors. All Rights Reserved. | |
73 | ||
4746f25a | 74 | Licensed under the Apache License 2.0 (the "License"). You may not use |
ce9586b9 RL |
75 | this file except in compliance with the License. You can obtain a copy |
76 | in the file LICENSE in the source distribution or at | |
77 | L<https://www.openssl.org/source/license.html>. | |
78 | ||
79 | =cut |