]>
Commit | Line | Data |
---|---|---|
6ab6decc RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | OSSL_STORE_SEARCH, | |
6 | OSSL_STORE_SEARCH_by_name, | |
7 | OSSL_STORE_SEARCH_by_issuer_serial, | |
8 | OSSL_STORE_SEARCH_by_key_fingerprint, | |
9 | OSSL_STORE_SEARCH_by_alias, | |
10 | OSSL_STORE_SEARCH_free, | |
11 | OSSL_STORE_SEARCH_get_type, | |
12 | OSSL_STORE_SEARCH_get0_name, | |
13 | OSSL_STORE_SEARCH_get0_serial, | |
14 | OSSL_STORE_SEARCH_get0_bytes, | |
15 | OSSL_STORE_SEARCH_get0_string, | |
16 | OSSL_STORE_SEARCH_get0_digest | |
17 | - Type and functions to create OSSL_STORE search criteria | |
18 | ||
19 | =head1 SYNOPSIS | |
20 | ||
21 | #include <openssl/store.h> | |
22 | ||
23 | typedef struct ossl_store_search_st OSSL_STORE_SEARCH; | |
24 | ||
25 | OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_name(X509_NAME *name); | |
26 | OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_issuer_serial(X509_NAME *name, | |
27 | const ASN1_INTEGER | |
28 | *serial); | |
29 | OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_key_fingerprint(const EVP_MD *digest, | |
30 | const unsigned char | |
31 | *bytes, int len); | |
32 | OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_alias(const char *alias); | |
33 | ||
34 | void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search); | |
35 | ||
36 | int OSSL_STORE_SEARCH_get_type(const OSSL_STORE_SEARCH *criterion); | |
37 | X509_NAME *OSSL_STORE_SEARCH_get0_name(OSSL_STORE_SEARCH *criterion); | |
38 | const ASN1_INTEGER *OSSL_STORE_SEARCH_get0_serial(const OSSL_STORE_SEARCH | |
39 | *criterion); | |
40 | const unsigned char *OSSL_STORE_SEARCH_get0_bytes(const OSSL_STORE_SEARCH | |
41 | *criterion, size_t *length); | |
42 | const char *OSSL_STORE_SEARCH_get0_string(const OSSL_STORE_SEARCH *criterion); | |
43 | const EVP_MD *OSSL_STORE_SEARCH_get0_digest(const OSSL_STORE_SEARCH | |
44 | *criterion); | |
45 | ||
46 | =head1 DESCRIPTION | |
47 | ||
3266cf58 | 48 | These functions are used to specify search criteria to help search for specific |
6ab6decc RL |
49 | objects through other names than just the URI that's given to OSSL_STORE_open(). |
50 | For example, this can be useful for an application that has received a URI | |
51 | and then wants to add on search criteria in a uniform and supported manner. | |
52 | ||
53 | =head2 Types | |
54 | ||
55 | B<OSSL_STORE_SEARCH> is an opaque type that holds the constructed search | |
56 | criterion, and that can be given to an OSSL_STORE context with | |
57 | OSSL_STORE_find(). | |
58 | ||
59 | The calling application owns the allocation of an B<OSSL_STORE_SEARCH> at all | |
60 | times, and should therefore be careful not to deallocate it before | |
61 | OSSL_STORE_close() has been called for the OSSL_STORE context it was given | |
62 | to. | |
63 | ||
64 | =head2 Application Functions | |
65 | ||
66 | OSSL_STORE_SEARCH_by_name(), | |
67 | OSSL_STORE_SEARCH_by_issuer_serial(), | |
68 | OSSL_STORE_SEARCH_by_key_fingerprint(), | |
69 | and OSSL_STORE_SEARCH_by_alias() | |
70 | are used to create an B<OSSL_STORE_SEARCH> from a subject name, an issuer name | |
71 | and serial number pair, a key fingerprint, and an alias (for example a friendly | |
72 | name). | |
73 | The parameters that are provided are not copied, only referred to in a | |
74 | criterion, so they must have at least the same life time as the created | |
75 | B<OSSL_STORE_SEARCH>. | |
76 | ||
77 | OSSL_STORE_SEARCH_free() is used to free the B<OSSL_STORE_SEARCH>. | |
78 | ||
79 | =head2 Loader Functions | |
80 | ||
81 | OSSL_STORE_SEARCH_get_type() returns the criterion type for the given | |
82 | B<OSSL_STORE_SEARCH>. | |
83 | ||
84 | OSSL_STORE_SEARCH_get0_name(), OSSL_STORE_SEARCH_get0_serial(), | |
85 | OSSL_STORE_SEARCH_get0_bytes(), OSSL_STORE_SEARCH_get0_string(), | |
86 | and OSSL_STORE_SEARCH_get0_digest() | |
87 | are used to retrieve different data from a B<OSSL_STORE_SEARCH>, as | |
88 | available for each type. | |
89 | For more information, see L</SUPPORTED CRITERION TYPES> below. | |
90 | ||
91 | =head1 SUPPORTED CRITERION TYPES | |
92 | ||
93 | Currently supported criterion types are: | |
94 | ||
95 | =over 4 | |
96 | ||
97 | =item OSSL_STORE_SEARCH_BY_NAME | |
98 | ||
99 | This criterion supports a search by exact match of subject name. | |
100 | The subject name itself is a B<X509_NAME> pointer. | |
101 | A criterion of this type is created with OSSL_STORE_SEARCH_by_name(), | |
102 | and the actual subject name is retrieved with OSSL_STORE_SEARCH_get0_name(). | |
103 | ||
104 | =item OSSL_STORE_SEARCH_BY_ISSUER_SERIAL | |
105 | ||
106 | This criterion supports a search by exact match of both issuer name and serial | |
107 | number. | |
108 | The issuer name itself is a B<X509_NAME> pointer, and the serial number is | |
109 | a B<ASN1_INTEGER> pointer. | |
110 | A criterion of this type is created with OSSL_STORE_SEARCH_by_issuer_serial() | |
111 | and the actual issuer name and serial number are retrieved with | |
112 | OSSL_STORE_SEARCH_get0_name() and OSSL_STORE_SEARCH_get0_serial(). | |
113 | ||
114 | =item OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT | |
115 | ||
116 | This criterion supports a search by exact match of key fingerprint. | |
117 | The key fingerprint in itself is a string of bytes and its length, as | |
118 | well as the algorithm that was used to compute the fingerprint. | |
119 | The digest may be left unspecified (NULL), and in that case, the | |
120 | loader has to decide on a default digest and compare fingerprints | |
121 | accordingly. | |
122 | A criterion of this type is created with OSSL_STORE_SEARCH_by_key_fingerprint() | |
123 | and the actual fingerprint and its length can be retrieved with | |
124 | OSSL_STORE_SEARCH_get0_bytes(). | |
3266cf58 | 125 | The digest can be retrieved with OSSL_STORE_SEARCH_get0_digest(). |
6ab6decc RL |
126 | |
127 | =item OSSL_STORE_SEARCH_BY_ALIAS | |
128 | ||
129 | This criterion supports a search by match of an alias of some kind. | |
130 | The alias in itself is a simple C string. | |
131 | A criterion of this type is created with OSSL_STORE_SEARCH_by_alias() | |
132 | and the actual alias is retrieved with OSSL_STORE_SEARCH_get0_string(). | |
133 | ||
134 | =back | |
135 | ||
136 | =head1 RETURN VALUES | |
137 | ||
138 | OSSL_STORE_SEARCH_by_name(), | |
139 | OSSL_STORE_SEARCH_by_issuer_serial(), | |
140 | OSSL_STORE_SEARCH_by_key_fingerprint(), | |
141 | and OSSL_STORE_SEARCH_by_alias() | |
142 | return a B<OSSL_STORE_SEARCH> pointer on success, or B<NULL> on failure. | |
143 | ||
144 | OSSL_STORE_SEARCH_get_type() returns the criterion type of the given | |
145 | B<OSSL_STORE_SEARCH>. | |
146 | There is no error value. | |
147 | ||
148 | OSSL_STORE_SEARCH_get0_name() returns a B<X509_NAME> pointer on success, | |
149 | or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type. | |
150 | ||
151 | OSSL_STORE_SEARCH_get0_serial() returns a B<ASN1_INTEGER> pointer on success, | |
152 | or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type. | |
153 | ||
154 | OSSL_STORE_SEARCH_get0_bytes() returns a B<const unsigned char> pointer and | |
155 | sets B<*length> to the strings length on success, or B<NULL> when the given | |
156 | B<OSSL_STORE_SEARCH> was of a different type. | |
157 | ||
158 | OSSL_STORE_SEARCH_get0_string() returns a B<const char> pointer on success, | |
159 | or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type. | |
160 | ||
161 | OSSL_STORE_SEARCH_get0_digest() returns a B<const EVP_MD> pointer. | |
162 | B<NULL> is a valid value and means that the store loader default will | |
163 | be used when applicable. | |
164 | ||
165 | =head1 SEE ALSO | |
166 | ||
167 | L<ossl_store(7)>, L<OSSL_STORE_supports_search(3)>, L<OSSL_STORE_find(3)> | |
168 | ||
169 | =head1 HISTORY | |
170 | ||
171 | B<OSSL_STORE_SEARCH>, | |
172 | OSSL_STORE_SEARCH_by_name(), | |
173 | OSSL_STORE_SEARCH_by_issuer_serial(), | |
174 | OSSL_STORE_SEARCH_by_key_fingerprint(), | |
175 | OSSL_STORE_SEARCH_by_alias(), | |
176 | OSSL_STORE_SEARCH_free(), | |
177 | OSSL_STORE_SEARCH_get_type(), | |
178 | OSSL_STORE_SEARCH_get0_name(), | |
179 | OSSL_STORE_SEARCH_get0_serial(), | |
180 | OSSL_STORE_SEARCH_get0_bytes(), | |
181 | and OSSL_STORE_SEARCH_get0_string() | |
182 | were added to OpenSSL 1.1.1. | |
183 | ||
184 | =head1 COPYRIGHT | |
185 | ||
186 | Copyright 2018 The OpenSSL Project Authors. All Rights Reserved. | |
187 | ||
188 | Licensed under the OpenSSL license (the "License"). You may not use | |
189 | this file except in compliance with the License. You can obtain a copy | |
190 | in the file LICENSE in the source distribution or at | |
191 | L<https://www.openssl.org/source/license.html>. | |
192 | ||
193 | =cut |