IOStream Class Reference

#include <Pt/Ssl/IOStream.h>

SSL iostream. More...

Inherits BasicIOStream< char >, and NonCopyable.

Public Member Functions
	IOStream (std::size_t bufferSize=1024)
	Creates a closed SSL stream.
	IOStream (Context &ctx, std::iostream &ios, OpenMode mode, std::size_t bufferSize=1024)
	Creates an SSL stream and opens it.
virtual	~IOStream ()
	Destructor.
void	open (Context &ctx, std::iostream &ios, OpenMode mode)
	Opens the SSL stream on ios using ctx and mode.
const char *	currentCipher () const
	Returns the cipher in use, or a placeholder if not connected.
void	close ()
	Closes the stream without a TLS shutdown.
bool	isConnected () const
	Returns true if the handshake has completed.
bool	writeHandshake ()
	Writes a handshake message to the underlying stream.
bool	readHandshake ()
	Reads a handshake message from the underlying stream.
bool	shutdown ()
	Completes or starts the TLS shutdown.
bool	isShutdown () const
	Returns true if a shutdown alert was received.
bool	isClosed () const
	Returns true if the connection was closed prematurely.
std::streamsize	import (std::streamsize maxImport=0)
	Decrypts available data from the underlying stream.
StreamBuffer &	sslBuffer ()
	Returns the SSL stream buffer.
std::streamsize	peeksome (char *buffer, std::streamsize n)
	Peeks bytes in the stream buffer.
std::streamsize	writesome (char *buffer, std::streamsize n)
	Write as much data as fits in buffer.
BasicStreamBuffer< char > *	buffer ()
	Returns the buffer.
void	setBuffer (BasicStreamBuffer< char > *sb)
	Sets the buffer.

Detailed Description

IOStream is the iostream facade for a secure connection. It wraps an underlying iostream with a Context and an OpenMode, and it is the type most callers construct. The handshake, encrypted I/O, and shutdown are the stream operations the group described; this type forwards them to its StreamBuffer.

A default-constructed stream is closed. The constructor that takes a context, an iostream, and a mode opens immediately, as does open(). isConnected() is true after the handshake completes. readHandshake() and writeHandshake() are the non-blocking handshake steps. import() decrypts available input. sslBuffer() is the buffer when the caller needs StreamBuffer::setPeerName() or the streambuf itself. currentCipher() is the negotiated cipher. close() drops the connection without a TLS shutdown.

Writes use the inherited iostream API. flush() pushes encrypted bytes to the underlying stream. Premature EOF on the transport is handled by the code that owns that stream.

The example imports available ciphertext and reads the decrypted bytes, then writes a message and flushes it so the encrypted output reaches the underlying stream.

Pt::Ssl::IOStream& ssl = ...;
 
for(;;)
{
    ssl.import();
 
    std::streamsize avail = ssl.sslBuffer().in_avail();
    if(avail <= 0)
        break;
 
    do
    {
        char buf[255];
        std::streamsize n = ssl.readsome(buf, sizeof(buf));
        std::cout.write(buf, n);
    }
    while( ssl.sslBuffer().in_avail() > 0 );
}
 
if( ssl.isShutdown() )
    ssl.shutdown();
 
ssl << "pi is: " << 3.1415;
ssl.flush();

Member Function Documentation

writeHandshake()

bool writeHandshake

(

)

Returns true if handshake data was written, false otherwise.

Exceptions

%HandshakeFailed	if the handshake cannot complete.
%SslError	if the stream is not open.

readHandshake()

bool readHandshake

(

)

Returns true if more handshake data needs to be read, false otherwise.

Exceptions

%HandshakeFailed	if the handshake cannot complete.
%SslError	if the stream is not open.

shutdown()

bool shutdown

(

)

Returns true if the shutdown completed.

Exceptions

%SslError

if the shutdown fails.

import()

std::streamsize import

(

std::streamsize

maxImport = 0

)

Returns the number of bytes consumed from the underlying stream. Call isShutdown() to find out if a shutdown alert was received, and isClosed() if the connection was closed prematurely.

peeksome()

std::streamsize peeksome ( char * buffer, std::streamsize n )

inherited

The number of bytes that can be peeked depends on the current stream buffer get area and maybe less than requested, similar to istream::readsome().