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