xref: /freebsd/crypto/openssl/doc/man3/X509_LOOKUP.pod (revision e32fecd0c2c3ee37c47ee100f169e7eb0282a873) 
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,
10X509_LOOKUP_load_file, X509_LOOKUP_add_dir,
11X509_LOOKUP_get_store, X509_LOOKUP_by_subject,
12X509_LOOKUP_by_issuer_serial, X509_LOOKUP_by_fingerprint,
13X509_LOOKUP_by_alias
14- OpenSSL certificate lookup mechanisms
15
16=head1 SYNOPSIS
17
18 #include <openssl/x509_vfy.h>
19
20 typedef x509_lookup_st X509_LOOKUP;
21
22 typedef enum X509_LOOKUP_TYPE;
23
24 X509_LOOKUP *X509_LOOKUP_new(X509_LOOKUP_METHOD *method);
25 int X509_LOOKUP_init(X509_LOOKUP *ctx);
26 int X509_LOOKUP_shutdown(X509_LOOKUP *ctx);
27 void X509_LOOKUP_free(X509_LOOKUP *ctx);
28
29 int X509_LOOKUP_set_method_data(X509_LOOKUP *ctx, void *data);
30 void *X509_LOOKUP_get_method_data(const X509_LOOKUP *ctx);
31
32 int X509_LOOKUP_ctrl(X509_LOOKUP *ctx, int cmd, const char *argc,
33                      long argl, char **ret);
34 int X509_LOOKUP_load_file(X509_LOOKUP *ctx, char *name, long type);
35 int X509_LOOKUP_add_dir(X509_LOOKUP *ctx, char *name, long type);
36
37 X509_STORE *X509_LOOKUP_get_store(const X509_LOOKUP *ctx);
38
39 int X509_LOOKUP_by_subject(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
40                            X509_NAME *name, X509_OBJECT *ret);
41 int X509_LOOKUP_by_issuer_serial(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
42                                  X509_NAME *name, ASN1_INTEGER *serial,
43                                  X509_OBJECT *ret);
44 int X509_LOOKUP_by_fingerprint(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
45                                const unsigned char *bytes, int len,
46                                X509_OBJECT *ret);
47 int X509_LOOKUP_by_alias(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
48                          const char *str, int len, X509_OBJECT *ret);
49
50=head1 DESCRIPTION
51
52The B<X509_LOOKUP> structure holds the information needed to look up
53certificates and CRLs according to an associated L<X509_LOOKUP_METHOD(3)>.
54Multiple B<X509_LOOKUP> instances can be added to an L<X509_STORE(3)>
55to enable lookup in that store.
56
57X509_LOOKUP_new() creates a new B<X509_LOOKUP> using the given lookup
58I<method>.
59It can also be created by calling L<X509_STORE_add_lookup(3)>, which
60will associate an B<X509_STORE> with the lookup mechanism.
61
62X509_LOOKUP_init() initializes the internal state and resources as
63needed by the given B<X509_LOOKUP> to do its work.
64
65X509_LOOKUP_shutdown() tears down the internal state and resources of
66the given B<X509_LOOKUP>.
67
68X509_LOOKUP_free() destructs the given B<X509_LOOKUP>.
69
70X509_LOOKUP_set_method_data() associates a pointer to application data
71to the given B<X509_LOOKUP>.
72
73X509_LOOKUP_get_method_data() retrieves a pointer to application data
74from the given B<X509_LOOKUP>.
75
76X509_LOOKUP_ctrl() is used to set or get additional data to or from an
77B<X509_LOOKUP> structure or its associated L<X509_LOOKUP_METHOD(3)>.
78The arguments of the control command are passed via I<argc> and I<argl>,
79its return value via I<*ret>.
80The meaning of the arguments depends on the I<cmd> number of the
81control command. In general, this function is not called directly, but
82wrapped by a macro call, see below.
83The control I<cmd>s known to OpenSSL are discussed in more depth
84in L</Control Commands>.
85
86X509_LOOKUP_load_file() passes a filename to be loaded immediately
87into the associated B<X509_STORE>.
88I<type> indicates what type of object is expected.
89This can only be used with a lookup using the implementation
90L<X509_LOOKUP_file(3)>.
91
92X509_LOOKUP_add_dir() passes a directory specification from which
93certificates and CRLs are loaded on demand into the associated
94B<X509_STORE>.
95I<type> indicates what type of object is expected.
96This can only be used with a lookup using the implementation
97L<X509_LOOKUP_hash_dir(3)>.
98
99X509_LOOKUP_load_file(), X509_LOOKUP_add_dir(),
100X509_LOOKUP_add_store(), and X509_LOOKUP_load_store() are implemented
101as macros that use X509_LOOKUP_ctrl().
102
103X509_LOOKUP_by_subject(), X509_LOOKUP_by_issuer_serial(),
104X509_LOOKUP_by_fingerprint(), and X509_LOOKUP_by_alias() look up
105certificates and CRLs in the L<X509_STORE(3)> associated with the
106B<X509_LOOKUP> using different criteria, where the looked up object is
107stored in I<ret>.
108Some of the underlying B<X509_LOOKUP_METHOD>s will also cache objects
109matching the criteria in the associated B<X509_STORE>, which makes it
110possible to handle cases where the criteria have more than one hit.
111
112=head2 File Types
113
114X509_LOOKUP_load_file() and X509_LOOKUP_add_dir() take a I<type>,
115which can be one of the following:
116
117=over 4
118
119=item B<X509_FILETYPE_PEM>
120
121The file or files that are loaded are expected to be in PEM format.
122
123=item B<X509_FILETYPE_ASN1>
124
125The file or files that are loaded are expected to be in raw DER format.
126
127=item B<X509_FILETYPE_DEFAULT>
128
129The default certificate file or directory is used.  In this case,
130I<name> is ignored.
131
132=begin comment
133
134TODO
135Document X509_get_default_cert_file_env(3),
136X509_get_default_cert_file(3), X509_get_default_cert_dir_env(3) and
137X509_get_default_cert_dir(3) and link to them here.
138
139=end comment
140
141=back
142
143=head2 Control Commands
144
145The B<X509_LOOKUP_METHOD>s built into OpenSSL recognise the following
146X509_LOOKUP_ctrl() I<cmd>s:
147
148=over 4
149
150=item B<X509_L_FILE_LOAD>
151
152This is the command that X509_LOOKUP_load_file() uses.
153The filename is passed in I<argc>, and the type in I<argl>.
154
155=item B<X509_L_ADD_DIR>
156
157This is the command that X509_LOOKUP_add_dir() uses.
158The directory specification is passed in I<argc>, and the type in
159I<argl>.
160
161=item B<X509_L_ADD_STORE>
162
163This is the command that X509_LOOKUP_add_store() uses.
164The URI is passed in I<argc>.
165
166=item B<X509_L_LOAD_STORE>
167
168This is the command that X509_LOOKUP_load_store() uses.
169The URI is passed in I<argc>.
170
171=back
172
173=head1 RETURN VALUES
174
175X509_LOOKUP_new() returns an B<X509_LOOKUP> pointer when successful,
176or NULL on error.
177
178X509_LOOKUP_init() and X509_LOOKUP_shutdown() return 1 on success, or
1790 on error.
180
181X509_LOOKUP_ctrl() returns -1 if the B<X509_LOOKUP> doesn't have an
182associated B<X509_LOOKUP_METHOD>, or 1 if the X<509_LOOKUP_METHOD>
183doesn't have a control function.
184Otherwise, it returns what the control function in the
185B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in
186error.
187
188X509_LOOKUP_get_store() returns an B<X509_STORE> pointer if there is
189one, otherwise NULL.
190
191X509_LOOKUP_by_subject(), X509_LOOKUP_by_issuer_serial(),
192X509_LOOKUP_by_fingerprint(), and X509_LOOKUP_by_alias() all return 0
193if there is no B<X509_LOOKUP_METHOD> or that method doesn't implement
194the corresponding function.
195Otherwise, it returns what the corresponding function in the
196B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in
197error.
198
199=head1 SEE ALSO
200
201L<X509_LOOKUP_METHOD(3)>, L<X509_STORE(3)>
202
203=head1 COPYRIGHT
204
205Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
206
207Licensed under the Apache License 2.0 (the "License").  You may not use
208this file except in compliance with the License.  You can obtain a copy
209in the file LICENSE in the source distribution or at
210L<https://www.openssl.org/source/license.html>.
211
212=cut
213