secure/lib/libcrypto/man/X509_LOOKUP_hash_dir.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "X509_LOOKUP_HASH_DIR 3"
 132 .TH X509_LOOKUP_HASH_DIR 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/x509_vfy.h>
 143 \&
 144 \& X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void);
 145 \& X509_LOOKUP_METHOD *X509_LOOKUP_file(void);
 146 \&
 147 \& int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type);
 148 \& int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type);
 149 \& int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type);
 150 .Ve
 151 .SH "DESCRIPTION"
 152 .IX Header "DESCRIPTION"
 153 \&\fBX509_LOOKUP_hash_dir\fR and \fBX509_LOOKUP_file\fR are two certificate
 154 lookup methods to use with \fBX509_STORE\fR, provided by OpenSSL library.
 155 .PP
 156 Users of the library typically do not need to create instances of these
 157 methods manually, they would be created automatically by
 158 \&\fIX509_STORE_load_locations\fR\|(3) or
 159 \&\fISSL_CTX_load_verify_locations\fR\|(3)
 160 functions.
 161 .PP
 162 Internally loading of certificates and CRLs is implemented via functions
 163 \&\fBX509_load_cert_crl_file\fR, \fBX509_load_cert_file\fR and
 164 \&\fBX509_load_crl_file\fR. These functions support parameter \fItype\fR, which
 165 can be one of constants \fB\s-1FILETYPE_PEM\s0\fR, \fB\s-1FILETYPE_ASN1\s0\fR and
 166 \&\fB\s-1FILETYPE_DEFAULT\s0\fR. They load certificates and/or CRLs from specified
 167 file into memory cache of \fBX509_STORE\fR objects which given \fBctx\fR
 168 parameter is associated with.
 169 .PP
 170 Functions \fBX509_load_cert_file\fR and
 171 \&\fBX509_load_crl_file\fR can load both \s-1PEM\s0 and \s-1DER\s0 formats depending of
 172 type value. Because \s-1DER\s0 format cannot contain more than one certificate
 173 or \s-1CRL\s0 object (while \s-1PEM\s0 can contain several concatenated \s-1PEM\s0 objects)
 174 \&\fBX509_load_cert_crl_file\fR with \fB\s-1FILETYPE_ASN1\s0\fR is equivalent to
 175 \&\fBX509_load_cert_file\fR.
 176 .PP
 177 Constant \fB\s-1FILETYPE_DEFAULT\s0\fR with \s-1NULL\s0 filename causes these functions
 178 to load default certificate store file (see
 179 \&\fIX509_STORE_set_default_paths\fR\|(3).
 180 .PP
 181 Functions return number of objects loaded from file or 0 in case of
 182 error.
 183 .PP
 184 Both methods support adding several certificate locations into one
 185 \&\fBX509_STORE\fR.
 186 .PP
 187 This page documents certificate store formats used by these methods and
 188 caching policy.
 189 .SS "File Method"
 190 .IX Subsection "File Method"
 191 The \fBX509_LOOKUP_file\fR method loads all the certificates or CRLs
 192 present in a file into memory at the time the file is added as a
 193 lookup source.
 194 .PP
 195 File format is \s-1ASCII\s0 text which contains concatenated \s-1PEM\s0 certificates
 196 and CRLs.
 197 .PP
 198 This method should be used by applications which work with a small
 199 set of CAs.
 200 .SS "Hashed Directory Method"
 201 .IX Subsection "Hashed Directory Method"
 202 \&\fBX509_LOOKUP_hash_dir\fR is a more advanced method, which loads
 203 certificates and CRLs on demand, and caches them in memory once
 204 they are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs
 205 upon each lookup, so that newer CRLs are as soon as they appear in
 206 the directory.
 207 .PP
 208 The directory should contain one certificate or \s-1CRL\s0 per file in \s-1PEM\s0 format,
 209 with a file name of the form \fIhash\fR.\fIN\fR for a certificate, or
 210 \&\fIhash\fR.\fBr\fR\fIN\fR for a \s-1CRL.\s0
 211 The \fIhash\fR is the value returned by the \fIX509_NAME_hash\fR\|(3) function applied
 212 to the subject name for certificates or issuer name for CRLs.
 213 The hash can also be obtained via the \fB\-hash\fR option of the \fIx509\fR\|(1) or
 214 \&\fIcrl\fR\|(1) commands.
 215 .PP
 216 The .\fIN\fR or .\fBr\fR\fIN\fR suffix is a sequence number that starts at zero, and is
 217 incremented consecutively for each certificate or \s-1CRL\s0 with the same \fIhash\fR
 218 value.
 219 Gaps in the sequence numbers are not supported, it is assumed that there are no
 220 more objects with the same hash beyond the first missing number in the
 221 sequence.
 222 .PP
 223 Sequence numbers make it possible for the directory to contain multiple
 224 certificates with same subject name hash value.
 225 For example, it is possible to have in the store several certificates with same
 226 subject or several CRLs with same issuer (and, for example, different validity
 227 period).
 228 .PP
 229 When checking for new CRLs once one \s-1CRL\s0 for given hash value is
 230 loaded, hash_dir lookup method checks only for certificates with
 231 sequence number greater than that of the already cached \s-1CRL.\s0
 232 .PP
 233 Note that the hash algorithm used for subject name hashing changed in OpenSSL
 234 1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL
 235 0.9.8 to 1.0.0.
 236 .PP
 237 OpenSSL includes a \fIrehash\fR\|(1) utility which creates symlinks with correct
 238 hashed names for all files with .pem suffix in a given directory.
 239 .SH "RETURN VALUES"
 240 .IX Header "RETURN VALUES"
 241 \&\fIX509_LOOKUP_hash_dir()\fR and \fIX509_LOOKUP_file()\fR always return a valid
 242 \&\fBX509_LOOKUP_METHOD\fR structure.
 243 .PP
 244 \&\fIX509_load_cert_file()\fR, \fIX509_load_crl_file()\fR and \fIX509_load_cert_crl_file()\fR return
 245 the number of loaded objects or 0 on error.
 246 .SH "SEE ALSO"
 247 .IX Header "SEE ALSO"
 248 \&\fIPEM_read_PrivateKey\fR\|(3),
 249 \&\fIX509_STORE_load_locations\fR\|(3),
 250 \&\fIX509_store_add_lookup\fR\|(3),
 251 \&\fISSL_CTX_load_verify_locations\fR\|(3),
 252 \&\fIX509_LOOKUP_meth_new\fR\|(3),
 253 .SH "COPYRIGHT"
 254 .IX Header "COPYRIGHT"
 255 Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
 256 .PP
 257 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 258 this file except in compliance with the License.  You can obtain a copy
 259 in the file \s-1LICENSE\s0 in the source distribution or at
 260 <https://www.openssl.org/source/license.html>.