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