X509_LOOKUP_get_store(3ossl)

1X509_LOOKUP(3ossl)                  OpenSSL                 X509_LOOKUP(3ossl)
2
3
4

NAME

6       X509_LOOKUP, X509_LOOKUP_TYPE, X509_LOOKUP_new, X509_LOOKUP_free,
7       X509_LOOKUP_init, X509_LOOKUP_shutdown, X509_LOOKUP_set_method_data,
8       X509_LOOKUP_get_method_data, X509_LOOKUP_ctrl_ex, X509_LOOKUP_ctrl,
9       X509_LOOKUP_load_file_ex, X509_LOOKUP_load_file, X509_LOOKUP_add_dir,
10       X509_LOOKUP_add_store_ex, X509_LOOKUP_add_store,
11       X509_LOOKUP_load_store_ex, X509_LOOKUP_load_store,
12       X509_LOOKUP_get_store, X509_LOOKUP_by_subject_ex,
13       X509_LOOKUP_by_subject, X509_LOOKUP_by_issuer_serial,
14       X509_LOOKUP_by_fingerprint, X509_LOOKUP_by_alias - OpenSSL certificate
15       lookup mechanisms
16

SYNOPSIS

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_ex(X509_LOOKUP *ctx, int cmd, const char *argc, long argl,
33                                char **ret, OSSL_LIB_CTX *libctx, const char *propq);
34        int X509_LOOKUP_ctrl(X509_LOOKUP *ctx, int cmd, const char *argc,
35                             long argl, char **ret);
36        int X509_LOOKUP_load_file_ex(X509_LOOKUP *ctx, char *name, long type,
37                                     OSSL_LIB_CTX *libctx, const char *propq);
38        int X509_LOOKUP_load_file(X509_LOOKUP *ctx, char *name, long type);
39        int X509_LOOKUP_load_file_ex(X509_LOOKUP *ctx, char *name, long type,
40                                     OSSL_LIB_CTX *libctx, const char *propq);
41        int X509_LOOKUP_add_dir(X509_LOOKUP *ctx, char *name, long type);
42        int X509_LOOKUP_add_store_ex(X509_LOOKUP *ctx, char *uri, OSSL_LIB_CTX *libctx,
43                                     const char *propq);
44        int X509_LOOKUP_add_store(X509_LOOKUP *ctx, char *uri);
45        int X509_LOOKUP_load_store_ex(X509_LOOKUP *ctx, char *uri, OSSL_LIB_CTX *libctx,
46                                      const char *propq);
47        int X509_LOOKUP_load_store(X509_LOOKUP *ctx, char *uri);
48
49        X509_STORE *X509_LOOKUP_get_store(const X509_LOOKUP *ctx);
50
51        int X509_LOOKUP_by_subject_ex(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
52                                      const X509_NAME *name, X509_OBJECT *ret,
53                                      OSSL_LIB_CTX *libctx, const char *propq);
54        int X509_LOOKUP_by_subject(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
55                                   const X509_NAME *name, X509_OBJECT *ret);
56        int X509_LOOKUP_by_issuer_serial(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
57                                         const X509_NAME *name,
58                                         const ASN1_INTEGER *serial, X509_OBJECT *ret);
59        int X509_LOOKUP_by_fingerprint(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
60                                       const unsigned char *bytes, int len,
61                                       X509_OBJECT *ret);
62        int X509_LOOKUP_by_alias(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
63                                 const char *str, int len, X509_OBJECT *ret);
64

DESCRIPTION

66       The X509_LOOKUP structure holds the information needed to look up
67       certificates and CRLs according to an associated X509_LOOKUP_METHOD(3).
68       Multiple X509_LOOKUP instances can be added to an X509_STORE(3) to
69       enable lookup in that store.
70
71       X509_LOOKUP_new() creates a new X509_LOOKUP using the given lookup
72       method.  It can also be created by calling X509_STORE_add_lookup(3),
73       which will associate a X509_STORE with the lookup mechanism.
74
75       X509_LOOKUP_init() initializes the internal state and resources as
76       needed by the given X509_LOOKUP to do its work.
77
78       X509_LOOKUP_shutdown() tears down the internal state and resources of
79       the given X509_LOOKUP.
80
81       X509_LOOKUP_free() destructs the given X509_LOOKUP.
82
83       X509_LOOKUP_set_method_data() and X509_LOOKUP_get_method_data()
84       associates and retrieves a pointer to application data to and from the
85       given X509_LOOKUP, respectively.
86
87       X509_LOOKUP_ctrl_ex() is used to set or get additional data to or from
88       a X509_LOOKUP structure or its associated X509_LOOKUP_METHOD(3).  The
89       arguments of the control command are passed via argc and argl, its
90       return value via *ret. The library context libctx and property query
91       propq are used when fetching algorithms from providers.  The meaning of
92       the arguments depends on the cmd number of the control command. In
93       general, this function is not called directly, but wrapped by a macro
94       call, see below.  The control cmds known to OpenSSL are discussed in
95       more depth in "Control Commands".
96
97       X509_LOOKUP_ctrl() is similar to X509_LOOKUP_ctrl_ex() but uses NULL
98       for the library context libctx and property query propq.
99
100       X509_LOOKUP_load_file_ex() passes a filename to be loaded immediately
101       into the associated X509_STORE. The library context libctx and property
102       query propq are used when fetching algorithms from providers.  type
103       indicates what type of object is expected.  This can only be used with
104       a lookup using the implementation X509_LOOKUP_file(3).
105
106       X509_LOOKUP_load_file() is similar to X509_LOOKUP_load_file_ex() but
107       uses NULL for the library context libctx and property query propq.
108
109       X509_LOOKUP_add_dir() passes a directory specification from which
110       certificates and CRLs are loaded on demand into the associated
111       X509_STORE.  type indicates what type of object is expected.  This can
112       only be used with a lookup using the implementation
113       X509_LOOKUP_hash_dir(3).
114
115       X509_LOOKUP_add_store_ex() passes a URI for a directory-like structure
116       from which containers with certificates and CRLs are loaded on demand
117       into the associated X509_STORE. The library context libctx and property
118       query propq are used when fetching algorithms from providers.
119
120       X509_LOOKUP_add_store() is similar to X509_LOOKUP_add_store_ex() but
121       uses NULL for the library context libctx and property query propq.
122
123       X509_LOOKUP_load_store_ex() passes a URI for a single container from
124       which certificates and CRLs are immediately loaded into the associated
125       X509_STORE. The library context libctx and property query propq are
126       used when fetching algorithms from providers.  These functions can only
127       be used with a lookup using the implementation X509_LOOKUP_store(3).
128
129       X509_LOOKUP_load_store() is similar to X509_LOOKUP_load_store_ex() but
130       uses NULL for the library context libctx and property query propq.
131
132       X509_LOOKUP_load_file_ex(), X509_LOOKUP_load_file(),
133       X509_LOOKUP_add_dir(), X509_LOOKUP_add_store_ex()
134       X509_LOOKUP_add_store(), X509_LOOKUP_load_store_ex() and
135       X509_LOOKUP_load_store() are implemented as macros that use
136       X509_LOOKUP_ctrl().
137
138       X509_LOOKUP_by_subject_ex(), X509_LOOKUP_by_subject(),
139       X509_LOOKUP_by_issuer_serial(), X509_LOOKUP_by_fingerprint(), and
140       X509_LOOKUP_by_alias() look up certificates and CRLs in the
141       X509_STORE(3) associated with the X509_LOOKUP using different criteria,
142       where the looked up object is stored in ret.  Some of the underlying
143       X509_LOOKUP_METHODs will also cache objects matching the criteria in
144       the associated X509_STORE, which makes it possible to handle cases
145       where the criteria have more than one hit.
146
147   Control Commands
148       The X509_LOOKUP_METHODs built into OpenSSL recognize the following
149       X509_LOOKUP_ctrl() cmds:
150
151       X509_L_FILE_LOAD
152           This is the command that X509_LOOKUP_load_file_ex() and
153           X509_LOOKUP_load_file() use.  The filename is passed in argc, and
154           the type in argl.
155
156       X509_L_ADD_DIR
157           This is the command that X509_LOOKUP_add_dir() uses.  The directory
158           specification is passed in argc, and the type in argl.
159
160       X509_L_ADD_STORE
161           This is the command that X509_LOOKUP_add_store_ex() and
162           X509_LOOKUP_add_store() use.  The URI is passed in argc.
163
164       X509_L_LOAD_STORE
165           This is the command that X509_LOOKUP_load_store_ex() and
166           X509_LOOKUP_load_store() use.  The URI is passed in argc.
167

RETURN VALUES

169       X509_LOOKUP_new() returns a X509_LOOKUP pointer when successful, or
170       NULL on error.
171
172       X509_LOOKUP_init() and X509_LOOKUP_shutdown() return 1 on success, or 0
173       on error.
174
175       X509_LOOKUP_ctrl() returns -1 if the X509_LOOKUP doesn't have an
176       associated X509_LOOKUP_METHOD, or 1 if the doesn't have a control
177       function.  Otherwise, it returns what the control function in the
178       X509_LOOKUP_METHOD returns, which is usually 1 on success and 0 in
179       error.
180
181       X509_LOOKUP_get_store() returns a X509_STORE pointer if there is one,
182       otherwise NULL.
183
184       X509_LOOKUP_by_subject_ex(), X509_LOOKUP_by_subject(),
185       X509_LOOKUP_by_issuer_serial(), X509_LOOKUP_by_fingerprint(), and
186       X509_LOOKUP_by_alias() all return 0 if there is no X509_LOOKUP_METHOD
187       or that method doesn't implement the corresponding function.
188       Otherwise, it returns what the corresponding function in the
189       X509_LOOKUP_METHOD returns, which is usually 1 on success and 0 in
190       error.
191

HISTORY

196       The functions X509_LOOKUP_by_subject_ex() and X509_LOOKUP_ctrl_ex()
197       were added in OpenSSL 3.0.
198
199       The macros X509_LOOKUP_load_file_ex(), X509_LOOKUP_load_store_ex() and
200       509_LOOKUP_add_store_ex() were added in OpenSSL 3.0.
201

COPYRIGHT

203       Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
204
205       Licensed under the Apache License 2.0 (the "License").  You may not use
206       this file except in compliance with the License.  You can obtain a copy
207       in the file LICENSE in the source distribution or at
208       <https://www.openssl.org/source/license.html>.
209
210
211
2123.0.5                             2022-07-05                X509_LOOKUP(3ossl)

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

SEE ALSO

HISTORY

COPYRIGHT