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

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   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_CTX_NEW 3"
 136 .TH X509_STORE_CTX_NEW 3 "2022-05-03" "1.1.1o" "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_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, X509_STORE_CTX_init, X509_STORE_CTX_set0_trusted_stack, X509_STORE_CTX_set_cert, X509_STORE_CTX_set0_crls, X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain, X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted, X509_STORE_CTX_get_num_untrusted, X509_STORE_CTX_set_default, X509_STORE_CTX_set_verify, X509_STORE_CTX_verify_fn, X509_STORE_CTX_set_purpose, X509_STORE_CTX_set_trust, X509_STORE_CTX_purpose_inherit \&\- X509_STORE_CTX initialisation
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/x509_vfy.h>
 147 \&
 148 \& X509_STORE_CTX *X509_STORE_CTX_new(void);
 149 \& void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx);
 150 \& void X509_STORE_CTX_free(X509_STORE_CTX *ctx);
 151 \&
 152 \& int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store,
 153 \&                         X509 *x509, STACK_OF(X509) *chain);
 154 \&
 155 \& void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
 156 \&
 157 \& void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *x);
 158 \& STACK_OF(X509) *X509_STORE_CTX_get0_chain(X509_STORE_CTX *ctx);
 159 \& void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain);
 160 \& void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk);
 161 \&
 162 \& X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(X509_STORE_CTX *ctx);
 163 \& void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param);
 164 \& int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name);
 165 \&
 166 \& STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(X509_STORE_CTX *ctx);
 167 \& void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
 168 \&
 169 \& int X509_STORE_CTX_get_num_untrusted(X509_STORE_CTX *ctx);
 170 \&
 171 \& typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *);
 172 \& void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify);
 173 \&
 174 \& int X509_STORE_CTX_set_purpose(X509_STORE_CTX *ctx, int purpose);
 175 \& int X509_STORE_CTX_set_trust(X509_STORE_CTX *ctx, int trust);
 176 \& int X509_STORE_CTX_purpose_inherit(X509_STORE_CTX *ctx, int def_purpose,
 177 \&                                    int purpose, int trust);
 178 .Ve
 179 .SH "DESCRIPTION"
 180 .IX Header "DESCRIPTION"
 181 These functions initialise an \fBX509_STORE_CTX\fR structure for subsequent use
 182 by \fBX509_verify_cert()\fR.
 183 .PP
 184 \&\fBX509_STORE_CTX_new()\fR returns a newly initialised \fBX509_STORE_CTX\fR structure.
 185 .PP
 186 \&\fBX509_STORE_CTX_cleanup()\fR internally cleans up an \fBX509_STORE_CTX\fR structure.
 187 The context can then be reused with a new call to \fBX509_STORE_CTX_init()\fR.
 188 .PP
 189 \&\fBX509_STORE_CTX_free()\fR completely frees up \fBctx\fR. After this call \fBctx\fR
 190 is no longer valid.
 191 If \fBctx\fR is \s-1NULL\s0 nothing is done.
 192 .PP
 193 \&\fBX509_STORE_CTX_init()\fR sets up \fBctx\fR for a subsequent verification operation.
 194 It must be called before each call to \fBX509_verify_cert()\fR, i.e. a \fBctx\fR is only
 195 good for one call to \fBX509_verify_cert()\fR; if you want to verify a second
 196 certificate with the same \fBctx\fR then you must call \fBX509_STORE_CTX_cleanup()\fR
 197 and then \fBX509_STORE_CTX_init()\fR again before the second call to
 198 \&\fBX509_verify_cert()\fR. The trusted certificate store is set to \fBstore\fR, the end
 199 entity certificate to be verified is set to \fBx509\fR and a set of additional
 200 certificates (which will be untrusted but may be used to build the chain) in
 201 \&\fBchain\fR. Any or all of the \fBstore\fR, \fBx509\fR and \fBchain\fR parameters can be
 202 \&\fB\s-1NULL\s0\fR.
 203 .PP
 204 \&\fBX509_STORE_CTX_set0_trusted_stack()\fR sets the set of trusted certificates of
 205 \&\fBctx\fR to \fBsk\fR. This is an alternative way of specifying trusted certificates
 206 instead of using an \fBX509_STORE\fR.
 207 .PP
 208 \&\fBX509_STORE_CTX_set_cert()\fR sets the certificate to be verified in \fBctx\fR to
 209 \&\fBx\fR.
 210 .PP
 211 \&\fBX509_STORE_CTX_set0_verified_chain()\fR sets the validated chain used
 212 by \fBctx\fR to be \fBchain\fR.
 213 Ownership of the chain is transferred to \fBctx\fR and should not be
 214 free'd by the caller.
 215 \&\fBX509_STORE_CTX_get0_chain()\fR returns the internal pointer used by the
 216 \&\fBctx\fR that contains the validated chain.
 217 .PP
 218 \&\fBX509_STORE_CTX_set0_crls()\fR sets a set of CRLs to use to aid certificate
 219 verification to \fBsk\fR. These CRLs will only be used if \s-1CRL\s0 verification is
 220 enabled in the associated \fBX509_VERIFY_PARAM\fR structure. This might be
 221 used where additional \*(L"useful\*(R" CRLs are supplied as part of a protocol,
 222 for example in a PKCS#7 structure.
 223 .PP
 224 \&\fBX509_STORE_CTX_get0_param()\fR retrieves an internal pointer
 225 to the verification parameters associated with \fBctx\fR.
 226 .PP
 227 \&\fBX509_STORE_CTX_get0_untrusted()\fR retrieves an internal pointer to the
 228 stack of untrusted certificates associated with \fBctx\fR.
 229 .PP
 230 \&\fBX509_STORE_CTX_set0_untrusted()\fR sets the internal point to the stack
 231 of untrusted certificates associated with \fBctx\fR to \fBsk\fR.
 232 .PP
 233 \&\fBX509_STORE_CTX_set0_param()\fR sets the internal verification parameter pointer
 234 to \fBparam\fR. After this call \fBparam\fR should not be used.
 235 .PP
 236 \&\fBX509_STORE_CTX_set_default()\fR looks up and sets the default verification
 237 method to \fBname\fR. This uses the function \fBX509_VERIFY_PARAM_lookup()\fR to
 238 find an appropriate set of parameters from \fBname\fR.
 239 .PP
 240 \&\fBX509_STORE_CTX_get_num_untrusted()\fR returns the number of untrusted certificates
 241 that were used in building the chain following a call to \fBX509_verify_cert()\fR.
 242 .PP
 243 \&\fBX509_STORE_CTX_set_verify()\fR provides the capability for overriding the default
 244 verify function. This function is responsible for verifying chain signatures and
 245 expiration times.
 246 .PP
 247 A verify function is defined as an X509_STORE_CTX_verify type which has the
 248 following signature:
 249 .PP
 250 .Vb 1
 251 \& int (*verify)(X509_STORE_CTX *);
 252 .Ve
 253 .PP
 254 This function should receive the current X509_STORE_CTX as a parameter and
 255 return 1 on success or 0 on failure.
 256 .PP
 257 X509 certificates may contain information about what purposes keys contained
 258 within them can be used for. For example \*(L"\s-1TLS WWW\s0 Server Authentication\*(R" or
 259 \&\*(L"Email Protection\*(R". This \*(L"key usage\*(R" information is held internally to the
 260 certificate itself. In addition the trust store containing trusted certificates
 261 can declare what purposes we trust different certificates for. This \*(L"trust\*(R"
 262 information is not held within the certificate itself but is \*(L"meta\*(R" information
 263 held alongside it. This \*(L"meta\*(R" information is associated with the certificate
 264 after it is issued and could be determined by a system administrator. For
 265 example a certificate might declare that it is suitable for use for both
 266 \&\*(L"\s-1TLS WWW\s0 Server Authentication\*(R" and \*(L"\s-1TLS\s0 Client Authentication\*(R", but a system
 267 administrator might only trust it for the former. An X.509 certificate extension
 268 exists that can record extended key usage information to supplement the purpose
 269 information described above. This extended mechanism is arbitrarily extensible
 270 and not well suited for a generic library \s-1API\s0; applications that need to
 271 validate extended key usage information in certifiates will need to define a
 272 custom \*(L"purpose\*(R" (see below) or supply a nondefault verification callback
 273 (\fBX509_STORE_set_verify_cb_func\fR\|(3)).
 274 .PP
 275 \&\fBX509_STORE_CTX_set_purpose()\fR sets the purpose for the target certificate being
 276 verified in the \fIctx\fR. Built-in available values for the \fIpurpose\fR argument
 277 are \fBX509_PURPOSE_SSL_CLIENT\fR, \fBX509_PURPOSE_SSL_SERVER\fR,
 278 \&\fBX509_PURPOSE_NS_SSL_SERVER\fR, \fBX509_PURPOSE_SMIME_SIGN\fR,
 279 \&\fBX509_PURPOSE_SMIME_ENCRYPT\fR, \fBX509_PURPOSE_CRL_SIGN\fR, \fBX509_PURPOSE_ANY\fR,
 280 \&\fBX509_PURPOSE_OCSP_HELPER\fR and \fBX509_PURPOSE_TIMESTAMP_SIGN\fR. It is also
 281 possible to create a custom purpose value. Setting a purpose will ensure that
 282 the key usage declared within certificates in the chain being verified is
 283 consistent with that purpose as well as, potentially, other checks. Every
 284 purpose also has an associated default trust value which will also be set at the
 285 same time. During verification this trust setting will be verified to check it
 286 is consistent with the trust set by the system administrator for certificates in
 287 the chain.
 288 .PP
 289 \&\fBX509_STORE_CTX_set_trust()\fR sets the trust value for the target certificate
 290 being verified in the \fIctx\fR. Built-in available values for the \fItrust\fR
 291 argument are \fBX509_TRUST_COMPAT\fR, \fBX509_TRUST_SSL_CLIENT\fR,
 292 \&\fBX509_TRUST_SSL_SERVER\fR, \fBX509_TRUST_EMAIL\fR, \fBX509_TRUST_OBJECT_SIGN\fR,
 293 \&\fBX509_TRUST_OCSP_SIGN\fR, \fBX509_TRUST_OCSP_REQUEST\fR and \fBX509_TRUST_TSA\fR. It is
 294 also possible to create a custom trust value. Since \fBX509_STORE_CTX_set_purpose()\fR
 295 also sets the trust value it is normally sufficient to only call that function.
 296 If both are called then \fBX509_STORE_CTX_set_trust()\fR should be called after
 297 \&\fBX509_STORE_CTX_set_purpose()\fR since the trust setting of the last call will be
 298 used.
 299 .PP
 300 It should not normally be necessary for end user applications to call
 301 \&\fBX509_STORE_CTX_purpose_inherit()\fR directly. Typically applications should call
 302 \&\fBX509_STORE_CTX_set_purpose()\fR or \fBX509_STORE_CTX_set_trust()\fR instead. Using this
 303 function it is possible to set the purpose and trust values for the \fIctx\fR at
 304 the same time. The \fIdef_purpose\fR and \fIpurpose\fR arguments can have the same
 305 purpose values as described for \fBX509_STORE_CTX_set_purpose()\fR above. The \fItrust\fR
 306 argument can have the same trust values as described in
 307 \&\fBX509_STORE_CTX_set_trust()\fR above. Any of the \fIdef_purpose\fR, \fIpurpose\fR or
 308 \&\fItrust\fR values may also have the value 0 to indicate that the supplied
 309 parameter should be ignored. After calling this function the purpose to be used
 310 for verification is set from the \fIpurpose\fR argument, and the trust is set from
 311 the \fItrust\fR argument. If \fItrust\fR is 0 then the trust value will be set from
 312 the default trust value for \fIpurpose\fR. If the default trust value for the
 313 purpose is \fIX509_TRUST_DEFAULT\fR and \fItrust\fR is 0 then the default trust value
 314 associated with the \fIdef_purpose\fR value is used for the trust setting instead.
 315 .SH "NOTES"
 316 .IX Header "NOTES"
 317 The certificates and CRLs in a store are used internally and should \fBnot\fR
 318 be freed up until after the associated \fBX509_STORE_CTX\fR is freed.
 319 .SH "BUGS"
 320 .IX Header "BUGS"
 321 The certificates and CRLs in a context are used internally and should \fBnot\fR
 322 be freed up until after the associated \fBX509_STORE_CTX\fR is freed. Copies
 323 should be made or reference counts increased instead.
 324 .SH "RETURN VALUES"
 325 .IX Header "RETURN VALUES"
 326 \&\fBX509_STORE_CTX_new()\fR returns a newly allocated context or \fB\s-1NULL\s0\fR if an
 327 error occurred.
 328 .PP
 329 \&\fBX509_STORE_CTX_init()\fR returns 1 for success or 0 if an error occurred.
 330 .PP
 331 \&\fBX509_STORE_CTX_get0_param()\fR returns a pointer to an \fBX509_VERIFY_PARAM\fR
 332 structure or \fB\s-1NULL\s0\fR if an error occurred.
 333 .PP
 334 \&\fBX509_STORE_CTX_cleanup()\fR, \fBX509_STORE_CTX_free()\fR,
 335 \&\fBX509_STORE_CTX_set0_trusted_stack()\fR,
 336 \&\fBX509_STORE_CTX_set_cert()\fR,
 337 \&\fBX509_STORE_CTX_set0_crls()\fR and \fBX509_STORE_CTX_set0_param()\fR do not return
 338 values.
 339 .PP
 340 \&\fBX509_STORE_CTX_set_default()\fR returns 1 for success or 0 if an error occurred.
 341 .PP
 342 \&\fBX509_STORE_CTX_get_num_untrusted()\fR returns the number of untrusted certificates
 343 used.
 344 .SH "SEE ALSO"
 345 .IX Header "SEE ALSO"
 346 \&\fBX509_verify_cert\fR\|(3)
 347 \&\fBX509_VERIFY_PARAM_set_flags\fR\|(3)
 348 .SH "HISTORY"
 349 .IX Header "HISTORY"
 350 The \fBX509_STORE_CTX_set0_crls()\fR function was added in OpenSSL 1.0.0.
 351 The \fBX509_STORE_CTX_get_num_untrusted()\fR function was added in OpenSSL 1.1.0.
 352 .SH "COPYRIGHT"
 353 .IX Header "COPYRIGHT"
 354 Copyright 2009\-2022 The OpenSSL Project Authors. All Rights Reserved.
 355 .PP
 356 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 357 this file except in compliance with the License.  You can obtain a copy
 358 in the file \s-1LICENSE\s0 in the source distribution or at
 359 <https://www.openssl.org/source/license.html>.