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

=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

=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

=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

=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

=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