#use wml::openssl-macros area=docs page=X509_STORE_CTX_new

<title>Documents, X509_STORE_CTX_new(3)</title>

<h1>X509_STORE_CTX_new(3)</h1>

#use wml::imp::generic

{:
## What's this? [[s|(<STRONG>[^<].+?)</A>(</STRONG><DD>)|$1$2|sg]]
[[s|<P>\s+<P>|<P>|sg]]
[[s|<P>\s+</|</|sg]]
[[s|<DD>\s*<DT>|<DD>&nbsp;<DT>|sg]]
[[s|<DD>\s*</DL>|<DD>&nbsp;</DL>|sg]]
[[s|\[|&#91;|sg]]
[[s|\]|&#93;|sg]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#NOTES">NOTES</A>
	<LI><A HREF="#BUGS">BUGS</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
	<LI><A HREF="#HISTORY">HISTORY</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
X509_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

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/x509_vfy.h&gt;
</PRE>
<PRE> X509_STORE_CTX *X509_STORE_CTX_new(void);
 void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx);
 void X509_STORE_CTX_free(X509_STORE_CTX *ctx);
</PRE>
<PRE> int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store,
                         X509 *x509, STACK_OF(X509) *chain);
</PRE>
<PRE> void X509_STORE_CTX_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
</PRE>
<PRE> void   X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx,X509 *x);
 void   X509_STORE_CTX_set_chain(X509_STORE_CTX *ctx,STACK_OF(X509) *sk);
 void   X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk);
</PRE>
<PRE> X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(X509_STORE_CTX *ctx);
 void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param);
 int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
These functions initialise an <STRONG>X509_STORE_CTX</STRONG> structure for subsequent use by <CODE>X509_verify_cert().</CODE>

</P>
<P>
<CODE>X509_STORE_CTX_new()</CODE> returns a newly initialised <STRONG>X509_STORE_CTX</STRONG> structure.

</P>
<P>
<CODE>X509_STORE_CTX_cleanup()</CODE> internally cleans up an <STRONG>X509_STORE_CTX</STRONG> structure. The context can then be reused with an new call to
<CODE>X509_STORE_CTX_init().</CODE>

</P>
<P>
<CODE>X509_STORE_CTX_free()</CODE> completely frees up <STRONG>ctx</STRONG>. After this call <STRONG>ctx</STRONG>
is no longer valid.

</P>
<P>
<CODE>X509_STORE_CTX_init()</CODE> sets up <STRONG>ctx</STRONG> for a subsequent verification operation. The trusted certificate store is
set to <STRONG>store</STRONG>, the end entity certificate to be verified is set to <STRONG>x509</STRONG> and a set of additional certificates (which will be untrusted but may be
used to build the chain) in <STRONG>chain</STRONG>. Any or all of the <STRONG>store</STRONG>, <STRONG>x509</STRONG> and <STRONG>chain</STRONG> parameters can be <STRONG>NULL</STRONG>.

</P>
<P>
<CODE>X509_STORE_CTX_trusted_stack()</CODE> sets the set of trusted
certificates of <STRONG>ctx</STRONG>
to <STRONG>sk</STRONG>. This is an alternative way of specifying trusted certificates instead of
using an <STRONG>X509_STORE</STRONG>.

</P>
<P>
<CODE>X509_STORE_CTX_set_cert()</CODE> sets the certificate to be vertified
in <STRONG>ctx</STRONG> to
<STRONG>x</STRONG>.

</P>
<P>
<CODE>X509_STORE_CTX_set_chain()</CODE> sets the additional certificate
chain used by <STRONG>ctx</STRONG>
to <STRONG>sk</STRONG>.

</P>
<P>
<CODE>X509_STORE_CTX_set0_crls()</CODE> sets a set of CRLs to use to aid
certificate verification to <STRONG>sk</STRONG>. These CRLs will only be used if CRL verification is enabled in the
associated <STRONG>X509_VERIFY_PARAM</STRONG> structure. This might be used where additional ``useful'' CRLs are supplied
as part of a protocol, for example in a PKCS#7 structure.

</P>
<P>
X509_VERIFY_PARAM *X509_STORE_CTX_get0_param() retrieves an intenal pointer
to the verification parameters associated with <STRONG>ctx</STRONG>.

</P>
<P>
<CODE>X509_STORE_CTX_set0_param()</CODE> sets the intenal verification
parameter pointer to <STRONG>param</STRONG>. After this call <STRONG>param</STRONG> should not be used.

</P>
<P>
<CODE>X509_STORE_CTX_set_default()</CODE> looks up and sets the default
verification method to <STRONG>name</STRONG>. This uses the function <CODE>X509_VERIFY_PARAM_lookup()</CODE> to find an
appropriate set of parameters from <STRONG>name</STRONG>.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
The certificates and CRLs in a store are used internally and should <STRONG>not</STRONG>
be freed up until after the associated <STRONG>X509_STORE_CTX</STRONG> is freed. Legacy applications might implicitly use an <STRONG>X509_STORE_CTX</STRONG> like this:

</P>
<PRE>  X509_STORE_CTX ctx;
  X509_STORE_CTX_init(&amp;ctx, store, cert, chain);
</PRE>
<P>
this is <STRONG>not</STRONG> recommended in new applications they should instead do:

</P>
<PRE>  X509_STORE_CTX *ctx;
  ctx = X509_STORE_CTX_new();
  if (ctx == NULL)
        /* Bad error */
  X509_STORE_CTX_init(ctx, store, cert, chain);
</PRE>
<P>
<HR>
<H1><A NAME="BUGS">BUGS</A></H1>
<P>
The certificates and CRLs in a context are used internally and should <STRONG>not</STRONG>
be freed up until after the associated <STRONG>X509_STORE_CTX</STRONG> is freed. Copies should be made or reference counts increased instead.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>X509_STORE_CTX_new()</CODE> returns an newly allocates context or <STRONG>NULL</STRONG> is an error occurred.

</P>
<P>
<CODE>X509_STORE_CTX_init()</CODE> returns 1 for success or 0 if an error
occurred.

</P>
<P>
<CODE>X509_STORE_CTX_get0_param()</CODE> returns a pointer to an <STRONG>X509_VERIFY_PARAM</STRONG>
structure or <STRONG>NULL</STRONG> if an error occurred.

</P>
<P>
<CODE>X509_STORE_CTX_cleanup(),</CODE> <CODE>X509_STORE_CTX_free(),</CODE>
<CODE>X509_STORE_CTX_trusted_stack(),</CODE>
<CODE>X509_STORE_CTX_set_cert(),</CODE>
<CODE>X509_STORE_CTX_set_chain(),</CODE>
<CODE>X509_STORE_CTX_set0_crls()</CODE> and
<CODE>X509_STORE_CTX_set0_param()</CODE> do not return values.

</P>
<P>
<CODE>X509_STORE_CTX_set_default()</CODE> returns 1 for success or 0 if an
error occurred.

</P>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../crypto/X509_verify_cert.html#">X509_verify_cert(3)</A>

<A HREF="../crypto/X509_VERIFY_PARAM_set_flags.html#">X509_VERIFY_PARAM_set_flags(3)</A>



</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
<P>
<CODE>X509_STORE_CTX_set0_crls()</CODE> was first added to OpenSSL 1.0.0

</P>
:}