More SSL functions documented. Submitted by Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>

doc/ssl/SSL_CTX_load_verify_locations.pod

+=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

doc/ssl/SSL_CTX_set_client_CA_list.pod

+=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

doc/ssl/SSL_get_client_CA_list.pod

+=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

doc/ssl/SSL_load_client_CA_file.pod

+=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

doc/ssl/ssl.pod

@@ -625,15 +625,21 @@ connection defined in the B<SSL> structure.
 
 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_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_new(3)|SSL_new(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)>,