websocketpp::transport::asio::tls_socket::connection Class Reference

TLS enabled Asio connection socket component. More...

#include <tls.hpp>

Inheritance diagram for websocketpp::transport::asio::tls_socket::connection:

Collaboration diagram for websocketpp::transport::asio::tls_socket::connection:

Public Types
typedef connection	type
	Type of this connection socket component.
typedef lib::shared_ptr< type >	ptr
	Type of a shared pointer to this connection socket component.
typedef lib::asio::ssl::stream< lib::asio::ip::tcp::socket >	socket_type
	Type of the ASIO socket being used.
typedef lib::shared_ptr< socket_type >	socket_ptr
	Type of a shared pointer to the ASIO socket being used.
typedef lib::asio::io_service *	io_service_ptr
	Type of a pointer to the ASIO io_service being used.
typedef lib::shared_ptr< lib::asio::io_service::strand >	strand_ptr
	Type of a pointer to the ASIO io_service strand being used.
typedef lib::shared_ptr< lib::asio::ssl::context >	context_ptr
	Type of a shared pointer to the ASIO TLS context being used.

Public Member Functions
	connection ()
ptr	get_shared ()
	Get a shared pointer to this component.
bool	is_secure () const
	Check whether or not this connection is secure.
socket_type::lowest_layer_type &	get_raw_socket ()
	Retrieve a pointer to the underlying socket.
socket_type::next_layer_type &	get_next_layer ()
	Retrieve a pointer to the layer below the ssl stream.
socket_type &	get_socket ()
	Retrieve a pointer to the wrapped socket.
void	set_socket_init_handler (socket_init_handler h)
	Set the socket initialization handler.
void	set_tls_init_handler (tls_init_handler h)
	Set TLS init handler.
std::string	get_remote_endpoint (lib::error_code &ec) const
	Get the remote endpoint address.

Protected Member Functions
lib::error_code	init_asio (io_service_ptr service, strand_ptr strand, bool is_server)
	Perform one time initializations.
void	set_uri (uri_ptr u)
	Set hostname hook.
void	pre_init (init_handler callback)
	Pre-initialize security policy.
void	post_init (init_handler callback)
	Post-initialize security policy.
void	set_handle (connection_hdl hdl)
	Sets the connection handle.
void	handle_init (init_handler callback, lib::asio::error_code const &ec)
lib::error_code	get_ec () const
lib::asio::error_code	cancel_socket ()
	Cancel all async operations on this socket.
void	async_shutdown (socket::shutdown_handler callback)
template<typename ErrorCodeType >
lib::error_code	translate_ec (ErrorCodeType ec)
	Translate any security policy specific information about an error code.
lib::error_code	translate_ec (lib::error_code ec)

Detailed Description

transport::asio::tls_socket::connection implements a secure connection socket component that uses Asio's ssl::stream to wrap an ip::tcp::socket.

Definition at line 63 of file tls.hpp.

Member Typedef Documentation

context_ptr

lib::shared_ptr<lib::asio::ssl::context> websocketpp::transport::asio::tls_socket::connection::context_ptr

Definition at line 79 of file tls.hpp.

io_service_ptr

lib::asio::io_service* websocketpp::transport::asio::tls_socket::connection::io_service_ptr

Definition at line 75 of file tls.hpp.

ptr

lib::shared_ptr<type> websocketpp::transport::asio::tls_socket::connection::ptr

Definition at line 68 of file tls.hpp.

socket_ptr

lib::shared_ptr<socket_type> websocketpp::transport::asio::tls_socket::connection::socket_ptr

Definition at line 73 of file tls.hpp.

socket_type

lib::asio::ssl::stream<lib::asio::ip::tcp::socket> websocketpp::transport::asio::tls_socket::connection::socket_type

Definition at line 71 of file tls.hpp.

strand_ptr

lib::shared_ptr<lib::asio::io_service::strand> websocketpp::transport::asio::tls_socket::connection::strand_ptr

Definition at line 77 of file tls.hpp.

type

connection websocketpp::transport::asio::tls_socket::connection::type

Definition at line 66 of file tls.hpp.

Constructor & Destructor Documentation

connection()

websocketpp::transport::asio::tls_socket::connection::connection ( )

inlineexplicit

Definition at line 81 of file tls.hpp.

                          {
        //std::cout << "transport::asio::tls_socket::connection constructor"
        //          << std::endl;
    }

Member Function Documentation

async_shutdown()

void websocketpp::transport::asio::tls_socket::connection::async_shutdown ( socket::shutdown_handler callback )

inlineprotected

Definition at line 327 of file tls.hpp.

                                                         {
        if (m_strand) {
            m_socket->async_shutdown(m_strand->wrap(callback));
        } else {
            m_socket->async_shutdown(callback);
        }
    }

cancel_socket()

lib::asio::error_code websocketpp::transport::asio::tls_socket::connection::cancel_socket ( )

inlineprotected

Attempts to cancel all async operations on this socket and reports any failures.

NOTE: Windows XP and earlier do not support socket cancellation.

Returns

The error that occurred, if any.

Definition at line 321 of file tls.hpp.

                                      {
        lib::asio::error_code ec;
        get_raw_socket().cancel(ec);
        return ec;
    }

Here is the call graph for this function:

get_ec()

lib::error_code websocketpp::transport::asio::tls_socket::connection::get_ec ( ) const

inlineprotected

Definition at line 308 of file tls.hpp.

                                 {
        return m_ec;
    }

get_next_layer()

socket_type::next_layer_type & websocketpp::transport::asio::tls_socket::connection::get_next_layer ( )

inline

This is used internally.

Definition at line 111 of file tls.hpp.

                                                  {
        return m_socket->next_layer();
    }

get_raw_socket()

socket_type::lowest_layer_type & websocketpp::transport::asio::tls_socket::connection::get_raw_socket ( )

inline

This is used internally. It can also be used to set socket options, etc

Definition at line 103 of file tls.hpp.

                                                    {
        return m_socket->lowest_layer();
    }

Here is the caller graph for this function:

get_remote_endpoint()

std::string websocketpp::transport::asio::tls_socket::connection::get_remote_endpoint ( lib::error_code & ec ) const

inline

The iostream transport has no information about the ultimate remote endpoint. It will return the string "iostream transport". To indicate this.

TODO: allow user settable remote endpoint addresses if this seems useful

Returns

A string identifying the address of the remote endpoint

Definition at line 158 of file tls.hpp.

                                                            {
        std::stringstream s;
 
        lib::asio::error_code aec;
        lib::asio::ip::tcp::endpoint ep = m_socket->lowest_layer().remote_endpoint(aec);
 
        if (aec) {
            ec = error::make_error_code(error::pass_through);
            s << "Error getting remote endpoint: " << aec
               << " (" << aec.message() << ")";
            return s.str();
        } else {
            ec = lib::error_code();
            s << ep;
            return s.str();
        }
    }

Here is the call graph for this function:

get_shared()

ptr websocketpp::transport::asio::tls_socket::connection::get_shared ( )

inline

Definition at line 87 of file tls.hpp.

                     {
        return shared_from_this();
    }

Here is the caller graph for this function:

get_socket()

socket_type & websocketpp::transport::asio::tls_socket::connection::get_socket ( )

inline

This is used internally.

Definition at line 119 of file tls.hpp.

                               {
        return *m_socket;
    }

Here is the caller graph for this function:

handle_init()

void websocketpp::transport::asio::tls_socket::connection::handle_init ( init_handler callback, lib::asio::error_code const & ec )

inlineprotected

Definition at line 298 of file tls.hpp.

                                                                         {
        if (ec) {
            m_ec = socket::make_error_code(socket::error::tls_handshake_failed);
        } else {
            m_ec = lib::error_code();
        }
 
        callback(m_ec);
    }

Here is the call graph for this function:

Here is the caller graph for this function:

init_asio()

lib::error_code websocketpp::transport::asio::tls_socket::connection::init_asio ( io_service_ptr service, strand_ptr strand, bool is_server )

inlineprotected

init_asio is called once immediately after construction to initialize Asio components to the io_service

Parameters

service	A pointer to the endpoint's io_service
strand	A pointer to the connection's strand
is_server	Whether or not the endpoint is a server or not.

Definition at line 185 of file tls.hpp.

    {
        if (!m_tls_init_handler) {
            return socket::make_error_code(socket::error::missing_tls_init_handler);
        }
        m_context = m_tls_init_handler(m_hdl);
 
        if (!m_context) {
            return socket::make_error_code(socket::error::invalid_tls_context);
        }
        m_socket = lib::make_shared<socket_type>(*service, *m_context);
 
        m_io_service = service;
        m_strand = strand;
        m_is_server = is_server;
 
        return lib::error_code();
    }

Here is the call graph for this function:

is_secure()

bool websocketpp::transport::asio::tls_socket::connection::is_secure ( ) const

inline

Returns

Whether or not this connection is secure

Definition at line 95 of file tls.hpp.

                           {
        return true;
    }

post_init()

void websocketpp::transport::asio::tls_socket::connection::post_init ( init_handler callback )

inlineprotected

Called by the transport after all intermediate proxies have been negotiated. This gives the security policy the chance to talk with the real remote endpoint for a bit before the websocket handshake.

Parameters

callback

Handler to call back with completion information

Definition at line 262 of file tls.hpp.

                                          {
        m_ec = socket::make_error_code(socket::error::tls_handshake_timeout);
 
        // TLS handshake
        if (m_strand) {
            m_socket->async_handshake(
                get_handshake_type(),
                m_strand->wrap(lib::bind(
                    &type::handle_init, get_shared(),
                    callback,
                    lib::placeholders::_1
                ))
            );
        } else {
            m_socket->async_handshake(
                get_handshake_type(),
                lib::bind(
                    &type::handle_init, get_shared(),
                    callback,
                    lib::placeholders::_1
                )
            );
        }
    }

Here is the call graph for this function:

pre_init()

void websocketpp::transport::asio::tls_socket::connection::pre_init ( init_handler callback )

inlineprotected

Called by the transport after a new connection is created to initialize the socket component of the connection. This method is not allowed to write any bytes to the wire. This initialization happens before any proxies or other intermediate wrappers are negotiated.

Parameters

callback

Handler to call back with completion information

Definition at line 230 of file tls.hpp.

                                         {
        // TODO: is this the best way to check whether this function is 
        //       available in the version of OpenSSL being used?
        // TODO: consider case where host is an IP address
#if OPENSSL_VERSION_NUMBER >= 0x90812f
        if (!m_is_server) {
            // For clients on systems with a suitable OpenSSL version, set the
            // TLS SNI hostname header so connecting to TLS servers using SNI
            // will work.
            long res = SSL_set_tlsext_host_name(
                get_socket().native_handle(), m_uri->get_host().c_str());
            if (!(1 == res)) {
                callback(socket::make_error_code(socket::error::tls_failed_sni_hostname));
            }
        }
#endif
 
        if (m_socket_init_handler) {
            m_socket_init_handler(m_hdl,get_socket());
        }
 
        callback(lib::error_code());
    }

Here is the call graph for this function:

set_handle()

void websocketpp::transport::asio::tls_socket::connection::set_handle ( connection_hdl hdl )

inlineprotected

The connection handle is passed to any handlers to identify the connection

Parameters

hdl	The new handle

Definition at line 294 of file tls.hpp.

                                        {
        m_hdl = hdl;
    }

set_socket_init_handler()

void websocketpp::transport::asio::tls_socket::connection::set_socket_init_handler ( socket_init_handler h )

inline

The socket initialization handler is called after the socket object is created but before it is used. This gives the application a chance to set any ASIO socket options it needs.

Parameters

h	The new socket_init_handler

Definition at line 131 of file tls.hpp.

                                                        {
        m_socket_init_handler = h;
    }

set_tls_init_handler()

void websocketpp::transport::asio::tls_socket::connection::set_tls_init_handler ( tls_init_handler h )

inline

The tls init handler is called when needed to request a TLS context for the library to use. A TLS init handler must be set and it must return a valid TLS context in order for this endpoint to be able to initialize TLS connections

Parameters

h	The new tls_init_handler

Definition at line 144 of file tls.hpp.

                                                  {
        m_tls_init_handler = h;
    }

set_uri()

void websocketpp::transport::asio::tls_socket::connection::set_uri ( uri_ptr u )

inlineprotected

Called by the transport as a connection is being established to provide the hostname being connected to to the security/socket layer.

This socket policy uses the hostname to set the appropriate TLS SNI header.

Since

0.6.0

Parameters

u	The uri to set

Definition at line 217 of file tls.hpp.

                            {
        m_uri = u;
    }

translate_ec() [1/2]

template<typename ErrorCodeType >

lib::error_code websocketpp::transport::asio::tls_socket::connection::translate_ec ( ErrorCodeType ec )

inlineprotected

Translate_ec takes an Asio error code and attempts to convert its value to an appropriate websocketpp error code. In the case that the Asio and Websocketpp error types are the same (such as using boost::asio and boost::system_error or using standalone asio and std::system_error the code will be passed through natively.

In the case of a mismatch (boost::asio with std::system_error) a translated code will be returned. Any error that is determined to be related to TLS but does not have a more specific websocketpp error code is returned under the catch all error tls_error. Non-TLS related errors are returned as the transport generic error pass_through

Since

0.3.0

Parameters

ec	The error code to translate_ec

Returns

The translated error code

Definition at line 355 of file tls.hpp.

                                                 {
        if (ec.category() == lib::asio::error::get_ssl_category()) {
             // We know it is a TLS related error, but otherwise don't know
             // more. Pass through as TLS generic.
             return make_error_code(transport::error::tls_error);
        } else {
            // We don't know any more information about this error so pass
            // through
            return make_error_code(transport::error::pass_through);
        }
    }

translate_ec() [2/2]

lib::error_code websocketpp::transport::asio::tls_socket::connection::translate_ec ( lib::error_code ec )

inlineprotected

Overload of translate_ec to catch cases where lib::error_code is the same type as lib::asio::error_code

Definition at line 369 of file tls.hpp.

                                                 {
        // Normalize the tls_short_read error as it is used by the library and 
        // needs a consistent value. All other errors pass through natively.
        // TODO: how to get the SSL category from std::error?
        /*if (ec.category() == lib::asio::error::get_ssl_category()) {
            if (ERR_GET_REASON(ec.value()) == SSL_R_SHORT_READ) {
                return make_error_code(transport::error::tls_short_read);
            }
        }*/
        return ec;
    }

---

The documentation for this class was generated from the following file:

• libraries/fc/vendor/websocketpp/websocketpp/transport/asio/security/tls.hpp