Library: NetSSL_OpenSSL
Package: SSLSockets
Header: Poco/Net/SecureSocketImpl.h
Description
The SocketImpl for SecureStreamSocket.
Member Summary
Member Functions: abort, acceptConnection, acceptSSL, available, bind, bind6, close, completeHandshake, connect, connectNB, connectSSL, context, currentSession, getBlocking, getPeerHostName, handleError, isLocalHost, listen, mustRetry, onSessionCreated, peerCertificate, receiveBytes, reset, sendBytes, sessionWasReused, setBlocking, setPeerHostName, shutdown, sockfd, useSession, verifyPeerCertificate, verifyPeerCertificateImpl
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
abort
void abort();
Aborts the connection by closing the underlying TCP connection. No orderly SSL shutdown is performed.
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.
available
int available() const;
Returns the number of bytes available from the SSL buffer for immediate reading.
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. TCP clients should not bind a socket to a specific address.
If reuseAddress is true, sets the SO_REUSEADDR socket option.
bind
void bind(
const SocketAddress & address,
bool reuseAddress,
bool reusePort
);
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.
If reusePort is true, sets the SO_REUSEPORT socket option.
bind6
void bind6(
const SocketAddress & address,
bool reuseAddress = false,
bool ipV6Only = false
);
Bind a local IPv6 address to the socket.
This is usually only done when establishing a server socket. TCP clients should not bind a socket to a specific address.
If reuseAddress is true, sets the SO_REUSEADDR socket option.
The given address must be an IPv6 address. The IPPROTO_IPV6/IPV6_V6ONLY option is set on the socket according to the ipV6Only parameter.
If the library has not been built with IPv6 support, a Poco::NotImplementedException will be thrown.
bind6
void bind6(
const SocketAddress & address,
bool reuseAddress,
bool reusePort,
bool ipV6Only
);
Bind a local IPv6 address to the socket.
This is usually only done when establishing a server socket. TCP clients should not bind a socket to a specific address.
If reuseAddress is true, sets the SO_REUSEADDR socket option.
If reusePort is true, sets the SO_REUSEPORT socket option.
The given address must be an IPv6 address. The IPPROTO_IPV6/IPV6_V6ONLY option is set on the socket according to the ipV6Only parameter.
If the library has not been built with IPv6 support, a Poco::NotImplementedException will be thrown.
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.
currentSession
Session::Ptr currentSession();
Returns the SSL session of the current connection, for reuse in a future connection (if session caching is enabled).
If no connection is established, returns null.
getBlocking
bool getBlocking() const;
Returns the blocking mode of the socket. This method will only work if the blocking modes of the socket are changed via the setBlocking method!
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.
sessionWasReused
bool sessionWasReused();
Returns true iff a reused session was negotiated during the handshake.
setBlocking
void setBlocking(
bool flag
);
Sets the socket in blocking mode if flag is true, disables blocking mode if flag is false.
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.
useSession
void useSession(
Session::Ptr pSession
);
Sets the SSL session to use for the next connection. Setting a previously saved Session object is necessary to enable session caching.
To remove the currently set session, a null pointer can be given.
Must be called before connect() to be effective.
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 iff the given host name is the local host (either "localhost" or "127.0.0.1").
mustRetry
bool mustRetry(
int rc
);
Returns true if the last operation should be retried, otherwise false.
In case of an SSL_ERROR_WANT_READ error, and if the socket is blocking, waits for the underlying socket to become readable.
In case of an SSL_ERROR_WANT_WRITE error, and if the socket is blocking, waits for the underlying socket to become writable.
Can also throw a Poco::TimeoutException if the socket does not become readable or writable within the sockets receive or send timeout.
onSessionCreated
static int onSessionCreated(
SSL * pSSL,
SSL_SESSION * pSession
);
Callback to handle new session data sent by server.
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.
verifyPeerCertificateImpl
long verifyPeerCertificateImpl(
const std::string & hostName
);
Performs post-connect (or post-accept) peer certificate validation.