]>
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 MC |
36 | int X509_LOOKUP_ctrl_ex(X509_LOOKUP *ctx, int cmd, const char *argc, long argl, |
37 | char **ret, OPENSSL_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 MC |
40 | int X509_LOOKUP_load_file_ex(X509_LOOKUP *ctx, char *name, long type, |
41 | OPENSSL_CTX *libctx, const char *propq); | |
4e46a7af | 42 | int X509_LOOKUP_load_file(X509_LOOKUP *ctx, char *name, long type); |
d8652be0 MC |
43 | int X509_LOOKUP_load_file_ex(X509_LOOKUP *ctx, char *name, long type, |
44 | OPENSSL_CTX *libctx, const char *propq); | |
4e46a7af | 45 | int X509_LOOKUP_add_dir(X509_LOOKUP *ctx, char *name, long type); |
d8652be0 MC |
46 | int X509_LOOKUP_add_store_ex(X509_LOOKUP *ctx, char *uri, OPENSSL_CTX *libctx, |
47 | const char *propq); | |
4e46a7af | 48 | int X509_LOOKUP_add_store(X509_LOOKUP *ctx, char *uri); |
d8652be0 MC |
49 | int X509_LOOKUP_load_store_ex(X509_LOOKUP *ctx, char *uri, OPENSSL_CTX *libctx, |
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, | |
57 | OPENSSL_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 |
6725682d | 94 | a B<X509_LOOKUP> structure or its associated L<X509_LOOKUP_METHOD(3)>. |
4e46a7af | 95 | The arguments of the control command are passed via I<argc> and I<argl>, |
6725682d SL |
96 | its return value via I<*ret>. The library context I<libctx> and property |
97 | query <propq> are used when fetching algorithms from providers. | |
4e46a7af RL |
98 | The meaning of the arguments depends on the I<cmd> number of the |
99 | control command. In general, this function is not called directly, but | |
100 | wrapped by a macro call, see below. | |
101 | The control I<cmd>s known to OpenSSL are discussed in more depth | |
102 | in L</Control Commands>. | |
103 | ||
d8652be0 | 104 | X509_LOOKUP_ctrl() is similar to X509_LOOKUP_ctrl_ex() but |
6725682d SL |
105 | uses NULL for the library context I<libctx> and property query <propq>. |
106 | ||
d8652be0 | 107 | X509_LOOKUP_load_file_ex() passes a filename to be loaded immediately |
6725682d SL |
108 | into the associated B<X509_STORE>. The library context I<libctx> and property |
109 | query <propq> are used when fetching algorithms from providers. | |
4e46a7af RL |
110 | I<type> indicates what type of object is expected. |
111 | This can only be used with a lookup using the implementation | |
112 | L<X509_LOOKUP_file(3)>. | |
113 | ||
d8652be0 | 114 | X509_LOOKUP_load_file() is similar to X509_LOOKUP_load_file_ex() but |
6725682d SL |
115 | uses NULL for the library context I<libctx> and property query <propq>. |
116 | ||
4e46a7af RL |
117 | X509_LOOKUP_add_dir() passes a directory specification from which |
118 | certificates and CRLs are loaded on demand into the associated | |
119 | B<X509_STORE>. | |
120 | I<type> indicates what type of object is expected. | |
121 | This can only be used with a lookup using the implementation | |
122 | L<X509_LOOKUP_hash_dir(3)>. | |
123 | ||
d8652be0 | 124 | X509_LOOKUP_add_store_ex() passes a URI for a directory-like structure |
4e46a7af | 125 | from which containers with certificates and CRLs are loaded on demand |
6725682d SL |
126 | into the associated B<X509_STORE>. The library context I<libctx> and property |
127 | query <propq> are used when fetching algorithms from providers. | |
128 | ||
d8652be0 | 129 | X509_LOOKUP_add_store() is similar to X509_LOOKUP_add_store_ex() but |
6725682d SL |
130 | uses NULL for the library context I<libctx> and property query <propq>. |
131 | ||
d8652be0 | 132 | X509_LOOKUP_load_store_ex() passes a URI for a single container from |
4e46a7af | 133 | which certificates and CRLs are immediately loaded into the associated |
6725682d SL |
134 | B<X509_STORE>. The library context I<libctx> and property query <propq> are used |
135 | when fetching algorithms from providers. | |
4e46a7af RL |
136 | These functions can only be used with a lookup using the |
137 | implementation L<X509_LOOKUP_store(3)>. | |
138 | ||
d8652be0 | 139 | X509_LOOKUP_load_store() is similar to X509_LOOKUP_load_store_ex() but |
6725682d | 140 | uses NULL for the library context I<libctx> and property query <propq>. |
4e46a7af | 141 | |
d8652be0 | 142 | X509_LOOKUP_load_file_ex(), X509_LOOKUP_load_file(), |
6725682d | 143 | X509_LOOKUP_add_dir(), |
d8652be0 MC |
144 | X509_LOOKUP_add_store_ex() X509_LOOKUP_add_store(), |
145 | X509_LOOKUP_load_store_ex() and X509_LOOKUP_load_store() are | |
6725682d SL |
146 | implemented as macros that use X509_LOOKUP_ctrl(). |
147 | ||
d8652be0 | 148 | X509_LOOKUP_by_subject_ex(), X509_LOOKUP_by_subject(), |
6725682d SL |
149 | X509_LOOKUP_by_issuer_serial(), X509_LOOKUP_by_fingerprint(), and |
150 | X509_LOOKUP_by_alias() look up certificates and CRLs in the L<X509_STORE(3)> | |
151 | associated with the B<X509_LOOKUP> using different criteria, where the looked up | |
152 | object is stored in I<ret>. | |
4e46a7af RL |
153 | Some of the underlying B<X509_LOOKUP_METHOD>s will also cache objects |
154 | matching the criteria in the associated B<X509_STORE>, which makes it | |
155 | possible to handle cases where the criteria have more than one hit. | |
156 | ||
157 | =head2 Control Commands | |
158 | ||
6725682d | 159 | The B<X509_LOOKUP_METHOD>s built into OpenSSL recognize the following |
4e46a7af RL |
160 | X509_LOOKUP_ctrl() I<cmd>s: |
161 | ||
162 | =over 4 | |
163 | ||
164 | =item B<X509_L_FILE_LOAD> | |
165 | ||
d8652be0 | 166 | This is the command that X509_LOOKUP_load_file_ex() and |
6725682d | 167 | X509_LOOKUP_load_file() use. |
4e46a7af RL |
168 | The filename is passed in I<argc>, and the type in I<argl>. |
169 | ||
170 | =item B<X509_L_ADD_DIR> | |
171 | ||
172 | This is the command that X509_LOOKUP_add_dir() uses. | |
173 | The directory specification is passed in I<argc>, and the type in | |
174 | I<argl>. | |
175 | ||
176 | =item B<X509_L_ADD_STORE> | |
177 | ||
d8652be0 | 178 | This is the command that X509_LOOKUP_add_store_ex() and |
6725682d | 179 | X509_LOOKUP_add_store() use. |
4e46a7af RL |
180 | The URI is passed in I<argc>. |
181 | ||
182 | =item B<X509_L_LOAD_STORE> | |
183 | ||
d8652be0 | 184 | This is the command that X509_LOOKUP_load_store_ex() and |
6725682d | 185 | X509_LOOKUP_load_store() use. |
4e46a7af RL |
186 | The URI is passed in I<argc>. |
187 | ||
188 | =back | |
189 | ||
190 | =head1 RETURN VALUES | |
191 | ||
192 | X509_LOOKUP_new() returns a B<X509_LOOKUP> pointer when successful, | |
193 | or NULL on error. | |
194 | ||
195 | X509_LOOKUP_init() and X509_LOOKUP_shutdown() return 1 on success, or | |
196 | 0 on error. | |
197 | ||
198 | X509_LOOKUP_ctrl() returns -1 if the B<X509_LOOKUP> doesn't have an | |
199 | associated B<X509_LOOKUP_METHOD>, or 1 if the X<509_LOOKUP_METHOD> | |
200 | doesn't have a control function. | |
201 | Otherwise, it returns what the control function in the | |
202 | B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in | |
203 | error. | |
204 | ||
205 | X509_LOOKUP_get_store() returns a B<X509_STORE> pointer if there is | |
206 | one, otherwise NULL. | |
207 | ||
d8652be0 | 208 | X509_LOOKUP_by_subject_ex(), X509_LOOKUP_by_subject(), |
6725682d SL |
209 | X509_LOOKUP_by_issuer_serial(), X509_LOOKUP_by_fingerprint(), and |
210 | X509_LOOKUP_by_alias() all return 0 if there is no B<X509_LOOKUP_METHOD> or that | |
211 | method doesn't implement the corresponding function. | |
4e46a7af RL |
212 | Otherwise, it returns what the corresponding function in the |
213 | B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in | |
214 | error. | |
215 | ||
216 | =head1 SEE ALSO | |
217 | ||
218 | L<X509_LOOKUP_METHOD(3)>, L<X509_STORE(3)> | |
219 | ||
6725682d SL |
220 | =head1 HISTORY |
221 | ||
d8652be0 MC |
222 | The functions X509_LOOKUP_by_subject_ex() and |
223 | X509_LOOKUP_ctrl_ex() were added in OpenSSL 3.0. | |
6725682d | 224 | |
d8652be0 MC |
225 | The macros X509_LOOKUP_load_file_ex(), |
226 | X509_LOOKUP_load_store_with_libctx() and 509_LOOKUP_add_store_ex() were | |
6725682d SL |
227 | added in OpenSSL 3.0. |
228 | ||
4e46a7af RL |
229 | =head1 COPYRIGHT |
230 | ||
231 | Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. | |
232 | ||
233 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
234 | this file except in compliance with the License. You can obtain a copy | |
235 | in the file LICENSE in the source distribution or at | |
236 | L<https://www.openssl.org/source/license.html>. | |
237 | ||
238 | =cut |