crypto/openssl/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,
  10 X509_LOOKUP_load_file, X509_LOOKUP_add_dir,
  11 X509_LOOKUP_get_store, X509_LOOKUP_by_subject,
  12 X509_LOOKUP_by_issuer_serial, X509_LOOKUP_by_fingerprint,
  13 X509_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
  52 The B<X509_LOOKUP> structure holds the information needed to look up
  53 certificates and CRLs according to an associated L<X509_LOOKUP_METHOD(3)>.
  54 Multiple B<X509_LOOKUP> instances can be added to an L<X509_STORE(3)>
  55 to enable lookup in that store.
  56
  57 X509_LOOKUP_new() creates a new B<X509_LOOKUP> using the given lookup
  58 I<method>.
  59 It can also be created by calling L<X509_STORE_add_lookup(3)>, which
  60 will associate an B<X509_STORE> with the lookup mechanism.
  61
  62 X509_LOOKUP_init() initializes the internal state and resources as
  63 needed by the given B<X509_LOOKUP> to do its work.
  64
  65 X509_LOOKUP_shutdown() tears down the internal state and resources of
  66 the given B<X509_LOOKUP>.
  67
  68 X509_LOOKUP_free() destructs the given B<X509_LOOKUP>.
  69
  70 X509_LOOKUP_set_method_data() associates a pointer to application data
  71 to the given B<X509_LOOKUP>.
  72
  73 X509_LOOKUP_get_method_data() retrieves a pointer to application data
  74 from the given B<X509_LOOKUP>.
  75
  76 X509_LOOKUP_ctrl() is used to set or get additional data to or from an
  77 B<X509_LOOKUP> structure or its associated L<X509_LOOKUP_METHOD(3)>.
  78 The arguments of the control command are passed via I<argc> and I<argl>,
  79 its return value via I<*ret>.
  80 The meaning of the arguments depends on the I<cmd> number of the
  81 control command. In general, this function is not called directly, but
  82 wrapped by a macro call, see below.
  83 The control I<cmd>s known to OpenSSL are discussed in more depth
  84 in L</Control Commands>.
  85
  86 X509_LOOKUP_load_file() passes a filename to be loaded immediately
  87 into the associated B<X509_STORE>.
  88 I<type> indicates what type of object is expected.
  89 This can only be used with a lookup using the implementation
  90 L<X509_LOOKUP_file(3)>.
  91
  92 X509_LOOKUP_add_dir() passes a directory specification from which
  93 certificates and CRLs are loaded on demand into the associated
  94 B<X509_STORE>.
  95 I<type> indicates what type of object is expected.
  96 This can only be used with a lookup using the implementation
  97 L<X509_LOOKUP_hash_dir(3)>.
  98
  99 X509_LOOKUP_load_file(), X509_LOOKUP_add_dir(),
 100 X509_LOOKUP_add_store(), and X509_LOOKUP_load_store() are implemented
 101 as macros that use X509_LOOKUP_ctrl().
 102
 103 X509_LOOKUP_by_subject(), X509_LOOKUP_by_issuer_serial(),
 104 X509_LOOKUP_by_fingerprint(), and X509_LOOKUP_by_alias() look up
 105 certificates and CRLs in the L<X509_STORE(3)> associated with the
 106 B<X509_LOOKUP> using different criteria, where the looked up object is
 107 stored in I<ret>.
 108 Some of the underlying B<X509_LOOKUP_METHOD>s will also cache objects
 109 matching the criteria in the associated B<X509_STORE>, which makes it
 110 possible to handle cases where the criteria have more than one hit.
 111
 112 =head2 File Types
 113
 114 X509_LOOKUP_load_file() and X509_LOOKUP_add_dir() take a I<type>,
 115 which can be one of the following:
 116
 117 =over 4
 118
 119 =item B<X509_FILETYPE_PEM>
 120
 121 The file or files that are loaded are expected to be in PEM format.
 122
 123 =item B<X509_FILETYPE_ASN1>
 124
 125 The file or files that are loaded are expected to be in raw DER format.
 126
 127 =item B<X509_FILETYPE_DEFAULT>
 128
 129 The default certificate file or directory is used.  In this case,
 130 I<name> is ignored.
 131
 132 =begin comment
 133
 134 TODO
 135 Document X509_get_default_cert_file_env(3),
 136 X509_get_default_cert_file(3), X509_get_default_cert_dir_env(3) and
 137 X509_get_default_cert_dir(3) and link to them here.
 138
 139 =end comment
 140
 141 =back
 142
 143 =head2 Control Commands
 144
 145 The B<X509_LOOKUP_METHOD>s built into OpenSSL recognise the following
 146 X509_LOOKUP_ctrl() I<cmd>s:
 147
 148 =over 4
 149
 150 =item B<X509_L_FILE_LOAD>
 151
 152 This is the command that X509_LOOKUP_load_file() uses.
 153 The filename is passed in I<argc>, and the type in I<argl>.
 154
 155 =item B<X509_L_ADD_DIR>
 156
 157 This is the command that X509_LOOKUP_add_dir() uses.
 158 The directory specification is passed in I<argc>, and the type in
 159 I<argl>.
 160
 161 =item B<X509_L_ADD_STORE>
 162
 163 This is the command that X509_LOOKUP_add_store() uses.
 164 The URI is passed in I<argc>.
 165
 166 =item B<X509_L_LOAD_STORE>
 167
 168 This is the command that X509_LOOKUP_load_store() uses.
 169 The URI is passed in I<argc>.
 170
 171 =back
 172
 173 =head1 RETURN VALUES
 174
 175 X509_LOOKUP_new() returns an B<X509_LOOKUP> pointer when successful,
 176 or NULL on error.
 177
 178 X509_LOOKUP_init() and X509_LOOKUP_shutdown() return 1 on success, or
 179 0 on error.
 180
 181 X509_LOOKUP_ctrl() returns -1 if the B<X509_LOOKUP> doesn't have an
 182 associated B<X509_LOOKUP_METHOD>, or 1 if the X<509_LOOKUP_METHOD>
 183 doesn't have a control function.
 184 Otherwise, it returns what the control function in the
 185 B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in
 186 error.
 187
 188 X509_LOOKUP_get_store() returns an B<X509_STORE> pointer if there is
 189 one, otherwise NULL.
 190
 191 X509_LOOKUP_by_subject(), X509_LOOKUP_by_issuer_serial(),
 192 X509_LOOKUP_by_fingerprint(), and X509_LOOKUP_by_alias() all return 0
 193 if there is no B<X509_LOOKUP_METHOD> or that method doesn't implement
 194 the corresponding function.
 195 Otherwise, it returns what the corresponding function in the
 196 B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in
 197 error.
 198
 199 =head1 SEE ALSO
 200
 201 L<X509_LOOKUP_METHOD(3)>, L<X509_STORE(3)>
 202
 203 =head1 COPYRIGHT
 204
 205 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 206
 207 Licensed under the Apache License 2.0 (the "License").  You may not use
 208 this file except in compliance with the License.  You can obtain a copy
 209 in the file LICENSE in the source distribution or at
 210 L<https://www.openssl.org/source/license.html>.
 211
 212 =cut