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