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