This commit was manufactured by cvs2svn to create branch 'BRANCH_engine'.

=pod

=head1 NAME

SSL_CTX_load_verify_locations - set default locations for trusted CA

certificates

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,

                                   const char *CApath);

=head1 DESCRIPTION

SSL_CTX_load_verify_locations() specifies the locations for B<ctx>, at

which CA certificates for verification purposes are located. The certificates

available via B<CAfile> and B<CApath> are trusted.

=head1 NOTES

If B<CAfile> is not NULL, it points to a file of CA certificates in PEM

format. The file can contain several CA certificates identified by

 -----BEGIN CERTIFICATE-----

 ... (CA certificate in base64 encoding) ...

 -----END CERTIFICATE-----

sequences. Before, between, and after the certificates text is allowed

which can be used e.g. for descriptions of the certificates.

The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations()

function.

If on an TLS/SSL server no special setting is perfomed using *client_CA_list()

functions, the certificates contained in B<CAfile> are listed to the client

as available CAs during the TLS/SSL handshake.

If B<CApath> is not NULL, it points to a directory containing CA certificates

in PEM format. The files each contain one CA certificate. The files are

looked up by the CA subject name hash value, which must hence be available.

Use the B<c_rehash> utility to create the necessary links.

The certificates in B<CAfile> are only looked up when required, e.g. when

building the certificate chain or when actually performing the verification

of a peer certificate.

On a server, the certificates in B<CApath> are not listed as available

CA certificates to a client during a TLS/SSL handshake.

=head1 EXAMPLES

Generate a CA certificate file with descriptive text from the CA certificates

ca1.pem ca2.pem ca3.pem:

 #!/bin/sh

 rm CAfile.pem

 for i in ca1.pem ca2.pem ca3.pem ; do

   openssl x509 -in $i -text >> CAfile.pem

 done

Prepare the directory /some/where/certs containing several CA certificates

for use as B<CApath>:

 cd /some/where/certs

 c_rehash

=head1 RETURN VALUES

The following return values can occur:

=over 4

=item 0

The operation failed because B<CAfile> and B<CApath> are NULL or the

processing at one of the locations specified failed. Check the error

stack to find out the reason.

=item 1

The operation succeeded.

=back

=head1 SEE ALSO

L<ssl(3)|ssl(3)>,

L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,

L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>

=cut

=pod

=head1 NAME

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

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 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);

=head1 DESCRIPTION

SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when

requesting a client certificate for B<ctx>.

SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when

requesting a client certificate for the chosen B<ssl>, overriding the

setting valid for B<ssl>'s SSL_CTX object.

SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the

list of CAs sent to the client when requesting a client certificate for

B<ctx>.

SSL_add_client_CA() adds the CA name extracted from B<cacert> to the

list of CAs sent to the client when requesting a client certificate for

the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.

=head1 NOTES

When a TLS/SSL server requests a client certificate (see

B<SSL_CTX_set_verify_options()>), it sends a list of CAs, for which

it will accept certificates, to the client. If no special list is provided,

the CAs available using the B<CAfile> option in

L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>

are sent.

This list can be explicitely set using the SSL_CTX_set_client_CA_list() for

B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list

specified overrides the previous setting. The CAs listed do not become

trusted (B<list> only contains the names, not the complete certificates); use

L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> 

to additionally load them for verification.

SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional

items the list of client CAs. If no list was specified before using

SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client

CA list for B<ctx> or B<ssl> (as appropriate) is opened. The CAs implicitly

specified using

L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>

are no longer used automatically.

These functions are only useful for TLS/SSL servers.

=head1 RETURN VALUES

SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return

diagnostic information.

SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return

values:

=over 4

=item 1

The operation succeeded.

=item 0

A failure while manipulating the STACK_OF(X509_NAME) object occured or

the X509_NAME could not be extracted from B<cacert>. Check the error stack

to find out the reason.

=back

=head1 SEE ALSO

L<ssl(3)|ssl(3)>,

L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,

L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>

L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>

=cut

=pod

=head1 NAME

SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 STACK_OF(X509_NAME) *SSL_get_client_CA_list(SSL *s);

 STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(SSL_CTX *ctx); 

=head1 DESCRIPTION

SSL_CTX_get_client_CA_list() returns the list of client CAs explicitely set for

B<ctx> using L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>.

SSL_get_client_CA_list() returns the list of client CAs explicitely

set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with

L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, when in

server mode. In client mode, SSL_get_client_CA_list returns the list of

client CAs sent from the server, if any.

=head1 RETURN VALUES

SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return

diagnostic information.

SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return

values:

=over 4

=item STACK_OF(X509_NAMES)

List of CA names explicitely set (for B<ctx> or in server mode) or send

by the server (client mode).

=item NULL

No client CA list was explicitely set (for B<ctx> or in server mode) or

the server did not send a list of CAs (client mode).

=back

=head1 SEE ALSO

L<ssl(3)|ssl(3)>,

L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>

=cut

=pod

=head1 NAME

SSL_load_client_CA_file - load certificate names from file

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file);

=head1 DESCRIPTION

SSL_load_client_CA_file() reads certificates from B<file> and returns

a STACK_OF(X509_NAME) with the subject names found.

=head1 NOTES

SSL_load_client_CA_file() reads a file of PEM formatted certificates and

extracts the X509_NAMES of the certificates found. While the name suggests

the specific usage as support function for

L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,

it is not limited to CA certificates.

=head1 EXAMPLES

Load names of CAs from file and use it as a client CA list:

 SSL_CTX *ctx;

 STACK_OF(X509_NAME) *cert_names;

 ... 

 cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");

 if (cert_names != NULL)

   SSL_CTX_set_client_CA_list(ctx, cert_names);

 else

   error_handling();

 ...

=head1 RETURN VALUES

The following return values can occur:

=over 4

=item NULL

The operation failed, check out the error stack for the reason.

=item Pointer to STACK_OF(X509_NAME)

Pointer to the subject names of the successfully read certificates.

=back

=head1 SEE ALSO

L<ssl(3)|ssl(3)>,

L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>

=cut