New documents. Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>

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

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

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

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

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

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