ot::ssl
class SSLSocket  (abstract)

The SSL/TLS protocols add a layer of security over a standard TCP/IP socket connection. This additional security comprises one or more of the following protections:-

• Identity protection (authentication) where the identitiy of the peer is verified using public key infrastructure.
• Privacy protection (confidentiality), where the contents of messages are encrypted using a secret key which is known only to the two parties of the communication.
• Integrity protection, where the contents of messages are guaranteed not to have been modified by another party.

Before the handshake commences, the application can influence the choice of cipher suite by specifying an ordered list of acceptable cipher suite names to the setEnabledCipherSuites() method. By default, the security provider will enable only those cipher suites which offer a reasonable level of protection. A list of supported cipher suite names may be obtained using the getSupportedCipherSuites() method. The cipher suite naming convention employed is consistent with the cipher names used within the TLS specification but absent the 'TLS_' prefix.

The SSL handshake can be started explicitly by calling the startHandshake() method. Alternatively, if data is read from or written to the I/O streams associated with the SSLSocket, an implicit handshake is performed before any application data is transferred.

Once the handshake has completed, the SSL connection is associated with a SSLSession, which represents the negotiated parameters and secret keys employed for the duration of the session. The SSLSession object can be obtained by calling the getSession() method.

Multi-threaded considerations:

Static functions are synchronized for safe access from multiple concurrent threads but instance member functions are not. Unlike plain sockets, unless otherwise specified, it is not acceptable for one thread to read from a SSLSocket while another thread writes to the same SSLSocket. This is because some security providers may not support multi-threaded access to a single SSLSession. This is the case when the OpenSSL package is used.

Since:

OpenTop 1.4

StringList

SSLSocket

protected  SSLSocket()

Default constructor which creates an unconnected SSLSocket. All SSLSocket constructors are protected and should be used only when implementing a SSL security provider. Instances of SSLSocket may be created using the methods provided by SSLSocketFactory.

SSLSocket

protected  SSLSocket(InetAddress* pAddress,
                     int port)

Creates a SSLSocket and connects it to the specified port on the network host designated by the provided InetAddress. The registered socket factory is used to create an instance of SocketImpl to perform the network communication for the socket.

All SSLSocket constructors are protected and should be used only when implementing a SSL security provider. Instances of SSLSocket may be created using the methods provided by SSLSocketFactory.

Exceptions:

SocketException - if an error occurs creating or connecting the socket.
NullPointerException - if pAddress is null.

SSLSocket

protected  SSLSocket(const String& host,
                     int port)

Creates a SSLSocket that is connected to a specified host name and port. The host name is first resolved into an InetAddress before connecting to it.

All SSLSocket constructors are protected and should be used only when implementing a SSL security provider. Instances of SSLSocket may be created using the methods provided by SSLSocketFactory.

Parameters:

host - the name of the remote host or a string representation of its IP-address in the form "xxx.xxx.xxx.xxx".

Exceptions:

UnknownHostException - if host cannot be resolved into an Internet address.
SocketException - if an error occurs creating or connecting the socket.

SSLSocket

protected  SSLSocket(Socket* pImpl,
                     const String& host,
                     int port)

Protected constructor that creates a SSLSocket using the passed Socket. All SSLSocket constructors are protected and should be used only when implementing a SSL security provider. Instances of SSLSocket may be created using the methods provided by SSLSocketFactory.

Parameters:

pSocket - pointer to the underlying socket. @host the peer host. @port the port number on the peer host

Exceptions:

NullPointerException - if pSocket is null.

SSLSocket

protected  SSLSocket(InetAddress* pAddress,
                     int port,
                     InetAddress* pLocalAddr,
                     int localPort)

Creates a SSLSocket and connects it to the specified remote port on the network host designated by the provided InetAddress. The created SSLSocket is bound to the specified local port and InetAddress.

If pLocalAddr is null, the socket is bound to any interface on the local host. If localPort is 0, the operating system chooses an unused local port number.

All SSLSocket constructors are protected and should be used only when implementing a SSL security provider. Instances of SSLSocket may be created using the methods provided by SSLSocketFactory.

Exceptions:

NullPointerException - if pAddress is null.
SocketException - if an error occurs creating, binding or connecting the socket.

SSLSocket

protected  SSLSocket(const String& host,
                     int port,
                     InetAddress* pLocalAddr,
                     int localPort)

Creates a SSLSocket and connects it to the specified remote port on the network host designated by the provided InetAddress. The created Socket is bound to the specified local port and InetAddress.

If pLocalAddr is null, the socket is bound to any interface on the local host. If localPort is 0, the operating system chooses an unused local port number.

All SSLSocket constructors are protected and should be used only when implementing a SSL security provider. Instances of SSLSocket may be created using the methods provided by SSLSocketFactory.

Exceptions:

NullPointerException - if pAddress is null.
SocketException - if an error occurs creating, binding or connecting the socket.

See also:

connect() , bind()

~SSLSocket

protected  ~SSLSocket()

Virtual destructor.

addHandshakeCompletedListener

virtual void addHandshakeCompletedListener(HandshakeCompletedListener* pListener)=0

Registers a listener object that will be notified whenever a SSL handshake completes on this SSLSocket. Any number of listener objects may be registered, and they will all be notified when a SSL handshake completion event occurs. Multiple registrations of the same listener object will result in only one registration.

Parameters:

pListener - the HandshakeCompletedListener object to register.

Exceptions:

NullPointerException - if pListener is null.

See also:

removeHandshakeCompletedListener

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

getEnabledCipherSuites

virtual size_t getEnabledCipherSuites(StringList& ret) const=0

Returns an ordered list of cipher suite names which are currently enabled for this SSLSocket. A given security provider may support more cipher suites than are enabled by default. This is because not all cipher suites are equally secure, so security providers should only enable reasonably secure protocols by default.

Parameters:

ret - A reference to a StringList object, the contents of which are replaced with a list of enabled cipher suite names. This will be a subset of the cipher suite names which would be returned by getSupportedCipherSuites().

Returns:

the number of enabled cipher suites.

See also:

getSupportedCipherSuites()

Note:

The fact that a particular cipher suite is enabled does not necessarily mean that it can be used in a SSL handshake. There are various reasons why an enabled cipher suite would not be used, such as the need for a local certificate which hasn't been supplied or the fact that a cipher suite is anonymous but the peer has been configured to require authentication.

getNeedClientAuth

virtual bool getNeedClientAuth() const=0

Returns a boolean flag indicating if client authentication is required during SSL handshaking. This option is only used by SSLSockets operating in SSL server mode.

Returns:

true if client authentication is required; false otherwise.

See also:

setNeedClientAuth()

getPeerHost

virtual String getPeerHost() const

Returns the host name of the remote SSL peer. If a logical host name was provided in the constructor then this is returned, otherwise a reverse DNS look-up of the connected IP address is performed. If this SSLSocket is not yet connected then an empty String is returned.

getPeerPort

virtual int getPeerPort() const

Returns the port number of the remote SSL peer. If a logical port was provided in the constructor then this is returned, otherwise the remote port number from the underlying Socket is returned.

getSession

virtual RefPtr< SSLSession > getSession()=0

Returns a SSLSession object representing the set of parameters and secret keys negotiated during a SSL handshake. If the socket is not connected or an error occurred during the SSL handshake, and invalid SSLSession object is returned.

If the SSL handshake has not yet been performed and the socket is connected to a peer host, the handshake is started causing this method to block until the SSL handshake has completed or an error occurs.

Returns:

a RefPtr to a SSLSession object.

Exceptions:

SSLException - if an error occurs negotiating the SSL connection.

See also:

SSLSession::isValid()

getSupportedCipherSuites

virtual size_t getSupportedCipherSuites(StringList& ret) const=0

Returns an ordered list of cipher suite names which the security provider supports. The most secure cipher suite is listed first and the least secure last.

Parameters:

ret - A reference to a StringList, the contents of which are completely replaced with supported cipher suite names.

Returns:

The number of entries in the returned list.

getUseClientMode

virtual bool getUseClientMode() const=0

Returns a boolean flag indicating if this SSLSocket will use SSL client mode during the SSL handshake. The default for SSLSockets created by a SSLSocketFactory is true.

Returns:

true if SSL client mode will be used; false otherwise.

See also:

setUseClientMode()

getWantClientAuth

virtual bool getWantClientAuth() const=0

Returns a boolean flag indicating if this SSLSocket will request the client to authenticate itself (by sending a certificate) during the SSL handshake. However, if the client declines to send a certificate, the handshake continues anyway.

This option is only relevant to SSLSockets operating in SSL server mode.

Returns:

true if the client will be asked for authentication; false otherwise.

See also:

setWantClientAuth() , setNeedClientAuth()

removeHandshakeCompletedListener

virtual void removeHandshakeCompletedListener(HandshakeCompletedListener* pListener)=0

Unregisters a previously registered listener object. An IllegalArgumentException is thrown if pListener is not currently registered.

Parameters:

pListener - the HandshakeCompletedListener object to unregister.

Exceptions:

NullPointerException - if pListener is null.
IllegalArgumentException - if pListener is not currently registered.

See also:

addHandshakeCompletedListener

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

setEnabledCipherSuites

virtual void setEnabledCipherSuites(const StringList& suites)=0

Specifies the permitted cipher suites which may be used during the SSL handshake. During the SSL handshake negotiations, the list of enabled cipher suites is traversed from beginning to end, with the first acceptable suite being selected. For this reason the application should order the most secure cipher suites at the beginning of the list to help ensure maximum security.

Each value in the list must be a valid cipher suite name as returned by getSupportedCipherSuites().

Exceptions:

IllegalArgumentException - if any of the specified cipher suites are not supported by the security provider.

See also:

getEnabledCipherSuites()

Note:

The fact that a particular cipher suite is enabled does not necessarily mean that it can be used in a SSL handshake. There are various reasons why an enabled cipher suite would not be used, such as the need for a local certificate which hasn't been supplied or the fact that a cipher suite is anonymous but the peer has been configured to require authentication.

setNeedClientAuth

virtual void setNeedClientAuth(bool bSet)=0

Specifies whether client authentication is required during the negotiation of the SSL handshake. This is only used by SSLSockets operating in SSL server mode.

Parameters:

bSet - true if clients must authenticate themselves (by sending a certificate). Setting this value to true also overrides the current setting of setWantClientAuth() to ensure that the client is requested to authenticate itself.

See also:

getNeedClientAuth()

setUseClientMode

virtual void setUseClientMode(bool bClient)=0

Controls whether SSL client or server mode will be used during the SSL handshake. The mode controls both the order and contents of the packets transferred between hosts during the SSL handshake.

The default value is true for SSLSockets which have been created by a SSLSocketFactory because it is most common for clients to operate in SSL client mode.

Parameters:

bSet - true if this SSLSocket should use SSL client mode; false otherwise.

See also:

getUseClientMode()

setWantClientAuth

virtual void setWantClientAuth(bool bWantAuth)=0

Specifies whether client authentication is requested during the SSL handshake. This is only used by SSLSockets operating in SSL server mode.

Parameters:

bSet - true if clients are requested to authenticate themselves (by sending a certificate). Setting this value to false also overrides the current setting of setNeedClientAuth() because the client will not be asked to authenticate itself.

See also:

getWantClientAuth()

startHandshake

virtual void startHandshake()=0

Requests the SSLSocket to perform the SSL handshake negotiations with the remote peer. If the handshake has already been performed, this method requests that a new handshake be performed.

This method will block until the handshake has completed or an error occurs.

Exceptions:

SSLException - if an error occurs during the SSL negotiations.