diff options
author | Richard Levitte <levitte@openssl.org> | 2000-09-20 16:55:26 +0000 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2000-09-20 16:55:26 +0000 |
commit | 4759abc5f268710bb5b75b38152958d7a1a3f95f (patch) | |
tree | 81ac900b9895ed8297803357c40df651788b115d /doc | |
parent | e31e385ce3d788f0e9e2b6acd24c494a8338ab49 (diff) | |
download | openssl-4759abc5f268710bb5b75b38152958d7a1a3f95f.tar.gz |
New documents. Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ssl/SSL_CTX_free.pod | 29 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_new.pod | 93 | ||||
-rw-r--r-- | doc/ssl/SSL_get_peer_cert_chain.pod | 52 | ||||
-rw-r--r-- | doc/ssl/SSL_get_peer_certificate.pod | 48 | ||||
-rw-r--r-- | doc/ssl/SSL_get_verify_result.pod | 57 | ||||
-rw-r--r-- | doc/ssl/SSL_set_verify_result.pod | 38 |
6 files changed, 317 insertions, 0 deletions
diff --git a/doc/ssl/SSL_CTX_free.pod b/doc/ssl/SSL_CTX_free.pod new file mode 100644 index 0000000000..de69672422 --- /dev/null +++ b/doc/ssl/SSL_CTX_free.pod @@ -0,0 +1,29 @@ +=pod + +=head1 NAME + +SSL_CTX_free - free an allocated SSL_CTX object + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_free(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_free() decrements the reference count of B<ctx>, and removes the +SSL_CTX object pointed to by B<ctx> and frees up the allocated memory if the +the reference count has reached 0. + +It also calls the free()ing procedures for indirectly affected items, if +applicable: the session cacahe, the list of ciphers, the list of Client CAs, +the certificates and keys. + +=head1 RETURN VALUES + +SSL_CTX_free() does not provide diagnostic information. + +L<SSL_CTX_new(3)|SSL_CTX_new(3)>, L<ssl(3)|ssl(3)> + +=cut diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod new file mode 100644 index 0000000000..e166c692c3 --- /dev/null +++ b/doc/ssl/SSL_CTX_new.pod @@ -0,0 +1,93 @@ +=pod + +=head1 NAME + +SSL_CTX_new - create a new SSL_CTX object as framework for TLS/SSL enabled functions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_CTX *SSL_CTX_new(SSL_METHOD *method); + +=head1 DESCRIPTION + +SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish +TLS/SSL enabled connections. + +=head1 NOTES + +The SSL_CTX object uses B<method> as connection method. The methods exist +in a generic type (for client and server use), a server only type, and a +client only type. B<method> can be of the following types: + +=over 4 + +=item SSLv2_method(void), SSLv2_server_method(void), SSLv2_client_method(void) + +A TLS/SSL connection established with these methods will only understand +the SSLv2 protocol. A client will send out SSLv2 client hello messages +and will also indicate that it only understand SSLv2. A server will only +understand SSLv2 client hello messages. + +=item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void) + +A TLS/SSL connection established with these methods will only understand the +SSLv3 and TLSv1 protocol. A client will send out SSLv3 client hello messages +and will indicate that it also understands TLSv1. A server will only understand +SSLv3 and TLSv1 client hello messages. This especially means, that it will +not understand SSLv2 client hello messages which are widely used for +compatibility reasons, see SSLv23_*_method(). + +=item TLSv1_method(void), TLSv1_server_method(void), TLSv1_client_method(void) + +A TLS/SSL connection established with these methods will only understand the +TLSv1 protocol. A client will send out TLSv1 client hello messages +and will indicate that it only understands TLSv1. A server will only understand +TLSv1 client hello messages. This especially means, that it will +not understand SSLv2 client hello messages which are widely used for +compatibility reasons, see SSLv23_*_method(). + +=item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void) + +A TLS/SSL connection established with these methods will understand the SSLv2, +SSLv3, and TLSv1 protocol. A client will send out SSLv2 client hello messages +and will indicate that it also understands SSLv3 and TLSv1. A server will +understand SSLv2, SSLv3, and TLSv1 client hello messages. This is the best +choice when compatibility is a concern. + +=back + +The list of protocols available can later be limited using the SSL_OP_NO_SSLv2, +SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1 options of the B<SSL_CTX_set_options()> or +B<SSL_set_options()> functions. Using these options it is possible to choose +e.g. SSLv23_server_method() and be able to negotiate with all possible +clients, but to only allow newer protocols like SSLv3 or TLSv1. + +SSL_CTX_new() initializes the list of ciphers, the session cache setting, +the callbacks, the keys and certificates, and the options to its default +values. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +The creation of a new SSL_CTX object failed. Check the error stack to +find out the reason. + +=item Pointer to an SSL_CTX object + +The return value points to an allocated SSL_CTX object. + +=back + +=head1 SEE ALSO + +L<SSL_CTX_free(3)|SSL_CTX_free(3)>, L<SSL_accept(3)|SSL_accept(3)>, +L<ssl(3)|ssl(3)> + +=cut diff --git a/doc/ssl/SSL_get_peer_cert_chain.pod b/doc/ssl/SSL_get_peer_cert_chain.pod new file mode 100644 index 0000000000..e93e8206fa --- /dev/null +++ b/doc/ssl/SSL_get_peer_cert_chain.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +SSL_get_peer_cert_chain - get the X509 certificate chain of the peer + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + STACKOF(X509) *SSL_get_peer_cert_chain(SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_peer_cert_chain() returns a pointer to STACKOF(X509) certificates +forming the certificate chain of the peer. If called on the client side, +the stack also contains the peer's certificate; if called on the server +side, the peer's certificate must be obtained seperately using +L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>. +If the peer did not present a certificate, NULL is returned. + +=head1 NOTES + +The peer certificate chain is not necessarily available after reusing +a session, in which case a NULL pointer is returned. + +The reference count of the STACKOF(X509) object is not incremented. +If the corresponding session is freed, the pointer must not be used +any longer. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +No certificate was presented by the peer or no connection was established +or the certificate chain is no longer available when a session is reused. + +=item Pointer to a STACKOF(X509) + +The return value points to the certificate chain presented by the peer. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)> + +=cut diff --git a/doc/ssl/SSL_get_peer_certificate.pod b/doc/ssl/SSL_get_peer_certificate.pod new file mode 100644 index 0000000000..79c089aa51 --- /dev/null +++ b/doc/ssl/SSL_get_peer_certificate.pod @@ -0,0 +1,48 @@ +=pod + +=head1 NAME + +SSL_get_peer_certificate - get the X509 certificate of the peer + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + X509 *SSL_get_peer_certificate(SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_peer_certificate() returns a pointer to the X509 certificate the +peer presented. If the peer did not present a certificate, NULL is returned. + +=head1 NOTES + +That a certificate is returned does not indicate information about the +verification state, use L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> +to check the verification state. + +The reference count of the X509 object is incremented by one, so that it +will not be destroyed when the session containing the peer certificate is +freed. The X509 object must be explicitely freed using X509_free(). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +No certificate was presented by the peer or no connection was established. + +=item Pointer to an X509 certificate + +The return value points to the certificate presented by the peer. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> + +=cut diff --git a/doc/ssl/SSL_get_verify_result.pod b/doc/ssl/SSL_get_verify_result.pod new file mode 100644 index 0000000000..4d66236a05 --- /dev/null +++ b/doc/ssl/SSL_get_verify_result.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +SSL_get_verify_result - get result of peer certificate verification + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_get_verify_result(SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_verify_result() returns the result of the verification of the +X509 certificate presented by the peer, if any. + +=head1 NOTES + +SSL_get_verify_result() can only return one error code while the verification +of a certificate can fail because of many reasons at the same time. Only +the last verification error that occured during the processing is available +from SSL_get_verify_result(). + +The verification result is part of the established session and is restored +when a session is reused. + +=head1 BUGS + +If no peer certificate was presented, the returned result code is +X509_V_OK. This is because no verification error occured, it does however +not indicate success. SSL_get_verify_result() is only useful in connection +with L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>. + +=head1 RETURN VALUES + +The following return values can currently occur: + +=over 4 + +=item X509_V_OK + +The verification succeeded or no peer certificate was presented. + +=item Any other value + +Documented in L<verify(1)|verify(1)>. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_set_verify_result(3)|SSL_set_verify_result(3)>, +L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, +L<verify(1)|verify(1)> + +=cut diff --git a/doc/ssl/SSL_set_verify_result.pod b/doc/ssl/SSL_set_verify_result.pod new file mode 100644 index 0000000000..04ab101aad --- /dev/null +++ b/doc/ssl/SSL_set_verify_result.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +SSL_set_verify_result - override result of peer certificate verification + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_set_verify_result(SSL *ssl, long verify_result); + +=head1 DESCRIPTION + +SSL_set_verify_result() sets B<verify_result> of the object B<ssl> to be the +result of the verification of the X509 certificate presented by the peer, +if any. + +=head1 NOTES + +SSL_set_verify_result() overrides the verification result. It only changes +the verification result of the B<ssl> object. It does not become part of the +established session, so if the session is to be reused later, the original +value will reappear. + +The valid codes for B<verify_result> are documented in L<verify(1)|verify(1)>. + +=head1 RETURN VALUES + +SSL_set_verify_result() does not provide a return value. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, +L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, +L<verify(1)|verify(1)> + +=cut |