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

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
   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_HASH_DIR 3"
 136 .TH X509_LOOKUP_HASH_DIR 3 "2020-09-22" "1.1.1h" "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_hash_dir, X509_LOOKUP_file, X509_load_cert_file, X509_load_crl_file, X509_load_cert_crl_file \- Default OpenSSL certificate lookup methods
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/x509_vfy.h>
 147 \&
 148 \& X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void);
 149 \& X509_LOOKUP_METHOD *X509_LOOKUP_file(void);
 150 \&
 151 \& int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type);
 152 \& int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type);
 153 \& int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type);
 154 .Ve
 155 .SH "DESCRIPTION"
 156 .IX Header "DESCRIPTION"
 157 \&\fBX509_LOOKUP_hash_dir\fR and \fBX509_LOOKUP_file\fR are two certificate
 158 lookup methods to use with \fBX509_STORE\fR, provided by OpenSSL library.
 159 .PP
 160 Users of the library typically do not need to create instances of these
 161 methods manually, they would be created automatically by
 162 \&\fBX509_STORE_load_locations\fR\|(3) or
 163 \&\fBSSL_CTX_load_verify_locations\fR\|(3)
 164 functions.
 165 .PP
 166 Internally loading of certificates and CRLs is implemented via functions
 167 \&\fBX509_load_cert_crl_file\fR, \fBX509_load_cert_file\fR and
 168 \&\fBX509_load_crl_file\fR. These functions support parameter \fItype\fR, which
 169 can be one of constants \fB\s-1FILETYPE_PEM\s0\fR, \fB\s-1FILETYPE_ASN1\s0\fR and
 170 \&\fB\s-1FILETYPE_DEFAULT\s0\fR. They load certificates and/or CRLs from specified
 171 file into memory cache of \fBX509_STORE\fR objects which given \fBctx\fR
 172 parameter is associated with.
 173 .PP
 174 Functions \fBX509_load_cert_file\fR and
 175 \&\fBX509_load_crl_file\fR can load both \s-1PEM\s0 and \s-1DER\s0 formats depending of
 176 type value. Because \s-1DER\s0 format cannot contain more than one certificate
 177 or \s-1CRL\s0 object (while \s-1PEM\s0 can contain several concatenated \s-1PEM\s0 objects)
 178 \&\fBX509_load_cert_crl_file\fR with \fB\s-1FILETYPE_ASN1\s0\fR is equivalent to
 179 \&\fBX509_load_cert_file\fR.
 180 .PP
 181 Constant \fB\s-1FILETYPE_DEFAULT\s0\fR with \s-1NULL\s0 filename causes these functions
 182 to load default certificate store file (see
 183 \&\fBX509_STORE_set_default_paths\fR\|(3).
 184 .PP
 185 Functions return number of objects loaded from file or 0 in case of
 186 error.
 187 .PP
 188 Both methods support adding several certificate locations into one
 189 \&\fBX509_STORE\fR.
 190 .PP
 191 This page documents certificate store formats used by these methods and
 192 caching policy.
 193 .SS "File Method"
 194 .IX Subsection "File Method"
 195 The \fBX509_LOOKUP_file\fR method loads all the certificates or CRLs
 196 present in a file into memory at the time the file is added as a
 197 lookup source.
 198 .PP
 199 File format is \s-1ASCII\s0 text which contains concatenated \s-1PEM\s0 certificates
 200 and CRLs.
 201 .PP
 202 This method should be used by applications which work with a small
 203 set of CAs.
 204 .SS "Hashed Directory Method"
 205 .IX Subsection "Hashed Directory Method"
 206 \&\fBX509_LOOKUP_hash_dir\fR is a more advanced method, which loads
 207 certificates and CRLs on demand, and caches them in memory once
 208 they are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs
 209 upon each lookup, so that newer CRLs are as soon as they appear in
 210 the directory.
 211 .PP
 212 The directory should contain one certificate or \s-1CRL\s0 per file in \s-1PEM\s0 format,
 213 with a filename of the form \fIhash\fR.\fIN\fR for a certificate, or
 214 \&\fIhash\fR.\fBr\fR\fIN\fR for a \s-1CRL.\s0
 215 The \fIhash\fR is the value returned by the \fBX509_NAME_hash\fR\|(3) function applied
 216 to the subject name for certificates or issuer name for CRLs.
 217 The hash can also be obtained via the \fB\-hash\fR option of the \fBx509\fR\|(1) or
 218 \&\fBcrl\fR\|(1) commands.
 219 .PP
 220 The .\fIN\fR or .\fBr\fR\fIN\fR suffix is a sequence number that starts at zero, and is
 221 incremented consecutively for each certificate or \s-1CRL\s0 with the same \fIhash\fR
 222 value.
 223 Gaps in the sequence numbers are not supported, it is assumed that there are no
 224 more objects with the same hash beyond the first missing number in the
 225 sequence.
 226 .PP
 227 Sequence numbers make it possible for the directory to contain multiple
 228 certificates with same subject name hash value.
 229 For example, it is possible to have in the store several certificates with same
 230 subject or several CRLs with same issuer (and, for example, different validity
 231 period).
 232 .PP
 233 When checking for new CRLs once one \s-1CRL\s0 for given hash value is
 234 loaded, hash_dir lookup method checks only for certificates with
 235 sequence number greater than that of the already cached \s-1CRL.\s0
 236 .PP
 237 Note that the hash algorithm used for subject name hashing changed in OpenSSL
 238 1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL
 239 0.9.8 to 1.0.0.
 240 .PP
 241 OpenSSL includes a \fBrehash\fR\|(1) utility which creates symlinks with correct
 242 hashed names for all files with .pem suffix in a given directory.
 243 .SH "RETURN VALUES"
 244 .IX Header "RETURN VALUES"
 245 \&\fBX509_LOOKUP_hash_dir()\fR and \fBX509_LOOKUP_file()\fR always return a valid
 246 \&\fBX509_LOOKUP_METHOD\fR structure.
 247 .PP
 248 \&\fBX509_load_cert_file()\fR, \fBX509_load_crl_file()\fR and \fBX509_load_cert_crl_file()\fR return
 249 the number of loaded objects or 0 on error.
 250 .SH "SEE ALSO"
 251 .IX Header "SEE ALSO"
 252 \&\fBPEM_read_PrivateKey\fR\|(3),
 253 \&\fBX509_STORE_load_locations\fR\|(3),
 254 \&\fBX509_store_add_lookup\fR\|(3),
 255 \&\fBSSL_CTX_load_verify_locations\fR\|(3),
 256 \&\fBX509_LOOKUP_meth_new\fR\|(3),
 257 .SH "COPYRIGHT"
 258 .IX Header "COPYRIGHT"
 259 Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved.
 260 .PP
 261 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 262 this file except in compliance with the License.  You can obtain a copy
 263 in the file \s-1LICENSE\s0 in the source distribution or at
 264 <https://www.openssl.org/source/license.html>.