secure/lib/libcrypto/man/man3/X509_LOOKUP.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.41)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "X509_LOOKUP 3"
 136 .TH X509_LOOKUP 3 "2020-12-08" "1.1.1i" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 X509_LOOKUP, X509_LOOKUP_TYPE, X509_LOOKUP_new, X509_LOOKUP_free, X509_LOOKUP_init, X509_LOOKUP_shutdown, X509_LOOKUP_set_method_data, X509_LOOKUP_get_method_data, X509_LOOKUP_ctrl, X509_LOOKUP_load_file, X509_LOOKUP_add_dir, X509_LOOKUP_get_store, X509_LOOKUP_by_subject, X509_LOOKUP_by_issuer_serial, X509_LOOKUP_by_fingerprint, X509_LOOKUP_by_alias \&\- OpenSSL certificate lookup mechanisms
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/x509_vfy.h>
 147 \&
 148 \& typedef x509_lookup_st X509_LOOKUP;
 149 \&
 150 \& typedef enum X509_LOOKUP_TYPE;
 151 \&
 152 \& X509_LOOKUP *X509_LOOKUP_new(X509_LOOKUP_METHOD *method);
 153 \& int X509_LOOKUP_init(X509_LOOKUP *ctx);
 154 \& int X509_LOOKUP_shutdown(X509_LOOKUP *ctx);
 155 \& void X509_LOOKUP_free(X509_LOOKUP *ctx);
 156 \&
 157 \& int X509_LOOKUP_set_method_data(X509_LOOKUP *ctx, void *data);
 158 \& void *X509_LOOKUP_get_method_data(const X509_LOOKUP *ctx);
 159 \&
 160 \& int X509_LOOKUP_ctrl(X509_LOOKUP *ctx, int cmd, const char *argc,
 161 \&                      long argl, char **ret);
 162 \& int X509_LOOKUP_load_file(X509_LOOKUP *ctx, char *name, long type);
 163 \& int X509_LOOKUP_add_dir(X509_LOOKUP *ctx, char *name, long type);
 164 \&
 165 \& X509_STORE *X509_LOOKUP_get_store(const X509_LOOKUP *ctx);
 166 \&
 167 \& int X509_LOOKUP_by_subject(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
 168 \&                            X509_NAME *name, X509_OBJECT *ret);
 169 \& int X509_LOOKUP_by_issuer_serial(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
 170 \&                                  X509_NAME *name, ASN1_INTEGER *serial,
 171 \&                                  X509_OBJECT *ret);
 172 \& int X509_LOOKUP_by_fingerprint(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
 173 \&                                const unsigned char *bytes, int len,
 174 \&                                X509_OBJECT *ret);
 175 \& int X509_LOOKUP_by_alias(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
 176 \&                          const char *str, int len, X509_OBJECT *ret);
 177 .Ve
 178 .SH "DESCRIPTION"
 179 .IX Header "DESCRIPTION"
 180 The \fBX509_LOOKUP\fR structure holds the information needed to look up
 181 certificates and CRLs according to an associated \fBX509_LOOKUP_METHOD\fR\|(3).
 182 Multiple \fBX509_LOOKUP\fR instances can be added to an \fBX509_STORE\fR\|(3)
 183 to enable lookup in that store.
 184 .PP
 185 \&\fBX509_LOOKUP_new()\fR creates a new \fBX509_LOOKUP\fR using the given lookup
 186 \&\fImethod\fR.
 187 It can also be created by calling \fBX509_STORE_add_lookup\fR\|(3), which
 188 will associate an \fBX509_STORE\fR with the lookup mechanism.
 189 .PP
 190 \&\fBX509_LOOKUP_init()\fR initializes the internal state and resources as
 191 needed by the given \fBX509_LOOKUP\fR to do its work.
 192 .PP
 193 \&\fBX509_LOOKUP_shutdown()\fR tears down the internal state and resources of
 194 the given \fBX509_LOOKUP\fR.
 195 .PP
 196 \&\fBX509_LOOKUP_free()\fR destructs the given \fBX509_LOOKUP\fR.
 197 .PP
 198 \&\fBX509_LOOKUP_set_method_data()\fR associates a pointer to application data
 199 to the given \fBX509_LOOKUP\fR.
 200 .PP
 201 \&\fBX509_LOOKUP_get_method_data()\fR retrieves a pointer to application data
 202 from the given \fBX509_LOOKUP\fR.
 203 .PP
 204 \&\fBX509_LOOKUP_ctrl()\fR is used to set or get additional data to or from an
 205 \&\fBX509_LOOKUP\fR structure or its associated \fBX509_LOOKUP_METHOD\fR\|(3).
 206 The arguments of the control command are passed via \fIargc\fR and \fIargl\fR,
 207 its return value via \fI*ret\fR.
 208 The meaning of the arguments depends on the \fIcmd\fR number of the
 209 control command. In general, this function is not called directly, but
 210 wrapped by a macro call, see below.
 211 The control \fIcmd\fRs known to OpenSSL are discussed in more depth
 212 in \*(L"Control Commands\*(R".
 213 .PP
 214 \&\fBX509_LOOKUP_load_file()\fR passes a filename to be loaded immediately
 215 into the associated \fBX509_STORE\fR.
 216 \&\fItype\fR indicates what type of object is expected.
 217 This can only be used with a lookup using the implementation
 218 \&\fBX509_LOOKUP_file\fR\|(3).
 219 .PP
 220 \&\fBX509_LOOKUP_add_dir()\fR passes a directory specification from which
 221 certificates and CRLs are loaded on demand into the associated
 222 \&\fBX509_STORE\fR.
 223 \&\fItype\fR indicates what type of object is expected.
 224 This can only be used with a lookup using the implementation
 225 \&\fBX509_LOOKUP_hash_dir\fR\|(3).
 226 .PP
 227 \&\fBX509_LOOKUP_load_file()\fR, \fBX509_LOOKUP_add_dir()\fR,
 228 \&\fBX509_LOOKUP_add_store()\fR, and \fBX509_LOOKUP_load_store()\fR are implemented
 229 as macros that use \fBX509_LOOKUP_ctrl()\fR.
 230 .PP
 231 \&\fBX509_LOOKUP_by_subject()\fR, \fBX509_LOOKUP_by_issuer_serial()\fR,
 232 \&\fBX509_LOOKUP_by_fingerprint()\fR, and \fBX509_LOOKUP_by_alias()\fR look up
 233 certificates and CRLs in the \fBX509_STORE\fR\|(3) associated with the
 234 \&\fBX509_LOOKUP\fR using different criteria, where the looked up object is
 235 stored in \fIret\fR.
 236 Some of the underlying \fBX509_LOOKUP_METHOD\fRs will also cache objects
 237 matching the criteria in the associated \fBX509_STORE\fR, which makes it
 238 possible to handle cases where the criteria have more than one hit.
 239 .SS "File Types"
 240 .IX Subsection "File Types"
 241 \&\fBX509_LOOKUP_load_file()\fR and \fBX509_LOOKUP_add_dir()\fR take a \fItype\fR,
 242 which can be one of the following:
 243 .IP "\fBX509_FILETYPE_PEM\fR" 4
 244 .IX Item "X509_FILETYPE_PEM"
 245 The file or files that are loaded are expected to be in \s-1PEM\s0 format.
 246 .IP "\fBX509_FILETYPE_ASN1\fR" 4
 247 .IX Item "X509_FILETYPE_ASN1"
 248 The file or files that are loaded are expected to be in raw \s-1DER\s0 format.
 249 .IP "\fBX509_FILETYPE_DEFAULT\fR" 4
 250 .IX Item "X509_FILETYPE_DEFAULT"
 251 The default certificate file or directory is used.  In this case,
 252 \&\fIname\fR is ignored.
 253 .SS "Control Commands"
 254 .IX Subsection "Control Commands"
 255 The \fBX509_LOOKUP_METHOD\fRs built into OpenSSL recognise the following
 256 \&\fBX509_LOOKUP_ctrl()\fR \fIcmd\fRs:
 257 .IP "\fBX509_L_FILE_LOAD\fR" 4
 258 .IX Item "X509_L_FILE_LOAD"
 259 This is the command that \fBX509_LOOKUP_load_file()\fR uses.
 260 The filename is passed in \fIargc\fR, and the type in \fIargl\fR.
 261 .IP "\fBX509_L_ADD_DIR\fR" 4
 262 .IX Item "X509_L_ADD_DIR"
 263 This is the command that \fBX509_LOOKUP_add_dir()\fR uses.
 264 The directory specification is passed in \fIargc\fR, and the type in
 265 \&\fIargl\fR.
 266 .IP "\fBX509_L_ADD_STORE\fR" 4
 267 .IX Item "X509_L_ADD_STORE"
 268 This is the command that \fBX509_LOOKUP_add_store()\fR uses.
 269 The \s-1URI\s0 is passed in \fIargc\fR.
 270 .IP "\fBX509_L_LOAD_STORE\fR" 4
 271 .IX Item "X509_L_LOAD_STORE"
 272 This is the command that \fBX509_LOOKUP_load_store()\fR uses.
 273 The \s-1URI\s0 is passed in \fIargc\fR.
 274 .SH "RETURN VALUES"
 275 .IX Header "RETURN VALUES"
 276 \&\fBX509_LOOKUP_new()\fR returns an \fBX509_LOOKUP\fR pointer when successful,
 277 or \s-1NULL\s0 on error.
 278 .PP
 279 \&\fBX509_LOOKUP_init()\fR and \fBX509_LOOKUP_shutdown()\fR return 1 on success, or
 280 0 on error.
 281 .PP
 282 \&\fBX509_LOOKUP_ctrl()\fR returns \-1 if the \fBX509_LOOKUP\fR doesn't have an
 283 associated \fBX509_LOOKUP_METHOD\fR, or 1 if the
 284 doesn't have a control function.
 285 Otherwise, it returns what the control function in the
 286 \&\fBX509_LOOKUP_METHOD\fR returns, which is usually 1 on success and 0 in
 287 error.
 288 .IX Xref "509_LOOKUP_METHOD"
 289 .PP
 290 \&\fBX509_LOOKUP_get_store()\fR returns an \fBX509_STORE\fR pointer if there is
 291 one, otherwise \s-1NULL.\s0
 292 .PP
 293 \&\fBX509_LOOKUP_by_subject()\fR, \fBX509_LOOKUP_by_issuer_serial()\fR,
 294 \&\fBX509_LOOKUP_by_fingerprint()\fR, and \fBX509_LOOKUP_by_alias()\fR all return 0
 295 if there is no \fBX509_LOOKUP_METHOD\fR or that method doesn't implement
 296 the corresponding function.
 297 Otherwise, it returns what the corresponding function in the
 298 \&\fBX509_LOOKUP_METHOD\fR returns, which is usually 1 on success and 0 in
 299 error.
 300 .SH "SEE ALSO"
 301 .IX Header "SEE ALSO"
 302 \&\fBX509_LOOKUP_METHOD\fR\|(3), \fBX509_STORE\fR\|(3)
 303 .SH "COPYRIGHT"
 304 .IX Header "COPYRIGHT"
 305 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 306 .PP
 307 Licensed under the Apache License 2.0 (the \*(L"License\*(R").  You may not use
 308 this file except in compliance with the License.  You can obtain a copy
 309 in the file \s-1LICENSE\s0 in the source distribution or at
 310 <https://www.openssl.org/source/license.html>.