Provides stream-oriented functionality using SSL. More...

#include <stream.hpp>

Inheritance diagram for boost::asio::ssl::stream< Stream >:

Collaboration diagram for boost::asio::ssl::stream< Stream >:

Classes
struct	impl_struct
	Structure for use with deprecated impl_type. More...

Public Types
typedef SSL *	native_handle_type
	The native handle type of the SSL stream. More...

typedef impl_struct *	impl_type
	(Deprecated: Use native_handle_type.) The underlying implementation type. More...

typedef remove_reference < Stream >::type	next_layer_type
	The type of the next layer. More...

typedef next_layer_type::lowest_layer_type	lowest_layer_type
	The type of the lowest layer. More...

enum	handshake_type { client, server }
	Different handshake types. More...

Public Member Functions
template<typename Arg >
	stream (Arg &arg, context &ctx)
	Construct a stream. More...

	~stream ()
	Destructor. More...

boost::asio::io_service &	get_io_service ()
	Get the io_service associated with the object. More...

native_handle_type	native_handle ()
	Get the underlying implementation in the native type. More...

impl_type	impl ()
	(Deprecated: Use native_handle().) Get the underlying implementation in the native type. More...

const next_layer_type &	next_layer () const
	Get a reference to the next layer. More...

next_layer_type &	next_layer ()
	Get a reference to the next layer. More...

lowest_layer_type &	lowest_layer ()
	Get a reference to the lowest layer. More...

const lowest_layer_type &	lowest_layer () const
	Get a reference to the lowest layer. More...

void	set_verify_mode (verify_mode v)
	Set the peer verification mode. More...

boost::system::error_code	set_verify_mode (verify_mode v, boost::system::error_code &ec)
	Set the peer verification mode. More...

void	set_verify_depth (int depth)
	Set the peer verification depth. More...

boost::system::error_code	set_verify_depth (int depth, boost::system::error_code &ec)
	Set the peer verification depth. More...

template<typename VerifyCallback >
void	set_verify_callback (VerifyCallback callback)
	Set the callback used to verify peer certificates. More...

template<typename VerifyCallback >
boost::system::error_code	set_verify_callback (VerifyCallback callback, boost::system::error_code &ec)
	Set the callback used to verify peer certificates. More...

void	handshake (handshake_type type)
	Perform SSL handshaking. More...

boost::system::error_code	handshake (handshake_type type, boost::system::error_code &ec)
	Perform SSL handshaking. More...

template<typename ConstBufferSequence >
void	handshake (handshake_type type, const ConstBufferSequence &buffers)
	Perform SSL handshaking. More...

template<typename ConstBufferSequence >
boost::system::error_code	handshake (handshake_type type, const ConstBufferSequence &buffers, boost::system::error_code &ec)
	Perform SSL handshaking. More...

template<typename HandshakeHandler >
	BOOST_ASIO_INITFN_RESULT_TYPE (HandshakeHandler, void(boost::system::error_code)) async_handshake(handshake_type type
	Start an asynchronous SSL handshake. More...

	BOOST_ASIO_MOVE_ARG (HandshakeHandler) handler)

template<typename ConstBufferSequence , typename BufferedHandshakeHandler >
	BOOST_ASIO_INITFN_RESULT_TYPE (BufferedHandshakeHandler, void(boost::system::error_code, std::size_t)) async_handshake(handshake_type type
	Start an asynchronous SSL handshake. More...

const ConstBufferSequence	BOOST_ASIO_MOVE_ARG (BufferedHandshakeHandler) handler)

void	shutdown ()
	Shut down SSL on the stream. More...

boost::system::error_code	shutdown (boost::system::error_code &ec)
	Shut down SSL on the stream. More...

template<typename ShutdownHandler >
	BOOST_ASIO_INITFN_RESULT_TYPE (ShutdownHandler, void(boost::system::error_code)) async_shutdown(BOOST_ASIO_MOVE_ARG(ShutdownHandler) handler)
	Asynchronously shut down SSL on the stream. More...

template<typename ConstBufferSequence >
std::size_t	write_some (const ConstBufferSequence &buffers)
	Write some data to the stream. More...

template<typename ConstBufferSequence >
std::size_t	write_some (const ConstBufferSequence &buffers, boost::system::error_code &ec)
	Write some data to the stream. More...

template<typename ConstBufferSequence , typename WriteHandler >
	BOOST_ASIO_INITFN_RESULT_TYPE (WriteHandler, void(boost::system::error_code, std::size_t)) async_write_some(const ConstBufferSequence &buffers
	Start an asynchronous write. More...

	BOOST_ASIO_MOVE_ARG (WriteHandler) handler)

template<typename MutableBufferSequence >
std::size_t	read_some (const MutableBufferSequence &buffers)
	Read some data from the stream. More...

template<typename MutableBufferSequence >
std::size_t	read_some (const MutableBufferSequence &buffers, boost::system::error_code &ec)
	Read some data from the stream. More...

template<typename MutableBufferSequence , typename ReadHandler >
	BOOST_ASIO_INITFN_RESULT_TYPE (ReadHandler, void(boost::system::error_code, std::size_t)) async_read_some(const MutableBufferSequence &buffers
	Start an asynchronous read. More...

	BOOST_ASIO_MOVE_ARG (ReadHandler) handler)

Public Attributes
const ConstBufferSequence &	buffers

Detailed Description

template<typename Stream>
class boost::asio::ssl::stream< Stream >

Provides stream-oriented functionality using SSL.

The stream class template provides asynchronous and blocking stream-oriented functionality using SSL.

Thread Safety: Distinct objects: Safe.
Shared objects: Unsafe. The application must also ensure that all asynchronous operations are performed within the same implicit or explicit strand.

Example: To use the SSL stream template with an ip::tcp::socket, you would write:
boost::asio::io_service io_service;

boost::asio::ssl::context ctx(boost::asio::ssl::context::sslv23);

boost::asio::ssl::stream<asio:ip::tcp::socket> sock(io_service, ctx);

Concepts:: AsyncReadStream, AsyncWriteStream, Stream, SyncReadStream, SyncWriteStream.

Member Typedef Documentation

template<typename Stream>

typedef impl_struct* boost::asio::ssl::stream< Stream >::impl_type

(Deprecated: Use native_handle_type.) The underlying implementation type.

template<typename Stream>

typedef next_layer_type::lowest_layer_type boost::asio::ssl::stream< Stream >::lowest_layer_type

The type of the lowest layer.

template<typename Stream>

typedef SSL* boost::asio::ssl::stream< Stream >::native_handle_type

The native handle type of the SSL stream.

template<typename Stream>

typedef remove_reference<Stream>::type boost::asio::ssl::stream< Stream >::next_layer_type

The type of the next layer.

Member Enumeration Documentation

enum boost::asio::ssl::stream_base::handshake_type

inherited

Different handshake types.

Enumerator
client	Perform handshaking as a client.
server	Perform handshaking as a server.

Constructor & Destructor Documentation

template<typename Stream>

template<typename Arg >

boost::asio::ssl::stream< Stream >::stream	(	Arg &	arg,
		context &	ctx
	)

inline

Construct a stream.

This constructor creates a stream and initialises the underlying stream object.

Parameters

arg	The argument to be passed to initialise the underlying stream.
ctx	The SSL context to be used for the stream.

References boost::asio::ssl::stream< Stream >::impl_struct::ssl.

template<typename Stream>

boost::asio::ssl::stream< Stream >::~stream ( )

inline

Destructor.

Member Function Documentation

template<typename Stream>

template<typename HandshakeHandler >

boost::asio::ssl::stream< Stream >::BOOST_ASIO_INITFN_RESULT_TYPE	(	HandshakeHandler	,
		void(boost::system::error_code)
	)

Start an asynchronous SSL handshake.

This function is used to asynchronously perform an SSL handshake on the stream. This function call always returns immediately.

Parameters

type	The type of handshaking to be performed, i.e. as a client or as a server.
handler	The handler to be called when the handshake operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: void handler( const boost::system::error_code& error // Result of operation. );

template<typename Stream>

template<typename ConstBufferSequence , typename BufferedHandshakeHandler >

boost::asio::ssl::stream< Stream >::BOOST_ASIO_INITFN_RESULT_TYPE	(	BufferedHandshakeHandler	,
		void(boost::system::error_code, std::size_t)
	)

Start an asynchronous SSL handshake.

This function is used to asynchronously perform an SSL handshake on the stream. This function call always returns immediately.

Parameters

type	The type of handshaking to be performed, i.e. as a client or as a server.
buffers	The buffered data to be reused for the handshake. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called.
handler	The handler to be called when the handshake operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Amount of buffers used in handshake. );

template<typename Stream>

template<typename ShutdownHandler >

boost::asio::ssl::stream< Stream >::BOOST_ASIO_INITFN_RESULT_TYPE	(	ShutdownHandler	,
		void(boost::system::error_code)
	)

inline

Asynchronously shut down SSL on the stream.

This function is used to asynchronously shut down SSL on the stream. This function call always returns immediately.

Parameters

handler

The handler to be called when the handshake operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:

 void handler(
  const boost::system::error_code& error // Result of operation.
); 

References boost::asio::detail::async_result_init< Handler, Signature >::handler, boost::unit_test::framework::init(), boost::asio::detail::async_result_init< Handler, Signature >::result, and boost::detail::void.

template<typename Stream>

template<typename ConstBufferSequence , typename WriteHandler >

boost::asio::ssl::stream< Stream >::BOOST_ASIO_INITFN_RESULT_TYPE	(	WriteHandler	,
		void(boost::system::error_code, std::size_t)
	)		const

Start an asynchronous write.

This function is used to asynchronously write one or more bytes of data to the stream. The function call always returns immediately.

Parameters

buffers	The data to be written to the stream. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called.
handler	The handler to be called when the write operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes written. );

Note: The async_write_some operation may not transmit all of the data to the peer. Consider using the boost::asio::async_write function if you need to ensure that all data is written before the blocking operation completes.

template<typename Stream>

template<typename MutableBufferSequence , typename ReadHandler >

boost::asio::ssl::stream< Stream >::BOOST_ASIO_INITFN_RESULT_TYPE	(	ReadHandler	,
		void(boost::system::error_code, std::size_t)
	)		const

Start an asynchronous read.

This function is used to asynchronously read one or more bytes of data from the stream. The function call always returns immediately.

Parameters

buffers	The buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called.
handler	The handler to be called when the read operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes read. );

Note: The async_read_some operation may not read all of the requested number of bytes. Consider using the boost::asio::async_read function if you need to ensure that the requested amount of data is read before the asynchronous operation completes.

template<typename Stream>

boost::asio::ssl::stream< Stream >::BOOST_ASIO_MOVE_ARG ( HandshakeHandler )

inline

References boost::asio::detail::async_result_init< Handler, Signature >::handler, boost::unit_test::framework::init(), boost::asio::detail::async_result_init< Handler, Signature >::result, and boost::detail::void.

template<typename Stream>

const ConstBufferSequence boost::asio::ssl::stream< Stream >::BOOST_ASIO_MOVE_ARG ( BufferedHandshakeHandler )

inline

References boost::asio::detail::async_result_init< Handler, Signature >::handler, boost::unit_test::framework::init(), boost::asio::detail::async_result_init< Handler, Signature >::result, and boost::detail::void.

template<typename Stream>

boost::asio::ssl::stream< Stream >::BOOST_ASIO_MOVE_ARG ( WriteHandler )

inline

References boost::asio::detail::async_result_init< Handler, Signature >::handler, boost::unit_test::framework::init(), boost::asio::detail::async_result_init< Handler, Signature >::result, and boost::detail::void.

template<typename Stream>

boost::asio::ssl::stream< Stream >::BOOST_ASIO_MOVE_ARG ( ReadHandler )

inline

References boost::asio::detail::async_result_init< Handler, Signature >::handler, boost::unit_test::framework::init(), boost::asio::detail::async_result_init< Handler, Signature >::result, and boost::detail::void.

template<typename Stream>

boost::asio::io_service& boost::asio::ssl::stream< Stream >::get_io_service ( )

inline

Get the io_service associated with the object.

This function may be used to obtain the io_service object that the stream uses to dispatch handlers for asynchronous operations.

Returns: A reference to the io_service object that stream will use to dispatch handlers. Ownership is not transferred to the caller.

template<typename Stream>

void boost::asio::ssl::stream< Stream >::handshake ( handshake_type type )

inline

Perform SSL handshaking.

This function is used to perform SSL handshaking on the stream. The function call will block until handshaking is complete or an error occurs.

Parameters

type	The type of handshaking to be performed, i.e. as a client or as a server.

Exceptions

boost::system::system_error Thrown on failure.

Referenced by boost::asio::ssl::stream< Stream >::handshake().

template<typename Stream>

boost::system::error_code boost::asio::ssl::stream< Stream >::handshake	(	handshake_type	type,
		boost::system::error_code &	ec
	)

inline

Perform SSL handshaking.

This function is used to perform SSL handshaking on the stream. The function call will block until handshaking is complete or an error occurs.

Parameters

type	The type of handshaking to be performed, i.e. as a client or as a server.
ec	Set to indicate what error occurred, if any.

template<typename Stream>

template<typename ConstBufferSequence >

void boost::asio::ssl::stream< Stream >::handshake	(	handshake_type	type,
		const ConstBufferSequence &	buffers
	)

inline

Perform SSL handshaking.

This function is used to perform SSL handshaking on the stream. The function call will block until handshaking is complete or an error occurs.

Parameters

type	The type of handshaking to be performed, i.e. as a client or as a server.
buffers	The buffered data to be reused for the handshake.

Exceptions

boost::system::system_error Thrown on failure.

References boost::asio::ssl::stream< Stream >::handshake().

template<typename Stream>

template<typename ConstBufferSequence >

boost::system::error_code boost::asio::ssl::stream< Stream >::handshake	(	handshake_type	type,
		const ConstBufferSequence &	buffers,
		boost::system::error_code &	ec
	)

inline

Perform SSL handshaking.

This function is used to perform SSL handshaking on the stream. The function call will block until handshaking is complete or an error occurs.

Parameters

type	The type of handshaking to be performed, i.e. as a client or as a server.
buffers	The buffered data to be reused for the handshake.
ec	Set to indicate what error occurred, if any.

template<typename Stream>

impl_type boost::asio::ssl::stream< Stream >::impl ( )

inline

(Deprecated: Use native_handle().) Get the underlying implementation in the native type.

This function may be used to obtain the underlying implementation of the context. This is intended to allow access to stream functionality that is not otherwise provided.

template<typename Stream>

lowest_layer_type& boost::asio::ssl::stream< Stream >::lowest_layer ( )

inline

Get a reference to the lowest layer.

This function returns a reference to the lowest layer in a stack of stream layers.

Returns: A reference to the lowest layer in the stack of stream layers. Ownership is not transferred to the caller.

template<typename Stream>

const lowest_layer_type& boost::asio::ssl::stream< Stream >::lowest_layer ( ) const

inline

Get a reference to the lowest layer.

This function returns a reference to the lowest layer in a stack of stream layers.

Returns: A reference to the lowest layer in the stack of stream layers. Ownership is not transferred to the caller.

template<typename Stream>

native_handle_type boost::asio::ssl::stream< Stream >::native_handle ( )

inline

Get the underlying implementation in the native type.

This function may be used to obtain the underlying implementation of the context. This is intended to allow access to context functionality that is not otherwise provided.

Example: The native_handle() function returns a pointer of type SSL* that is suitable for passing to functions such as SSL_get_verify_result and SSL_get_peer_certificate:
boost::asio::ssl::stream<asio:ip::tcp::socket> sock(io_service, ctx);

// ... establish connection and perform handshake ...

if (X509* cert = SSL_get_peer_certificate(sock.native_handle()))

{

if (SSL_get_verify_result(sock.native_handle()) == X509_V_OK)

{

// ...

}

}

template<typename Stream>

const next_layer_type& boost::asio::ssl::stream< Stream >::next_layer ( ) const

inline

Get a reference to the next layer.

This function returns a reference to the next layer in a stack of stream layers.

Returns: A reference to the next layer in the stack of stream layers. Ownership is not transferred to the caller.

template<typename Stream>

next_layer_type& boost::asio::ssl::stream< Stream >::next_layer ( )

inline

Get a reference to the next layer.

This function returns a reference to the next layer in a stack of stream layers.

Returns: A reference to the next layer in the stack of stream layers. Ownership is not transferred to the caller.

template<typename Stream>

template<typename MutableBufferSequence >

std::size_t boost::asio::ssl::stream< Stream >::read_some ( const MutableBufferSequence & buffers )

inline

Read some data from the stream.

This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.

Parameters

buffers The buffers into which the data will be read.

Returns: The number of bytes read.

Exceptions

boost::system::system_error Thrown on failure.

Note: The read_some operation may not read all of the requested number of bytes. Consider using the boost::asio::read function if you need to ensure that the requested amount of data is read before the blocking operation completes.

References boost::n.

template<typename Stream>

template<typename MutableBufferSequence >

std::size_t boost::asio::ssl::stream< Stream >::read_some	(	const MutableBufferSequence &	buffers,
		boost::system::error_code &	ec
	)

inline

Read some data from the stream.

This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.

Parameters

buffers	The buffers into which the data will be read.
ec	Set to indicate what error occurred, if any.

Returns: The number of bytes read. Returns 0 if an error occurred.

Note: The read_some operation may not read all of the requested number of bytes. Consider using the boost::asio::read function if you need to ensure that the requested amount of data is read before the blocking operation completes.

template<typename Stream>

template<typename VerifyCallback >

void boost::asio::ssl::stream< Stream >::set_verify_callback ( VerifyCallback callback )

inline

Set the callback used to verify peer certificates.

This function is used to specify a callback function that will be called by the implementation when it needs to verify a peer certificate.

Parameters

callback

The function object to be used for verifying a certificate. The function signature of the handler must be:

 bool verify_callback(
  bool preverified, // True if the certificate passed pre-verification.
  verify_context& ctx // The peer certificate and other context.
); 

The return value of the callback is true if the certificate has passed verification, false otherwise.

Exceptions

boost::system::system_error Thrown on failure.

Note: Calls SSL_set_verify.

template<typename Stream>

template<typename VerifyCallback >

boost::system::error_code boost::asio::ssl::stream< Stream >::set_verify_callback	(	VerifyCallback	callback,
		boost::system::error_code &	ec
	)

inline

Set the callback used to verify peer certificates.

This function is used to specify a callback function that will be called by the implementation when it needs to verify a peer certificate.

Parameters

callback	The function object to be used for verifying a certificate. The function signature of the handler must be: bool verify_callback( bool preverified, // True if the certificate passed pre-verification. verify_context& ctx // The peer certificate and other context. ); The return value of the callback is true if the certificate has passed verification, false otherwise.
ec	Set to indicate what error occurred, if any.

Note: Calls SSL_set_verify.

template<typename Stream>

void boost::asio::ssl::stream< Stream >::set_verify_depth ( int depth )

inline

Set the peer verification depth.

This function may be used to configure the maximum verification depth allowed by the stream.

Parameters

depth Maximum depth for the certificate chain verification that shall be allowed.

Exceptions

boost::system::system_error Thrown on failure.

Note: Calls SSL_set_verify_depth.

template<typename Stream>

boost::system::error_code boost::asio::ssl::stream< Stream >::set_verify_depth	(	int	depth,
		boost::system::error_code &	ec
	)

inline

Set the peer verification depth.

This function may be used to configure the maximum verification depth allowed by the stream.

Parameters

depth	Maximum depth for the certificate chain verification that shall be allowed.
ec	Set to indicate what error occurred, if any.

Note: Calls SSL_set_verify_depth.

template<typename Stream>

void boost::asio::ssl::stream< Stream >::set_verify_mode ( verify_mode v )

inline

Set the peer verification mode.

This function may be used to configure the peer verification mode used by the stream. The new mode will override the mode inherited from the context.

Parameters

v	A bitmask of peer verification modes. See verify_mode for available values.

Exceptions

boost::system::system_error Thrown on failure.

Note: Calls SSL_set_verify.

template<typename Stream>

boost::system::error_code boost::asio::ssl::stream< Stream >::set_verify_mode	(	verify_mode	v,
		boost::system::error_code &	ec
	)

inline

Set the peer verification mode.

This function may be used to configure the peer verification mode used by the stream. The new mode will override the mode inherited from the context.

Parameters

v	A bitmask of peer verification modes. See verify_mode for available values.
ec	Set to indicate what error occurred, if any.

Note: Calls SSL_set_verify.

template<typename Stream>

void boost::asio::ssl::stream< Stream >::shutdown ( )

inline

Shut down SSL on the stream.

This function is used to shut down SSL on the stream. The function call will block until SSL has been shut down or an error occurs.

Exceptions

boost::system::system_error Thrown on failure.

template<typename Stream>

boost::system::error_code boost::asio::ssl::stream< Stream >::shutdown ( boost::system::error_code & ec )

inline

Shut down SSL on the stream.

This function is used to shut down SSL on the stream. The function call will block until SSL has been shut down or an error occurs.

Parameters

ec	Set to indicate what error occurred, if any.

template<typename Stream>

template<typename ConstBufferSequence >

std::size_t boost::asio::ssl::stream< Stream >::write_some ( const ConstBufferSequence & buffers )

inline

Write some data to the stream.

This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs.

Parameters

buffers The data to be written.

Returns: The number of bytes written.

Exceptions

boost::system::system_error Thrown on failure.

Note: The write_some operation may not transmit all of the data to the peer. Consider using the boost::asio::write function if you need to ensure that all data is written before the blocking operation completes.

References boost::n.

template<typename Stream>

template<typename ConstBufferSequence >

std::size_t boost::asio::ssl::stream< Stream >::write_some	(	const ConstBufferSequence &	buffers,
		boost::system::error_code &	ec
	)

inline

Write some data to the stream.

This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs.

Parameters

buffers	The data to be written to the stream.
ec	Set to indicate what error occurred, if any.

Returns: The number of bytes written. Returns 0 if an error occurred.

Note: The write_some operation may not transmit all of the data to the peer. Consider using the boost::asio::write function if you need to ensure that all data is written before the blocking operation completes.

Member Data Documentation

template<typename Stream>

const ConstBufferSequence& boost::asio::ssl::stream< Stream >::buffers

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

boost_1_57_0/boost/asio/ssl/stream.hpp

Classes

Public Types

Public Member Functions

Public Attributes

Detailed Description

template<typename Stream> class boost::asio::ssl::stream< Stream >

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<typename Stream>
class boost::asio::ssl::stream< Stream >