Class Poco::Net::SecureSocketImpl
Author: Applied Informatics Software Engineering GmbH and Contributors
Date: 2009-11-24

# Poco::Net

# class SecureSocketImpl

Library: NetSSL_OpenSSL
Package: SSLSockets
Header: Poco/Net/SecureSocketImpl.h

## Description

The SocketImpl for SecureStreamSocket.

## Member Summary

Member Functions: acceptConnection, acceptSSL, bind, close, completeHandshake, connect, connectNB, connectSSL, context, getPeerHostName, handleError, isLocalHost, listen, peerCertificate, receiveBytes, reset, sendBytes, setPeerHostName, shutdown, sockfd, verifyCertificate, verifyPeerCertificate

## Constructors

### SecureSocketImpl

SecureSocketImpl(
Poco::AutoPtr < SocketImpl > pSocketImpl,
Context::Ptr pContext
);

Creates the SecureSocketImpl using an already connected stream socket.

## Destructor

### ~SecureSocketImpl

virtual ~SecureSocketImpl();

Destroys the SecureSocketImpl.

## Member Functions

### acceptConnection

SocketImpl * acceptConnection(
SocketAddress & clientAddr
);

Get the next completed connection from the socket's completed connection queue.

If the queue is empty, waits until a connection request completes.

Returns a new SSL socket for the connection with the client.

The client socket's address is returned in clientAddr.

### bind

void bind(
const SocketAddress & address,
bool reuseAddress = false
);

Bind a local address to the socket.

This is usually only done when establishing a server socket. SSL clients should not bind a socket to a specific address.

If reuseAddress is true, sets the SO_REUSEADDR socket option.

### close

void close();

Close the socket.

### completeHandshake

int completeHandshake();

Completes the SSL handshake.

If the SSL connection was the result of an accept(), the server-side handshake is completed, otherwise a client-side handshake is performed.

### connect

void connect(
const SocketAddress & address,
bool performHandshake
);

Initializes the socket and establishes a secure connection to the TCP server at the given address.

If performHandshake is true, the SSL handshake is performed immediately after establishing the connection. Otherwise, the handshake is performed the first time sendBytes(), receiveBytes() or completeHandshake() is called.

### connect

void connect(
const SocketAddress & address,
const Poco::Timespan & timeout,
bool performHandshake
);

Initializes the socket, sets the socket timeout and establishes a secure connection to the TCP server at the given address.

If performHandshake is true, the SSL handshake is performed immediately after establishing the connection. Otherwise, the handshake is performed the first time sendBytes(), receiveBytes() or completeHandshake() is called.

### connectNB

void connectNB(
const SocketAddress & address
);

Initializes the socket and establishes a secure connection to the TCP server at the given address. Prior to opening the connection the socket is set to nonblocking mode.

### context

Context::Ptr context() const;

Returns the SSL context used for this socket.

### getPeerHostName

const std::string & getPeerHostName() const;

Returns the peer host name.

### listen

void listen(
int backlog = 64
);

Puts the socket into listening state.

The socket becomes a passive socket that can accept incoming connection requests.

The backlog argument specifies the maximum number of connections that can be queued for this socket.

### peerCertificate

X509 * peerCertificate() const;

Returns the peer's certificate.

### receiveBytes

int receiveBytes(
void * buffer,
int length,
int flags = 0
);

Receives data from the socket and stores it in buffer. Up to length bytes are received.

Returns the number of bytes received.

### sendBytes

int sendBytes(
const void * buffer,
int length,
int flags = 0
);

Sends the contents of the given buffer through the socket. Any specified flags are ignored.

Returns the number of bytes sent, which may be less than the number of bytes specified.

### setPeerHostName

void setPeerHostName(
const std::string & hostName
);

Sets the peer host name for certificate validation purposes.

### shutdown

void shutdown();

Shuts down the connection by attempting an orderly SSL shutdown, then actually shutting down the TCP connection.

### sockfd

int sockfd();

Returns the underlying socket descriptor.

### verifyPeerCertificate

void verifyPeerCertificate();

Performs post-connect (or post-accept) peer certificate validation, using the peer host name set with setPeerHostName(), or the peer's IP address string if no peer host name has been set.

### verifyPeerCertificate

void verifyPeerCertificate(
const std::string & hostName
);

Performs post-connect (or post-accept) peer certificate validation using the given peer host name.

### acceptSSL

void acceptSSL();

Performs a server-side SSL handshake and certificate verification.

### connectSSL

void connectSSL(
bool performHandshake
);

Performs a client-side SSL handshake and establishes a secure connection over an already existing TCP connection.

### handleError

int handleError(
int rc
);

Handles an SSL error by throwing an appropriate exception.

### isLocalHost

static bool isLocalHost(
const std::string & hostName
);

Returns true if and only if the given host name is the local host (either "localhost" or "127.0.0.1").

### reset

void reset();

Prepares the socket for re-use.

After closing and resetting a socket, the socket can be used for a new connection.

Note that simply closing a socket is not sufficient to be able to re-use it again.

### verifyCertificate

long verifyCertificate(
const std::string & hostName
);

Performs post-connect (or post-accept) peer certificate validation.