From 4759abc5f268710bb5b75b38152958d7a1a3f95f Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Wed, 20 Sep 2000 16:55:26 +0000 Subject: [PATCH] New documents. Lutz Jaenicke --- doc/ssl/SSL_CTX_free.pod | 29 +++++++++ doc/ssl/SSL_CTX_new.pod | 93 ++++++++++++++++++++++++++++ doc/ssl/SSL_get_peer_cert_chain.pod | 52 ++++++++++++++++ doc/ssl/SSL_get_peer_certificate.pod | 48 ++++++++++++++ doc/ssl/SSL_get_verify_result.pod | 57 +++++++++++++++++ doc/ssl/SSL_set_verify_result.pod | 38 ++++++++++++ 6 files changed, 317 insertions(+) create mode 100644 doc/ssl/SSL_CTX_free.pod create mode 100644 doc/ssl/SSL_CTX_new.pod create mode 100644 doc/ssl/SSL_get_peer_cert_chain.pod create mode 100644 doc/ssl/SSL_get_peer_certificate.pod create mode 100644 doc/ssl/SSL_get_verify_result.pod create mode 100644 doc/ssl/SSL_set_verify_result.pod 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 + + void SSL_CTX_free(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_free() decrements the reference count of B, and removes the +SSL_CTX object pointed to by B 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, L + +=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 + + SSL_CTX *SSL_CTX_new(SSL_METHOD *method); + +=head1 DESCRIPTION + +SSL_CTX_new() creates a new B object as framework to establish +TLS/SSL enabled connections. + +=head1 NOTES + +The SSL_CTX object uses B 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 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 or +B 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, L, +L + +=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 + + 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. +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, L + +=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 + + 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 +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, L + +=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 + + 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. + +=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. + +=back + +=head1 SEE ALSO + +L, L, +L, +L + +=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 + + void SSL_set_verify_result(SSL *ssl, long verify_result); + +=head1 DESCRIPTION + +SSL_set_verify_result() sets B of the object B 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 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 are documented in L. + +=head1 RETURN VALUES + +SSL_set_verify_result() does not provide a return value. + +=head1 SEE ALSO + +L, L, +L, +L + +=cut -- 2.25.1