diff options
author | cvs2svn <cvs2svn> | 2000-10-03 22:02:29 +0000 |
---|---|---|
committer | cvs2svn <cvs2svn> | 2000-10-03 22:02:29 +0000 |
commit | 4ef897d1fccccb88de7c7cae84df0d2b27a6ed81 (patch) | |
tree | 8434e5b1a7e0819d336a866bc0d34147e3252663 | |
parent | 19a5e404cbb8a1a7a4d643aa0b53e53f1776dfb6 (diff) | |
parent | 356c06c7767e7bc4387c8fb3b955ae2c0a661f5b (diff) | |
download | openssl-new-4ef897d1fccccb88de7c7cae84df0d2b27a6ed81.tar.gz |
This commit was manufactured by cvs2svn to create branch 'BRANCH_engine'.
-rw-r--r-- | doc/ssl/SSL_CTX_load_verify_locations.pod | 93 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_client_CA_list.pod | 90 | ||||
-rw-r--r-- | doc/ssl/SSL_get_client_CA_list.pod | 52 | ||||
-rw-r--r-- | doc/ssl/SSL_load_client_CA_file.pod | 62 |
4 files changed, 297 insertions, 0 deletions
diff --git a/doc/ssl/SSL_CTX_load_verify_locations.pod b/doc/ssl/SSL_CTX_load_verify_locations.pod new file mode 100644 index 0000000000..66bb6f33b6 --- /dev/null +++ b/doc/ssl/SSL_CTX_load_verify_locations.pod @@ -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 diff --git a/doc/ssl/SSL_CTX_set_client_CA_list.pod b/doc/ssl/SSL_CTX_set_client_CA_list.pod new file mode 100644 index 0000000000..f27a291cb6 --- /dev/null +++ b/doc/ssl/SSL_CTX_set_client_CA_list.pod @@ -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 diff --git a/doc/ssl/SSL_get_client_CA_list.pod b/doc/ssl/SSL_get_client_CA_list.pod new file mode 100644 index 0000000000..d358bc352e --- /dev/null +++ b/doc/ssl/SSL_get_client_CA_list.pod @@ -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 diff --git a/doc/ssl/SSL_load_client_CA_file.pod b/doc/ssl/SSL_load_client_CA_file.pod new file mode 100644 index 0000000000..02527dc2ed --- /dev/null +++ b/doc/ssl/SSL_load_client_CA_file.pod @@ -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 |