generic-library/openssl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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

Browse Source
This commit is contained in:
cvs2svn
2000-10-03 22:02:29 +00:00
parent 19a5e404cb 356c06c776
commit 4ef897d1fc
4 changed files with 297 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
doc/ssl/SSL_CTX_load_verify_locations.pod Normal file
View File

@@ -0,0 +1,93 @@
=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

90
doc/ssl/SSL_CTX_set_client_CA_list.pod Normal file
View File

@@ -0,0 +1,90 @@
=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

52
doc/ssl/SSL_get_client_CA_list.pod Normal file
View File

@@ -0,0 +1,52 @@
=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

62
doc/ssl/SSL_load_client_CA_file.pod Normal file
View File

@@ -0,0 +1,62 @@
=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