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