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

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

<h1>SSL_CTX_set_client_CA_list(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="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#EXAMPLES">EXAMPLES</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
SSL_add_client_CA - set list of CAs sent to the client when requesting a
client certificate

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/ssl.h&gt;
 
 void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
 void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
 int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
 int SSL_add_client_CA(SSL *ssl, X509 *cacert);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>SSL_CTX_set_client_CA_list()</CODE> sets the <STRONG>list</STRONG> of CAs sent to the client when requesting a client certificate for <STRONG>ctx</STRONG>.

</P>
<P>
<CODE>SSL_set_client_CA_list()</CODE> sets the <STRONG>list</STRONG> of CAs sent to the client when requesting a client certificate for the
chosen <STRONG>ssl</STRONG>, overriding the setting valid for <STRONG>ssl</STRONG>'s SSL_CTX object.

</P>
<P>
<CODE>SSL_CTX_add_client_CA()</CODE> adds the CA name extracted from <STRONG>cacert</STRONG> to the list of CAs sent to the client when requesting a client certificate
for
<STRONG>ctx</STRONG>.

</P>
<P>
<CODE>SSL_add_client_CA()</CODE> adds the CA name extracted from <STRONG>cacert</STRONG> to the list of CAs sent to the client when requesting a client certificate
for the chosen <STRONG>ssl</STRONG>, overriding the setting valid for <STRONG>ssl</STRONG>'s SSL_CTX object.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
When a TLS/SSL server requests a client certificate (see
<STRONG>SSL_CTX_set_verify_options()</STRONG>), it sends a list of CAs, for which it will accept certificates, to the
client.

</P>
<P>
This list must explicitly be set using
<CODE>SSL_CTX_set_client_CA_list()</CODE> for
<STRONG>ctx</STRONG> and <CODE>SSL_set_client_CA_list()</CODE> for the specific <STRONG>ssl</STRONG>. The list specified overrides the previous setting. The CAs listed do not
become trusted (<STRONG>list</STRONG> only contains the names, not the complete certificates); use
<A HREF="../ssl/SSL_CTX_load_verify_locations.html#">SSL_CTX_load_verify_locations(3)</A> 
to additionally load them for verification.

</P>
<P>
If the list of acceptable CAs is compiled in a file, the
<A HREF="../ssl/SSL_load_client_CA_file.html#">SSL_load_client_CA_file(3)</A>
function can be used to help importing the necessary data.

</P>
<P>
<CODE>SSL_CTX_add_client_CA()</CODE> and <CODE>SSL_add_client_CA()</CODE>
can be used to add additional items the list of client CAs. If no list was
specified before using <CODE>SSL_CTX_set_client_CA_list()</CODE> or
<CODE>SSL_set_client_CA_list(),</CODE> a new client CA list for <STRONG>ctx</STRONG> or <STRONG>ssl</STRONG> (as appropriate) is opened.

</P>
<P>
These functions are only useful for TLS/SSL servers.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>SSL_CTX_set_client_CA_list()</CODE> and
<CODE>SSL_set_client_CA_list()</CODE> do not return diagnostic information.

</P>
<P>
<CODE>SSL_CTX_add_client_CA()</CODE> and <CODE>SSL_add_client_CA()</CODE>
have the following return values:

</P>
<DL>
<DT><STRONG><A NAME="item_1">1</A></STRONG><DD>
<P>
The operation succeeded.

</P>
<DT><STRONG><A NAME="item_0">0</A></STRONG><DD>
<P>
A failure while manipulating the <CODE>STACK_OF(X509_NAME)</CODE> object
occurred or the X509_NAME could not be extracted from <STRONG>cacert</STRONG>. Check the error stack to find out the reason.

</P>
</DL>
<P>
<HR>
<H1><A NAME="EXAMPLES">EXAMPLES</A></H1>
<P>
Scan all certificates in <STRONG>CAfile</STRONG> and list them as acceptable CAs:

</P>
<PRE>  SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile));
</PRE>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../ssl/ssl.html#">ssl(3)</A>,
<A HREF="../ssl/SSL_get_client_CA_list.html#">SSL_get_client_CA_list(3)</A>,
<A HREF="../ssl/SSL_load_client_CA_file.html#">SSL_load_client_CA_file(3)</A>,
<A HREF="../ssl/SSL_CTX_load_verify_locations.html#">SSL_CTX_load_verify_locations(3)</A>



</P>
:}