1238384Sjkim=pod 2238384Sjkim 3238384Sjkim=head1 NAME 4238384Sjkim 5238384SjkimX509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, X509_STORE_CTX_init, X509_STORE_CTX_trusted_stack, X509_STORE_CTX_set_cert, X509_STORE_CTX_set_chain, X509_STORE_CTX_set0_crls, X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, X509_STORE_CTX_set_default - X509_STORE_CTX initialisation 6238384Sjkim 7238384Sjkim=head1 SYNOPSIS 8238384Sjkim 9238384Sjkim #include <openssl/x509_vfy.h> 10238384Sjkim 11238384Sjkim X509_STORE_CTX *X509_STORE_CTX_new(void); 12238384Sjkim void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx); 13238384Sjkim void X509_STORE_CTX_free(X509_STORE_CTX *ctx); 14238384Sjkim 15238384Sjkim int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store, 16238384Sjkim X509 *x509, STACK_OF(X509) *chain); 17238384Sjkim 18238384Sjkim void X509_STORE_CTX_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); 19238384Sjkim 20238384Sjkim void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx,X509 *x); 21238384Sjkim void X509_STORE_CTX_set_chain(X509_STORE_CTX *ctx,STACK_OF(X509) *sk); 22238384Sjkim void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk); 23238384Sjkim 24238384Sjkim X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(X509_STORE_CTX *ctx); 25238384Sjkim void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param); 26238384Sjkim int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name); 27238384Sjkim 28238384Sjkim=head1 DESCRIPTION 29238384Sjkim 30238384SjkimThese functions initialise an B<X509_STORE_CTX> structure for subsequent use 31238384Sjkimby X509_verify_cert(). 32238384Sjkim 33238384SjkimX509_STORE_CTX_new() returns a newly initialised B<X509_STORE_CTX> structure. 34238384Sjkim 35238384SjkimX509_STORE_CTX_cleanup() internally cleans up an B<X509_STORE_CTX> structure. 36238384SjkimThe context can then be reused with an new call to X509_STORE_CTX_init(). 37238384Sjkim 38238384SjkimX509_STORE_CTX_free() completely frees up B<ctx>. After this call B<ctx> 39238384Sjkimis no longer valid. 40238384Sjkim 41238384SjkimX509_STORE_CTX_init() sets up B<ctx> for a subsequent verification operation. 42285329SjkimIt must be called before each call to X509_verify_cert(), i.e. a B<ctx> is only 43285329Sjkimgood for one call to X509_verify_cert(); if you want to verify a second 44325335Sjkimcertificate with the same B<ctx> then you must call X509_STORE_CTX_cleanup() 45285329Sjkimand then X509_STORE_CTX_init() again before the second call to 46285329SjkimX509_verify_cert(). The trusted certificate store is set to B<store>, the end 47285329Sjkimentity certificate to be verified is set to B<x509> and a set of additional 48285329Sjkimcertificates (which will be untrusted but may be used to build the chain) in 49285329SjkimB<chain>. Any or all of the B<store>, B<x509> and B<chain> parameters can be 50285329SjkimB<NULL>. 51238384Sjkim 52238384SjkimX509_STORE_CTX_trusted_stack() sets the set of trusted certificates of B<ctx> 53238384Sjkimto B<sk>. This is an alternative way of specifying trusted certificates 54238384Sjkiminstead of using an B<X509_STORE>. 55238384Sjkim 56238384SjkimX509_STORE_CTX_set_cert() sets the certificate to be vertified in B<ctx> to 57238384SjkimB<x>. 58238384Sjkim 59238384SjkimX509_STORE_CTX_set_chain() sets the additional certificate chain used by B<ctx> 60238384Sjkimto B<sk>. 61238384Sjkim 62238384SjkimX509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate 63238384Sjkimverification to B<sk>. These CRLs will only be used if CRL verification is 64238384Sjkimenabled in the associated B<X509_VERIFY_PARAM> structure. This might be 65238384Sjkimused where additional "useful" CRLs are supplied as part of a protocol, 66238384Sjkimfor example in a PKCS#7 structure. 67238384Sjkim 68238384SjkimX509_VERIFY_PARAM *X509_STORE_CTX_get0_param() retrieves an intenal pointer 69238384Sjkimto the verification parameters associated with B<ctx>. 70238384Sjkim 71238384SjkimX509_STORE_CTX_set0_param() sets the intenal verification parameter pointer 72238384Sjkimto B<param>. After this call B<param> should not be used. 73238384Sjkim 74238384SjkimX509_STORE_CTX_set_default() looks up and sets the default verification 75238384Sjkimmethod to B<name>. This uses the function X509_VERIFY_PARAM_lookup() to 76238384Sjkimfind an appropriate set of parameters from B<name>. 77238384Sjkim 78238384Sjkim=head1 NOTES 79238384Sjkim 80238384SjkimThe certificates and CRLs in a store are used internally and should B<not> 81238384Sjkimbe freed up until after the associated B<X509_STORE_CTX> is freed. Legacy 82238384Sjkimapplications might implicitly use an B<X509_STORE_CTX> like this: 83238384Sjkim 84238384Sjkim X509_STORE_CTX ctx; 85238384Sjkim X509_STORE_CTX_init(&ctx, store, cert, chain); 86238384Sjkim 87238384Sjkimthis is B<not> recommended in new applications they should instead do: 88238384Sjkim 89238384Sjkim X509_STORE_CTX *ctx; 90238384Sjkim ctx = X509_STORE_CTX_new(); 91238384Sjkim if (ctx == NULL) 92238384Sjkim /* Bad error */ 93238384Sjkim X509_STORE_CTX_init(ctx, store, cert, chain); 94238384Sjkim 95238384Sjkim=head1 BUGS 96238384Sjkim 97238384SjkimThe certificates and CRLs in a context are used internally and should B<not> 98238384Sjkimbe freed up until after the associated B<X509_STORE_CTX> is freed. Copies 99238384Sjkimshould be made or reference counts increased instead. 100238384Sjkim 101238384Sjkim=head1 RETURN VALUES 102238384Sjkim 103238384SjkimX509_STORE_CTX_new() returns an newly allocates context or B<NULL> is an 104238384Sjkimerror occurred. 105238384Sjkim 106238384SjkimX509_STORE_CTX_init() returns 1 for success or 0 if an error occurred. 107238384Sjkim 108238384SjkimX509_STORE_CTX_get0_param() returns a pointer to an B<X509_VERIFY_PARAM> 109238384Sjkimstructure or B<NULL> if an error occurred. 110238384Sjkim 111238384SjkimX509_STORE_CTX_cleanup(), X509_STORE_CTX_free(), X509_STORE_CTX_trusted_stack(), 112238384SjkimX509_STORE_CTX_set_cert(), X509_STORE_CTX_set_chain(), 113238384SjkimX509_STORE_CTX_set0_crls() and X509_STORE_CTX_set0_param() do not return 114238384Sjkimvalues. 115238384Sjkim 116238384SjkimX509_STORE_CTX_set_default() returns 1 for success or 0 if an error occurred. 117238384Sjkim 118238384Sjkim=head1 SEE ALSO 119238384Sjkim 120238384SjkimL<X509_verify_cert(3)|X509_verify_cert(3)> 121238384SjkimL<X509_VERIFY_PARAM_set_flags(3)|X509_VERIFY_PARAM_set_flags(3)> 122238384Sjkim 123238384Sjkim=head1 HISTORY 124238384Sjkim 125238384SjkimX509_STORE_CTX_set0_crls() was first added to OpenSSL 1.0.0 126238384Sjkim 127238384Sjkim=cut 128