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