secure/lib/libcrypto/man/X509_STORE_add_cert.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.39)
   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_STORE_ADD_CERT 3"
 136 .TH X509_STORE_ADD_CERT 3 "2019-09-10" "1.1.1d" "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_STORE_add_cert, X509_STORE_add_crl, X509_STORE_set_depth, X509_STORE_set_flags, X509_STORE_set_purpose, X509_STORE_set_trust, X509_STORE_load_locations, X509_STORE_set_default_paths \&\- X509_STORE manipulation
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/x509_vfy.h>
 147 \&
 148 \& int X509_STORE_add_cert(X509_STORE *ctx, X509 *x);
 149 \& int X509_STORE_add_crl(X509_STORE *ctx, X509_CRL *x);
 150 \& int X509_STORE_set_depth(X509_STORE *store, int depth);
 151 \& int X509_STORE_set_flags(X509_STORE *ctx, unsigned long flags);
 152 \& int X509_STORE_set_purpose(X509_STORE *ctx, int purpose);
 153 \& int X509_STORE_set_trust(X509_STORE *ctx, int trust);
 154 \&
 155 \& int X509_STORE_load_locations(X509_STORE *ctx,
 156 \&                               const char *file, const char *dir);
 157 \& int X509_STORE_set_default_paths(X509_STORE *ctx);
 158 .Ve
 159 .SH "DESCRIPTION"
 160 .IX Header "DESCRIPTION"
 161 The \fBX509_STORE\fR structure is intended to be a consolidated mechanism for
 162 holding information about X.509 certificates and CRLs, and constructing
 163 and validating chains of certificates terminating in trusted roots.
 164 It admits multiple lookup mechanisms and efficient scaling performance
 165 with large numbers of certificates, and a great deal of flexibility in
 166 how validation and policy checks are performed.
 167 .PP
 168 \&\fBX509_STORE_new\fR\|(3) creates an empty \fBX509_STORE\fR structure, which contains
 169 no information about trusted certificates or where such certificates
 170 are located on disk, and is generally not usable.  Normally, trusted
 171 certificates will be added to the \fBX509_STORE\fR to prepare it for use,
 172 via mechanisms such as \fBX509_STORE_add_lookup()\fR and \fBX509_LOOKUP_file()\fR, or
 173 \&\fBPEM_read_bio_X509_AUX()\fR and \fBX509_STORE_add_cert()\fR.  CRLs can also be added,
 174 and many behaviors configured as desired.
 175 .PP
 176 Once the \fBX509_STORE\fR is suitably configured, \fBX509_STORE_CTX_new()\fR is
 177 used to instantiate a single-use \fBX509_STORE_CTX\fR for each chain-building
 178 and verification operation.  That process includes providing the end-entity
 179 certificate to be verified and an additional set of untrusted certificates
 180 that may be used in chain-building.  As such, it is expected that the
 181 certificates included in the \fBX509_STORE\fR are certificates that represent
 182 trusted entities such as root certificate authorities (CAs).
 183 OpenSSL represents these trusted certificates internally as \fBX509\fR objects
 184 with an associated \fBX509_CERT_AUX\fR, as are produced by
 185 \&\fBPEM_read_bio_X509_AUX()\fR and similar routines that refer to X509_AUX.
 186 The public interfaces that operate on such trusted certificates still
 187 operate on pointers to \fBX509\fR objects, though.
 188 .PP
 189 \&\fBX509_STORE_add_cert()\fR and \fBX509_STORE_add_crl()\fR add the respective object
 190 to the \fBX509_STORE\fR's local storage.  Untrusted objects should not be
 191 added in this way.  The added object's reference count is incremented by one,
 192 hence the caller retains ownership of the object and needs to free it when it
 193 is no longer needed.
 194 .PP
 195 \&\fBX509_STORE_set_depth()\fR, \fBX509_STORE_set_flags()\fR, \fBX509_STORE_set_purpose()\fR,
 196 \&\fBX509_STORE_set_trust()\fR, and \fBX509_STORE_set1_param()\fR set the default values
 197 for the corresponding values used in certificate chain validation.  Their
 198 behavior is documented in the corresponding \fBX509_VERIFY_PARAM\fR manual
 199 pages, e.g., \fBX509_VERIFY_PARAM_set_depth\fR\|(3).
 200 .PP
 201 \&\fBX509_STORE_load_locations()\fR loads trusted certificate(s) into an
 202 \&\fBX509_STORE\fR from a given file and/or directory path.  It is permitted
 203 to specify just a file, just a directory, or both paths.  The certificates
 204 in the directory must be in hashed form, as documented in
 205 \&\fBX509_LOOKUP_hash_dir\fR\|(3).
 206 .PP
 207 \&\fBX509_STORE_set_default_paths()\fR is somewhat misnamed, in that it does not
 208 set what default paths should be used for loading certificates.  Instead,
 209 it loads certificates into the \fBX509_STORE\fR from the hardcoded default
 210 paths.
 211 .SH "RETURN VALUES"
 212 .IX Header "RETURN VALUES"
 213 \&\fBX509_STORE_add_cert()\fR, \fBX509_STORE_add_crl()\fR, \fBX509_STORE_set_depth()\fR,
 214 \&\fBX509_STORE_set_flags()\fR, \fBX509_STORE_set_purpose()\fR,
 215 \&\fBX509_STORE_set_trust()\fR, \fBX509_STORE_load_locations()\fR, and
 216 \&\fBX509_STORE_set_default_paths()\fR return 1 on success or 0 on failure.
 217 .SH "SEE ALSO"
 218 .IX Header "SEE ALSO"
 219 \&\fBX509_LOOKUP_hash_dir\fR\|(3).
 220 \&\fBX509_VERIFY_PARAM_set_depth\fR\|(3).
 221 \&\fBX509_STORE_new\fR\|(3),
 222 \&\fBX509_STORE_get0_param\fR\|(3)
 223 .SH "COPYRIGHT"
 224 .IX Header "COPYRIGHT"
 225 Copyright 2017\-2019 The OpenSSL Project Authors. All Rights Reserved.
 226 .PP
 227 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 228 this file except in compliance with the License.  You can obtain a copy
 229 in the file \s-1LICENSE\s0 in the source distribution or at
 230 <https://www.openssl.org/source/license.html>.