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