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