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

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