]>
Commit | Line | Data |
---|---|---|
4e46a7af RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | X509_LOOKUP, X509_LOOKUP_TYPE, | |
6 | X509_LOOKUP_new, X509_LOOKUP_free, X509_LOOKUP_init, | |
7 | X509_LOOKUP_shutdown, | |
8 | X509_LOOKUP_set_method_data, X509_LOOKUP_get_method_data, | |
d8652be0 MC |
9 | X509_LOOKUP_ctrl_ex, X509_LOOKUP_ctrl, |
10 | X509_LOOKUP_load_file_ex, X509_LOOKUP_load_file, | |
6725682d | 11 | X509_LOOKUP_add_dir, |
d8652be0 MC |
12 | X509_LOOKUP_add_store_ex, X509_LOOKUP_add_store, |
13 | X509_LOOKUP_load_store_ex, X509_LOOKUP_load_store, | |
6725682d | 14 | X509_LOOKUP_get_store, |
d8652be0 | 15 | X509_LOOKUP_by_subject_ex, X509_LOOKUP_by_subject, |
4e46a7af RL |
16 | X509_LOOKUP_by_issuer_serial, X509_LOOKUP_by_fingerprint, |
17 | X509_LOOKUP_by_alias | |
18 | - OpenSSL certificate lookup mechanisms | |
19 | ||
20 | =head1 SYNOPSIS | |
21 | ||
22 | #include <openssl/x509_vfy.h> | |
23 | ||
24 | typedef x509_lookup_st X509_LOOKUP; | |
25 | ||
26 | typedef enum X509_LOOKUP_TYPE; | |
27 | ||
28 | X509_LOOKUP *X509_LOOKUP_new(X509_LOOKUP_METHOD *method); | |
29 | int X509_LOOKUP_init(X509_LOOKUP *ctx); | |
30 | int X509_LOOKUP_shutdown(X509_LOOKUP *ctx); | |
31 | void X509_LOOKUP_free(X509_LOOKUP *ctx); | |
32 | ||
33 | int X509_LOOKUP_set_method_data(X509_LOOKUP *ctx, void *data); | |
34 | void *X509_LOOKUP_get_method_data(const X509_LOOKUP *ctx); | |
35 | ||
d8652be0 | 36 | int X509_LOOKUP_ctrl_ex(X509_LOOKUP *ctx, int cmd, const char *argc, long argl, |
b4250010 | 37 | char **ret, OSSL_LIB_CTX *libctx, const char *propq); |
4e46a7af RL |
38 | int X509_LOOKUP_ctrl(X509_LOOKUP *ctx, int cmd, const char *argc, |
39 | long argl, char **ret); | |
d8652be0 | 40 | int X509_LOOKUP_load_file_ex(X509_LOOKUP *ctx, char *name, long type, |
b4250010 | 41 | OSSL_LIB_CTX *libctx, const char *propq); |
4e46a7af | 42 | int X509_LOOKUP_load_file(X509_LOOKUP *ctx, char *name, long type); |
d8652be0 | 43 | int X509_LOOKUP_load_file_ex(X509_LOOKUP *ctx, char *name, long type, |
b4250010 | 44 | OSSL_LIB_CTX *libctx, const char *propq); |
4e46a7af | 45 | int X509_LOOKUP_add_dir(X509_LOOKUP *ctx, char *name, long type); |
b4250010 | 46 | int X509_LOOKUP_add_store_ex(X509_LOOKUP *ctx, char *uri, OSSL_LIB_CTX *libctx, |
d8652be0 | 47 | const char *propq); |
4e46a7af | 48 | int X509_LOOKUP_add_store(X509_LOOKUP *ctx, char *uri); |
b4250010 | 49 | int X509_LOOKUP_load_store_ex(X509_LOOKUP *ctx, char *uri, OSSL_LIB_CTX *libctx, |
d8652be0 | 50 | const char *propq); |
4e46a7af RL |
51 | int X509_LOOKUP_load_store(X509_LOOKUP *ctx, char *uri); |
52 | ||
53 | X509_STORE *X509_LOOKUP_get_store(const X509_LOOKUP *ctx); | |
54 | ||
d8652be0 MC |
55 | int X509_LOOKUP_by_subject_ex(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, |
56 | const X509_NAME *name, X509_OBJECT *ret, | |
b4250010 | 57 | OSSL_LIB_CTX *libctx, const char *propq); |
4e46a7af | 58 | int X509_LOOKUP_by_subject(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, |
8cc86b81 | 59 | const X509_NAME *name, X509_OBJECT *ret); |
4e46a7af | 60 | int X509_LOOKUP_by_issuer_serial(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, |
8cc86b81 DDO |
61 | const X509_NAME *name, |
62 | const ASN1_INTEGER *serial, X509_OBJECT *ret); | |
4e46a7af RL |
63 | int X509_LOOKUP_by_fingerprint(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, |
64 | const unsigned char *bytes, int len, | |
65 | X509_OBJECT *ret); | |
66 | int X509_LOOKUP_by_alias(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, | |
67 | const char *str, int len, X509_OBJECT *ret); | |
68 | ||
69 | =head1 DESCRIPTION | |
70 | ||
71 | The B<X509_LOOKUP> structure holds the information needed to look up | |
72 | certificates and CRLs according to an associated L<X509_LOOKUP_METHOD(3)>. | |
73 | Multiple B<X509_LOOKUP> instances can be added to an L<X509_STORE(3)> | |
74 | to enable lookup in that store. | |
75 | ||
76 | X509_LOOKUP_new() creates a new B<X509_LOOKUP> using the given lookup | |
77 | I<method>. | |
78 | It can also be created by calling L<X509_STORE_add_lookup(3)>, which | |
79 | will associate a B<X509_STORE> with the lookup mechanism. | |
80 | ||
81 | X509_LOOKUP_init() initializes the internal state and resources as | |
82 | needed by the given B<X509_LOOKUP> to do its work. | |
83 | ||
84 | X509_LOOKUP_shutdown() tears down the internal state and resources of | |
85 | the given B<X509_LOOKUP>. | |
86 | ||
87 | X509_LOOKUP_free() destructs the given B<X509_LOOKUP>. | |
88 | ||
89 | X509_LOOKUP_set_method_data() and X509_LOOKUP_get_method_data() | |
90 | associates and retrieves a pointer to application data to and from the | |
91 | given B<X509_LOOKUP>, respectively. | |
92 | ||
d8652be0 | 93 | X509_LOOKUP_ctrl_ex() is used to set or get additional data to or from |
0ce8271c DDO |
94 | a B<X509_LOOKUP> structure using any control function in the |
95 | associated L<X509_LOOKUP_METHOD(3)>. | |
4e46a7af | 96 | The arguments of the control command are passed via I<argc> and I<argl>, |
6725682d | 97 | its return value via I<*ret>. The library context I<libctx> and property |
bea31afe | 98 | query I<propq> are used when fetching algorithms from providers. |
4e46a7af RL |
99 | The meaning of the arguments depends on the I<cmd> number of the |
100 | control command. In general, this function is not called directly, but | |
101 | wrapped by a macro call, see below. | |
102 | The control I<cmd>s known to OpenSSL are discussed in more depth | |
103 | in L</Control Commands>. | |
104 | ||
d8652be0 | 105 | X509_LOOKUP_ctrl() is similar to X509_LOOKUP_ctrl_ex() but |
bea31afe | 106 | uses NULL for the library context I<libctx> and property query I<propq>. |
6725682d | 107 | |
d8652be0 | 108 | X509_LOOKUP_load_file_ex() passes a filename to be loaded immediately |
6725682d | 109 | into the associated B<X509_STORE>. The library context I<libctx> and property |
bea31afe | 110 | query I<propq> are used when fetching algorithms from providers. |
4e46a7af RL |
111 | I<type> indicates what type of object is expected. |
112 | This can only be used with a lookup using the implementation | |
113 | L<X509_LOOKUP_file(3)>. | |
114 | ||
d8652be0 | 115 | X509_LOOKUP_load_file() is similar to X509_LOOKUP_load_file_ex() but |
bea31afe | 116 | uses NULL for the library context I<libctx> and property query I<propq>. |
6725682d | 117 | |
4e46a7af RL |
118 | X509_LOOKUP_add_dir() passes a directory specification from which |
119 | certificates and CRLs are loaded on demand into the associated | |
120 | B<X509_STORE>. | |
121 | I<type> indicates what type of object is expected. | |
122 | This can only be used with a lookup using the implementation | |
123 | L<X509_LOOKUP_hash_dir(3)>. | |
124 | ||
d8652be0 | 125 | X509_LOOKUP_add_store_ex() passes a URI for a directory-like structure |
4e46a7af | 126 | from which containers with certificates and CRLs are loaded on demand |
6725682d | 127 | into the associated B<X509_STORE>. The library context I<libctx> and property |
bea31afe | 128 | query I<propq> are used when fetching algorithms from providers. |
6725682d | 129 | |
d8652be0 | 130 | X509_LOOKUP_add_store() is similar to X509_LOOKUP_add_store_ex() but |
bea31afe | 131 | uses NULL for the library context I<libctx> and property query I<propq>. |
6725682d | 132 | |
d8652be0 | 133 | X509_LOOKUP_load_store_ex() passes a URI for a single container from |
4e46a7af | 134 | which certificates and CRLs are immediately loaded into the associated |
bea31afe | 135 | B<X509_STORE>. The library context I<libctx> and property query I<propq> are used |
6725682d | 136 | when fetching algorithms from providers. |
4e46a7af RL |
137 | These functions can only be used with a lookup using the |
138 | implementation L<X509_LOOKUP_store(3)>. | |
139 | ||
d8652be0 | 140 | X509_LOOKUP_load_store() is similar to X509_LOOKUP_load_store_ex() but |
bea31afe | 141 | uses NULL for the library context I<libctx> and property query I<propq>. |
4e46a7af | 142 | |
d8652be0 | 143 | X509_LOOKUP_load_file_ex(), X509_LOOKUP_load_file(), |
6725682d | 144 | X509_LOOKUP_add_dir(), |
d8652be0 MC |
145 | X509_LOOKUP_add_store_ex() X509_LOOKUP_add_store(), |
146 | X509_LOOKUP_load_store_ex() and X509_LOOKUP_load_store() are | |
6725682d SL |
147 | implemented as macros that use X509_LOOKUP_ctrl(). |
148 | ||
d8652be0 | 149 | X509_LOOKUP_by_subject_ex(), X509_LOOKUP_by_subject(), |
6725682d SL |
150 | X509_LOOKUP_by_issuer_serial(), X509_LOOKUP_by_fingerprint(), and |
151 | X509_LOOKUP_by_alias() look up certificates and CRLs in the L<X509_STORE(3)> | |
152 | associated with the B<X509_LOOKUP> using different criteria, where the looked up | |
153 | object is stored in I<ret>. | |
4e46a7af RL |
154 | Some of the underlying B<X509_LOOKUP_METHOD>s will also cache objects |
155 | matching the criteria in the associated B<X509_STORE>, which makes it | |
156 | possible to handle cases where the criteria have more than one hit. | |
157 | ||
158 | =head2 Control Commands | |
159 | ||
6725682d | 160 | The B<X509_LOOKUP_METHOD>s built into OpenSSL recognize the following |
4e46a7af RL |
161 | X509_LOOKUP_ctrl() I<cmd>s: |
162 | ||
163 | =over 4 | |
164 | ||
165 | =item B<X509_L_FILE_LOAD> | |
166 | ||
d8652be0 | 167 | This is the command that X509_LOOKUP_load_file_ex() and |
6725682d | 168 | X509_LOOKUP_load_file() use. |
4e46a7af RL |
169 | The filename is passed in I<argc>, and the type in I<argl>. |
170 | ||
171 | =item B<X509_L_ADD_DIR> | |
172 | ||
173 | This is the command that X509_LOOKUP_add_dir() uses. | |
174 | The directory specification is passed in I<argc>, and the type in | |
175 | I<argl>. | |
176 | ||
177 | =item B<X509_L_ADD_STORE> | |
178 | ||
d8652be0 | 179 | This is the command that X509_LOOKUP_add_store_ex() and |
6725682d | 180 | X509_LOOKUP_add_store() use. |
4e46a7af RL |
181 | The URI is passed in I<argc>. |
182 | ||
183 | =item B<X509_L_LOAD_STORE> | |
184 | ||
d8652be0 | 185 | This is the command that X509_LOOKUP_load_store_ex() and |
6725682d | 186 | X509_LOOKUP_load_store() use. |
4e46a7af RL |
187 | The URI is passed in I<argc>. |
188 | ||
189 | =back | |
190 | ||
191 | =head1 RETURN VALUES | |
192 | ||
193 | X509_LOOKUP_new() returns a B<X509_LOOKUP> pointer when successful, | |
194 | or NULL on error. | |
195 | ||
196 | X509_LOOKUP_init() and X509_LOOKUP_shutdown() return 1 on success, or | |
197 | 0 on error. | |
198 | ||
0ce8271c DDO |
199 | X509_LOOKUP_ctrl_ex() and X509_LOOKUP_ctrl() |
200 | return -1 if the B<X509_LOOKUP> doesn't have an | |
4e46a7af RL |
201 | associated B<X509_LOOKUP_METHOD>, or 1 if the X<509_LOOKUP_METHOD> |
202 | doesn't have a control function. | |
203 | Otherwise, it returns what the control function in the | |
0ce8271c DDO |
204 | B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 on error |
205 | but could also be -1 on failure. | |
4e46a7af RL |
206 | |
207 | X509_LOOKUP_get_store() returns a B<X509_STORE> pointer if there is | |
208 | one, otherwise NULL. | |
209 | ||
0ce8271c DDO |
210 | X509_LOOKUP_by_subject_ex() returns 0 if there is no B<X509_LOOKUP_METHOD> |
211 | that implements any of the get_by_subject_ex() or get_by_subject() functions. | |
212 | It calls get_by_subject_ex() if present, otherwise get_by_subject(), and returns | |
213 | the result of the function, which is usually 1 on success and 0 on error. | |
214 | ||
215 | X509_LOOKUP_by_subject() is similar to X509_LOOKUP_by_subject_ex() | |
216 | but passes NULL for both the libctx and propq. | |
217 | ||
6725682d SL |
218 | X509_LOOKUP_by_issuer_serial(), X509_LOOKUP_by_fingerprint(), and |
219 | X509_LOOKUP_by_alias() all return 0 if there is no B<X509_LOOKUP_METHOD> or that | |
220 | method doesn't implement the corresponding function. | |
0ce8271c | 221 | Otherwise, they return what the corresponding function in the |
4e46a7af RL |
222 | B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in |
223 | error. | |
224 | ||
225 | =head1 SEE ALSO | |
226 | ||
227 | L<X509_LOOKUP_METHOD(3)>, L<X509_STORE(3)> | |
228 | ||
6725682d SL |
229 | =head1 HISTORY |
230 | ||
d8652be0 MC |
231 | The functions X509_LOOKUP_by_subject_ex() and |
232 | X509_LOOKUP_ctrl_ex() were added in OpenSSL 3.0. | |
6725682d | 233 | |
d8652be0 | 234 | The macros X509_LOOKUP_load_file_ex(), |
746f3674 | 235 | X509_LOOKUP_load_store_ex() and 509_LOOKUP_add_store_ex() were |
6725682d SL |
236 | added in OpenSSL 3.0. |
237 | ||
4e46a7af RL |
238 | =head1 COPYRIGHT |
239 | ||
0789c7d8 | 240 | Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. |
4e46a7af RL |
241 | |
242 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
243 | this file except in compliance with the License. You can obtain a copy | |
244 | in the file LICENSE in the source distribution or at | |
245 | L<https://www.openssl.org/source/license.html>. | |
246 | ||
247 | =cut |