doc/man3/X509_LOOKUP.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 X509_LOOKUP, X509_LOOKUP_TYPE,
   6 X509_LOOKUP_new, X509_LOOKUP_free, X509_LOOKUP_init,
   7 X509_LOOKUP_shutdown,
   8 X509_LOOKUP_set_method_data, X509_LOOKUP_get_method_data,
   9 X509_LOOKUP_ctrl_ex, X509_LOOKUP_ctrl,
  10 X509_LOOKUP_load_file_ex, X509_LOOKUP_load_file,
  11 X509_LOOKUP_add_dir,
  12 X509_LOOKUP_add_store_ex, X509_LOOKUP_add_store,
  13 X509_LOOKUP_load_store_ex, X509_LOOKUP_load_store,
  14 X509_LOOKUP_get_store,
  15 X509_LOOKUP_by_subject_ex, X509_LOOKUP_by_subject,
  16 X509_LOOKUP_by_issuer_serial, X509_LOOKUP_by_fingerprint,
  17 X509_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, OPENSSL_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                               OPENSSL_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                               OPENSSL_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, OPENSSL_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, OPENSSL_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                                OPENSSL_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
  71 The B<X509_LOOKUP> structure holds the information needed to look up
  72 certificates and CRLs according to an associated L<X509_LOOKUP_METHOD(3)>.
  73 Multiple B<X509_LOOKUP> instances can be added to an L<X509_STORE(3)>
  74 to enable lookup in that store.
  75
  76 X509_LOOKUP_new() creates a new B<X509_LOOKUP> using the given lookup
  77 I<method>.
  78 It can also be created by calling L<X509_STORE_add_lookup(3)>, which
  79 will associate a B<X509_STORE> with the lookup mechanism.
  80
  81 X509_LOOKUP_init() initializes the internal state and resources as
  82 needed by the given B<X509_LOOKUP> to do its work.
  83
  84 X509_LOOKUP_shutdown() tears down the internal state and resources of
  85 the given B<X509_LOOKUP>.
  86
  87 X509_LOOKUP_free() destructs the given B<X509_LOOKUP>.
  88
  89 X509_LOOKUP_set_method_data() and X509_LOOKUP_get_method_data()
  90 associates and retrieves a pointer to application data to and from the
  91 given B<X509_LOOKUP>, respectively.
  92
  93 X509_LOOKUP_ctrl_ex() is used to set or get additional data to or from
  94 a B<X509_LOOKUP> structure or its associated L<X509_LOOKUP_METHOD(3)>.
  95 The arguments of the control command are passed via I<argc> and I<argl>,
  96 its return value via I<*ret>. The library context I<libctx> and property
  97 query <propq> are used when fetching algorithms from providers.
  98 The meaning of the arguments depends on the I<cmd> number of the
  99 control command. In general, this function is not called directly, but
 100 wrapped by a macro call, see below.
 101 The control I<cmd>s known to OpenSSL are discussed in more depth
 102 in L</Control Commands>.
 103
 104 X509_LOOKUP_ctrl() is similar to X509_LOOKUP_ctrl_ex() but
 105 uses NULL for the library context I<libctx> and property query <propq>.
 106
 107 X509_LOOKUP_load_file_ex() passes a filename to be loaded immediately
 108 into the associated B<X509_STORE>. The library context I<libctx> and property
 109 query <propq> are used when fetching algorithms from providers.
 110 I<type> indicates what type of object is expected.
 111 This can only be used with a lookup using the implementation
 112 L<X509_LOOKUP_file(3)>.
 113
 114 X509_LOOKUP_load_file() is similar to X509_LOOKUP_load_file_ex() but
 115 uses NULL for the library context I<libctx> and property query <propq>.
 116
 117 X509_LOOKUP_add_dir() passes a directory specification from which
 118 certificates and CRLs are loaded on demand into the associated
 119 B<X509_STORE>.
 120 I<type> indicates what type of object is expected.
 121 This can only be used with a lookup using the implementation
 122 L<X509_LOOKUP_hash_dir(3)>.
 123
 124 X509_LOOKUP_add_store_ex() passes a URI for a directory-like structure
 125 from which containers with certificates and CRLs are loaded on demand
 126 into the associated B<X509_STORE>. The library context I<libctx> and property
 127 query <propq> are used when fetching algorithms from providers.
 128
 129 X509_LOOKUP_add_store() is similar to X509_LOOKUP_add_store_ex() but
 130 uses NULL for the library context I<libctx> and property query <propq>.
 131
 132 X509_LOOKUP_load_store_ex() passes a URI for a single container from
 133 which certificates and CRLs are immediately loaded into the associated
 134 B<X509_STORE>. The library context I<libctx> and property query <propq> are used
 135 when fetching algorithms from providers.
 136 These functions can only be used with a lookup using the
 137 implementation L<X509_LOOKUP_store(3)>.
 138
 139 X509_LOOKUP_load_store() is similar to X509_LOOKUP_load_store_ex() but
 140 uses NULL for the library context I<libctx> and property query <propq>.
 141
 142 X509_LOOKUP_load_file_ex(), X509_LOOKUP_load_file(),
 143 X509_LOOKUP_add_dir(),
 144 X509_LOOKUP_add_store_ex() X509_LOOKUP_add_store(),
 145 X509_LOOKUP_load_store_ex() and X509_LOOKUP_load_store() are
 146 implemented as macros that use X509_LOOKUP_ctrl().
 147
 148 X509_LOOKUP_by_subject_ex(), X509_LOOKUP_by_subject(),
 149 X509_LOOKUP_by_issuer_serial(), X509_LOOKUP_by_fingerprint(), and
 150 X509_LOOKUP_by_alias() look up certificates and CRLs in the L<X509_STORE(3)>
 151 associated with the B<X509_LOOKUP> using different criteria, where the looked up
 152 object is stored in I<ret>.
 153 Some of the underlying B<X509_LOOKUP_METHOD>s will also cache objects
 154 matching the criteria in the associated B<X509_STORE>, which makes it
 155 possible to handle cases where the criteria have more than one hit.
 156
 157 =head2 Control Commands
 158
 159 The B<X509_LOOKUP_METHOD>s built into OpenSSL recognize the following
 160 X509_LOOKUP_ctrl() I<cmd>s:
 161
 162 =over 4
 163
 164 =item B<X509_L_FILE_LOAD>
 165
 166 This is the command that X509_LOOKUP_load_file_ex() and
 167 X509_LOOKUP_load_file() use.
 168 The filename is passed in I<argc>, and the type in I<argl>.
 169
 170 =item B<X509_L_ADD_DIR>
 171
 172 This is the command that X509_LOOKUP_add_dir() uses.
 173 The directory specification is passed in I<argc>, and the type in
 174 I<argl>.
 175
 176 =item B<X509_L_ADD_STORE>
 177
 178 This is the command that X509_LOOKUP_add_store_ex() and
 179 X509_LOOKUP_add_store() use.
 180 The URI is passed in I<argc>.
 181
 182 =item B<X509_L_LOAD_STORE>
 183
 184 This is the command that X509_LOOKUP_load_store_ex() and
 185 X509_LOOKUP_load_store() use.
 186 The URI is passed in I<argc>.
 187
 188 =back
 189
 190 =head1 RETURN VALUES
 191
 192 X509_LOOKUP_new() returns a B<X509_LOOKUP> pointer when successful,
 193 or NULL on error.
 194
 195 X509_LOOKUP_init() and X509_LOOKUP_shutdown() return 1 on success, or
 196 0 on error.
 197
 198 X509_LOOKUP_ctrl() returns -1 if the B<X509_LOOKUP> doesn't have an
 199 associated B<X509_LOOKUP_METHOD>, or 1 if the X<509_LOOKUP_METHOD>
 200 doesn't have a control function.
 201 Otherwise, it returns what the control function in the
 202 B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in
 203 error.
 204
 205 X509_LOOKUP_get_store() returns a B<X509_STORE> pointer if there is
 206 one, otherwise NULL.
 207
 208 X509_LOOKUP_by_subject_ex(), X509_LOOKUP_by_subject(),
 209 X509_LOOKUP_by_issuer_serial(), X509_LOOKUP_by_fingerprint(), and
 210 X509_LOOKUP_by_alias() all return 0 if there is no B<X509_LOOKUP_METHOD> or that
 211 method doesn't implement the corresponding function.
 212 Otherwise, it returns what the corresponding function in the
 213 B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in
 214 error.
 215
 216 =head1 SEE ALSO
 217
 218 L<X509_LOOKUP_METHOD(3)>, L<X509_STORE(3)>
 219
 220 =head1 HISTORY
 221
 222 The functions X509_LOOKUP_by_subject_ex() and
 223 X509_LOOKUP_ctrl_ex() were added in OpenSSL 3.0.
 224
 225 The macros X509_LOOKUP_load_file_ex(),
 226 X509_LOOKUP_load_store_ex() and 509_LOOKUP_add_store_ex() were
 227 added in OpenSSL 3.0.
 228
 229 =head1 COPYRIGHT
 230
 231 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 232
 233 Licensed under the Apache License 2.0 (the "License").  You may not use
 234 this file except in compliance with the License.  You can obtain a copy
 235 in the file LICENSE in the source distribution or at
 236 L<https://www.openssl.org/source/license.html>.
 237
 238 =cut