Hi! Some manual pages about SSL_CTX_load_verify_locations() and friends. Best regards, Lutz -- Lutz Jaenicke [EMAIL PROTECTED] BTU Cottbus http://www.aet.TU-Cottbus.DE/personen/jaenicke/ Lehrstuhl Allgemeine Elektrotechnik Tel. +49 355 69-4129 Universitaetsplatz 3-4, D-03044 Cottbus Fax. +49 355 69-4153
diff -r -c --new-file openssl-SNAP-20000926-vanilla/doc/ssl/SSL_CTX_load_verify_locations.pod openssl-SNAP-20000926/doc/ssl/SSL_CTX_load_verify_locations.pod *** openssl-SNAP-20000926-vanilla/doc/ssl/SSL_CTX_load_verify_locations.pod Thu Jan 1 01:00:00 1970 --- openssl-SNAP-20000926/doc/ssl/SSL_CTX_load_verify_locations.pod Tue Oct 3 17:17:34 2000 *************** *** 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 diff -r -c --new-file openssl-SNAP-20000926-vanilla/doc/ssl/SSL_CTX_set_client_CA_list.pod openssl-SNAP-20000926/doc/ssl/SSL_CTX_set_client_CA_list.pod *** openssl-SNAP-20000926-vanilla/doc/ssl/SSL_CTX_set_client_CA_list.pod Thu Jan 1 01:00:00 1970 --- openssl-SNAP-20000926/doc/ssl/SSL_CTX_set_client_CA_list.pod Tue Oct 3 18:17:10 2000 *************** *** 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 diff -r -c --new-file openssl-SNAP-20000926-vanilla/doc/ssl/SSL_get_client_CA_list.pod openssl-SNAP-20000926/doc/ssl/SSL_get_client_CA_list.pod *** openssl-SNAP-20000926-vanilla/doc/ssl/SSL_get_client_CA_list.pod Thu Jan 1 01:00:00 1970 --- openssl-SNAP-20000926/doc/ssl/SSL_get_client_CA_list.pod Tue Oct 3 17:16:16 2000 *************** *** 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 diff -r -c --new-file openssl-SNAP-20000926-vanilla/doc/ssl/SSL_load_client_CA_file.pod openssl-SNAP-20000926/doc/ssl/SSL_load_client_CA_file.pod *** openssl-SNAP-20000926-vanilla/doc/ssl/SSL_load_client_CA_file.pod Thu Jan 1 01:00:00 1970 --- openssl-SNAP-20000926/doc/ssl/SSL_load_client_CA_file.pod Tue Oct 3 18:15:01 2000 *************** *** 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 diff -r -c --new-file openssl-SNAP-20000926-vanilla/doc/ssl/ssl.pod openssl-SNAP-20000926/doc/ssl/ssl.pod *** openssl-SNAP-20000926-vanilla/doc/ssl/ssl.pod Sat Sep 23 10:00:31 2000 --- openssl-SNAP-20000926/doc/ssl/ssl.pod Tue Oct 3 17:19:49 2000 *************** *** 625,639 **** L<openssl(1)|openssl(1)>, L<crypto(3)|crypto(3)>, L<SSL_accept(3)|SSL_accept(3)>, L<SSL_clear(3)|SSL_clear(3)>, ! L<SSL_connect(3)|SSL_connect(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_get_fd(3)|SSL_get_fd(3)>, L<SSL_get_peer_cert_chain(3)|SSL_get_peer_cert_chain(3)>, L<SSL_get_rbio(3)|SSL_get_rbio(3)>, L<SSL_get_session(3)|SSL_get_session(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, ! L<SSL_library_init(3)|SSL_library_init(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_read(3)|SSL_read(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>, L<SSL_set_fd(3)|SSL_set_fd(3)>, L<SSL_pending(3)|SSL_pending(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, --- 625,645 ---- L<openssl(1)|openssl(1)>, L<crypto(3)|crypto(3)>, L<SSL_accept(3)|SSL_accept(3)>, L<SSL_clear(3)|SSL_clear(3)>, ! L<SSL_connect(3)|SSL_connect(3)>, ! L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> ! L<SSL_CTX_new(3)|SSL_CTX_new(3)>, ! L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)> L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, + L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_get_fd(3)|SSL_get_fd(3)>, L<SSL_get_peer_cert_chain(3)|SSL_get_peer_cert_chain(3)>, L<SSL_get_rbio(3)|SSL_get_rbio(3)>, L<SSL_get_session(3)|SSL_get_session(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, ! L<SSL_library_init(3)|SSL_library_init(3)>, ! L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>, ! L<SSL_new(3)|SSL_new(3)>, L<SSL_read(3)|SSL_read(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>, L<SSL_set_fd(3)|SSL_set_fd(3)>, L<SSL_pending(3)|SSL_pending(3)>, L<SSL_set_session(3)|SSL_set_session(3)>,