doc/man3/X509_STORE_CTX_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 X509_STORE_CTX_new_ex, X509_STORE_CTX_new, X509_STORE_CTX_cleanup,
   6 X509_STORE_CTX_free, X509_STORE_CTX_init, X509_STORE_CTX_set0_trusted_stack,
   7 X509_STORE_CTX_set_cert, X509_STORE_CTX_set0_crls,
   8 X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain,
   9 X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param,
  10 X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted,
  11 X509_STORE_CTX_get_num_untrusted,
  12 X509_STORE_CTX_set_default,
  13 X509_STORE_CTX_set_verify,
  14 X509_STORE_CTX_verify_fn
  15 - X509_STORE_CTX initialisation
  16
  17 =head1 SYNOPSIS
  18
  19  #include <openssl/x509_vfy.h>
  20
  21  X509_STORE_CTX *X509_STORE_CTX_new_ex(OSSL_LIB_CTX *libctx, const char *propq);
  22  X509_STORE_CTX *X509_STORE_CTX_new(void);
  23  void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx);
  24  void X509_STORE_CTX_free(X509_STORE_CTX *ctx);
  25
  26  int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *trust_store,
  27                          X509 *target, STACK_OF(X509) *chain);
  28
  29  void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
  30
  31  void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *x);
  32  STACK_OF(X509) *X509_STORE_CTX_get0_chain(const X509_STORE_CTX *ctx);
  33  void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain);
  34  void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk);
  35
  36  X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(const X509_STORE_CTX *ctx);
  37  void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param);
  38  int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name);
  39
  40  STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(const X509_STORE_CTX *ctx);
  41  void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
  42
  43  int X509_STORE_CTX_get_num_untrusted(const X509_STORE_CTX *ctx);
  44
  45  typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *);
  46  void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify);
  47
  48 =head1 DESCRIPTION
  49
  50 These functions initialise an B<X509_STORE_CTX> structure for subsequent use
  51 by L<X509_verify_cert(3)> or L<X509_STORE_CTX_verify(3)>.
  52
  53 X509_STORE_CTX_new_ex() returns a newly initialised B<X509_STORE_CTX>
  54 structure associated with the specified library context I<libctx> and property
  55 query string I<propq>. Any cryptographic algorithms fetched while performing
  56 processing with the X509_STORE_CTX will use that library context and property
  57 query string.
  58
  59 X509_STORE_CTX_new() is the same as X509_STORE_CTX_new_ex() except that
  60 the default library context and a NULL property query string are used.
  61
  62 X509_STORE_CTX_cleanup() internally cleans up an B<X509_STORE_CTX> structure.
  63 It is used by X509_STORE_CTX_init() and X509_STORE_CTX_free().
  64
  65 X509_STORE_CTX_free() completely frees up I<ctx>. After this call I<ctx>
  66 is no longer valid.
  67 If I<ctx> is NULL nothing is done.
  68
  69 X509_STORE_CTX_init() sets up I<ctx> for a subsequent verification operation.
  70 It must be called before each call to L<X509_verify_cert(3)> or
  71 L<X509_STORE_CTX_verify(3)>, i.e., a context is only good for one verification.
  72 If you want to verify a further certificate or chain with the same I<ctx>
  73 then you must call X509_STORE_CTX_init() again.
  74 The trusted certificate store is set to I<trust_store> of type B<X509_STORE>.
  75 This may be NULL because there are no trusted certificates or because
  76 they are provided simply as a list using X509_STORE_CTX_set0_trusted_stack().
  77 The certificate to be verified is set to I<target>,
  78 and a list of additional certificates may be provided in I<chain>,
  79 which will be untrusted but may be used to build the chain.
  80 Each of the I<trust_store>, I<target> and I<chain> parameters can be NULL.
  81 Yet note that L<X509_verify_cert(3)> and L<X509_STORE_CTX_verify(3)>
  82 will need a verification target.
  83 This can also be set using X509_STORE_CTX_set_cert().
  84 For L<X509_STORE_CTX_verify(3)>, which takes by default the first element of the
  85 list of untrusted certificates as its verification target,
  86 this can be also set indirectly using X509_STORE_CTX_set0_untrusted().
  87
  88 X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates of
  89 I<ctx> to I<sk>. This is an alternative way of specifying trusted certificates
  90 instead of using an B<X509_STORE>.
  91
  92 X509_STORE_CTX_set_cert() sets the target certificate to be verified in I<ctx>
  93 to I<x>.
  94
  95 X509_STORE_CTX_set0_verified_chain() sets the validated chain used
  96 by I<ctx> to be I<chain>.
  97 Ownership of the chain is transferred to I<ctx> and should not be
  98 free'd by the caller.
  99 X509_STORE_CTX_get0_chain() returns the internal pointer used by the
 100 I<ctx> that contains the validated chain.
 101
 102 X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate
 103 verification to I<sk>. These CRLs will only be used if CRL verification is
 104 enabled in the associated B<X509_VERIFY_PARAM> structure. This might be
 105 used where additional "useful" CRLs are supplied as part of a protocol,
 106 for example in a PKCS#7 structure.
 107
 108 X509_STORE_CTX_get0_param() retrieves an internal pointer
 109 to the verification parameters associated with I<ctx>.
 110
 111 X509_STORE_CTX_get0_untrusted() retrieves an internal pointer to the
 112 stack of untrusted certificates associated with I<ctx>.
 113
 114 X509_STORE_CTX_set0_untrusted() sets the internal pointer to the stack
 115 of untrusted certificates associated with I<ctx> to I<sk>.
 116 X509_STORE_CTX_verify() will take the first element, if any,
 117 as its default target if the target certificate is not set explicitly.
 118
 119 X509_STORE_CTX_set0_param() sets the internal verification parameter pointer
 120 to I<param>. After this call B<param> should not be used.
 121
 122 X509_STORE_CTX_set_default() looks up and sets the default verification
 123 method to I<name>. This uses the function X509_VERIFY_PARAM_lookup() to
 124 find an appropriate set of parameters from I<name>.
 125
 126 X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates
 127 that were used in building the chain following a call to L<X509_verify_cert(3)>.
 128 With L<X509_STORE_CTX_verify(3)>, this does not count the first chain element.
 129
 130 X509_STORE_CTX_set_verify() provides the capability for overriding the default
 131 verify function. This function is responsible for verifying chain signatures and
 132 expiration times.
 133
 134 A verify function is defined as an X509_STORE_CTX_verify type which has the
 135 following signature:
 136
 137  int (*verify)(X509_STORE_CTX *);
 138
 139 This function should receive the current X509_STORE_CTX as a parameter and
 140 return 1 on success or 0 on failure.
 141
 142 =head1 NOTES
 143
 144 The certificates and CRLs in a store are used internally and should B<not>
 145 be freed up until after the associated B<X509_STORE_CTX> is freed.
 146
 147 =head1 BUGS
 148
 149 The certificates and CRLs in a context are used internally and should B<not>
 150 be freed up until after the associated B<X509_STORE_CTX> is freed. Copies
 151 should be made or reference counts increased instead.
 152
 153 =head1 RETURN VALUES
 154
 155 X509_STORE_CTX_new() returns a newly allocated context or NULL if an
 156 error occurred.
 157
 158 X509_STORE_CTX_init() returns 1 for success or 0 if an error occurred.
 159
 160 X509_STORE_CTX_get0_param() returns a pointer to an B<X509_VERIFY_PARAM>
 161 structure or NULL if an error occurred.
 162
 163 X509_STORE_CTX_cleanup(), X509_STORE_CTX_free(),
 164 X509_STORE_CTX_set0_trusted_stack(),
 165 X509_STORE_CTX_set_cert(),
 166 X509_STORE_CTX_set0_crls() and X509_STORE_CTX_set0_param() do not return
 167 values.
 168
 169 X509_STORE_CTX_set_default() returns 1 for success or 0 if an error occurred.
 170
 171 X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates
 172 used.
 173
 174 =head1 SEE ALSO
 175
 176 L<X509_verify_cert(3)>, L<X509_STORE_CTX_verify(3)>,
 177 L<X509_VERIFY_PARAM_set_flags(3)>
 178
 179 =head1 HISTORY
 180
 181 The X509_STORE_CTX_set0_crls() function was added in OpenSSL 1.0.0.
 182 The X509_STORE_CTX_get_num_untrusted() function was added in OpenSSL 1.1.0.
 183 The X509_STORE_CTX_new_ex() function was added in OpenSSL 3.0.
 184
 185 There is no need to call X509_STORE_CTX_cleanup() explicitly since OpenSSL 3.0.
 186
 187 =head1 COPYRIGHT
 188
 189 Copyright 2009-2021 The OpenSSL Project Authors. All Rights Reserved.
 190
 191 Licensed under the Apache License 2.0 (the "License").  You may not use
 192 this file except in compliance with the License.  You can obtain a copy
 193 in the file LICENSE in the source distribution or at
 194 L<https://www.openssl.org/source/license.html>.
 195
 196 =cut