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