GDSocket Class Reference

TCP sockets, supporting SSL/TLS and communication across the firewall. More...

Inherits GDSocketImpl.

Description

This class is an extension of the native java.net.Socket class, for utilizing BlackBerry Dynamics secure communication. See the package documentation for an introduction to the BlackBerry Dynamics secure communication feature.

This class extends the native java.net.Socket class and offers the same programming interface, with the following exceptions.

• The following features aren't supported.
  • Out of band data isn't supported.
  • Urgent messages feature isn't supported.
  • Traffic class isn't supported.
  • Server socket methods such as accept() cannot be used.
  • The bind() method cannot be used.
  • The connect(SocketAddress) method cannot be used.
  If the application attempts to use an unsupported feature, a java.lang.UnsupportedOperationException will be thrown.
• Only the default constructor is supported. Other constructors, for example those with parameters for proxy or host address, aren't supported.
• A socket must always be closed, by calling the close() method, in order to prevent resource contention. This applies even if the socket was never connected nor used. (An unused native java.net.Socket can be safely abandoned without the need for an explicit close.)
• Data communication doesn't go via the proxy specified in the mobile device's native settings, if any.
• The getInetAddress() method won't return the address of the connected remote host.

See also

java::net::Socket class reference on the android.com developer website.

java.lang.UnsupportedOperationException class reference on the android.com developer website.

GDHttpClient

GDNetUtility

SSL/TLS Security

The BlackBerry Dynamics socket interface supports use of a Secure Socket Layer or Transport Layer Security (SSL/TLS) to send and receive data.

Using SSL/TLS requires that the remote end has a suitable certificate, and that the certificate is valid. A number of checks for validity are made, some of which can be switched off by the application.

A typical secure socket connection sequence would be as follows. The application makes a first connection attempt. In the first attempt, all checking is switched on. If a security error is encountered, this attempt will fail. The application can then switch off some checking, and make a second connection attempt to the same address as the first connection attempt. With less rigorous checking, the second attempt may succeed where the first failed.

Secure Protocol Selection

Establishing an SSL/TLS connection can involve negotiating and retrying, in order to select a secure protocol that is supported by both client and server. The BlackBerry Dynamics runtime handles client-side negotiation and retrying, if secure communication is in use.

The following protocol versions can be blocked by enterprise management console configuration.

• SSLv3
• TLSv1.0
• TLSv1.1
• TLSv1.2

The configuration of blocked protocol versions can be done in the enterprise management console user interface. The configuration applies at the deployment level and isn't specific to user, policy group, or application server. The block only affects communication with application servers that is routed via the BlackBerry Dynamics proxy infrastructure.

Enterprise server connection notes

BlackBerry Dynamics secure communication can be used to connect to servers that are behind the enterprise firewall. This applies to socket connections and HTTP requests. Note the following when using this capability.

The addresses of any application servers to which connection is being made must be configured in the enterprise management console. The address could be registered as the application's server, or as an additional server, for example.

Note. The application server configuration set in the management console can be obtained in the application code by using the GDAndroid.getApplicationConfig method.

The connection to the application server will be made through the BlackBerry Dynamics proxy infrastructure. The status of the application's connection to the proxy infrastructure can be checked and monitored by using the GDNetworkInfo interface.

See also

System administration tasks

GDNetworkInfo class reference.

Public Member Functions
	GDSocket () throws IOException
	Constructor that prepares a new socket object. More...
	GDSocket (boolean isSecure) throws IOException
	Constructor that prepares a new socket with specified use of SSL/TLS. More...
void	disableHostVerification ()
	Security option: Switch off SSL/TLS host name verification. More...
void	disablePeerVerification ()
	Security option: Switch off SSL/TLS authenticity verification. More...
void	connect (SocketAddress remoteAddr, int timeout) throws IOException
	Connect the socket. More...
void	connect (String hostname, int port, int timeout) throws IOException
	Connect the socket. More...
	GDSocket (Proxy proxy) throws Exception
	Not supported. More...
	GDSocket (String dstName, int dstPort) throws Exception
	Not supported. More...
	GDSocket (String dstName, int dstPort, InetAddress localAddress, int localPort) throws SocketException
	Not supported. More...
	GDSocket (String hostName, int port, boolean streaming) throws Exception
	Not supported. More...
	GDSocket (InetAddress dstAddress, int dstPort) throws Exception
	Not supported. More...
	GDSocket (InetAddress dstAddress, int dstPort, InetAddress localAddress, int localPort) throws Exception
	Not supported. More...
void	connect (SocketAddress remoteAddr)
	Not supported. More...

Constructor & Destructor Documentation

GDSocket() [1/8]

GDSocket

(

)

throws IOException

Call this function to construct a new socket object. Its state will be: unconnected.

GDSocket() [2/8]

GDSocket

(

boolean

isSecure

)

throws IOException

Call this function to construct a new socket object. Its state will be: unconnected.

Parameters

isSecure

false to use no security, true to use SSL/TLS security.

GDSocket() [3/8]

GDSocket

(

Proxy

proxy

)

throws Exception

This constructor isn't supported by this subclass. Use GDSocket() or GDSocket(boolean) instead.

GDSocket() [4/8]

GDSocket	(	String	dstName,
		int	dstPort
	)		throws Exception

This constructor isn't supported by this subclass. Use GDSocket() or GDSocket(boolean) instead.

GDSocket() [5/8]

GDSocket	(	String	dstName,
		int	dstPort,
		InetAddress	localAddress,
		int	localPort
	)		throws SocketException

This constructor isn't supported by this subclass. Use GDSocket() or GDSocket(boolean) instead.

GDSocket() [6/8]

GDSocket	(	String	hostName,
		int	port,
		boolean	streaming
	)		throws Exception

This constructor isn't supported by this subclass. Use GDSocket() or GDSocket(boolean) instead.

GDSocket() [7/8]

GDSocket	(	InetAddress	dstAddress,
		int	dstPort
	)		throws Exception

This constructor isn't supported by this subclass. Use GDSocket() or GDSocket(boolean) instead.

GDSocket() [8/8]

GDSocket	(	InetAddress	dstAddress,
		int	dstPort,
		InetAddress	localAddress,
		int	localPort
	)		throws Exception

This constructor isn't supported by this subclass. Use GDSocket() or GDSocket(boolean) instead.

Member Function Documentation

disableHostVerification()

void disableHostVerification

(

)

This method switches off host name verification, when making an SSL/TLS connection. Host name verification is an SSL/TLS security option.

Host Name Verification

When negotiating an SSL/TLS connection, the server sends a certificate indicating its identity. The certificate includes a number of host names. By default, one of the host names in the certificate must match with the host name specified by the client, or the connection fails.
If host name verification is switched off, the connection succeeds regardless of whether there is a matching host name in the certificate.
If switched on, the BlackBerry Dynamics runtime checks server identity in a way that conforms with the relevant RFC. See under section 3.1 Server Identity, in RFC2818.

This method must be called before connect.

Switching off host name verification doesn't switch off authenticity verification, see disablePeerVerification.

See also

SSL/TLS Security, above

disablePeerVerification()

void disablePeerVerification

(

)

This method switches off certificate authenticity verification, when making an SSL/TLS connection. Authenticity verification is an SSL/TLS security option.

Certificate Authenticity Verification

When negotiating an SSL/TLS connection, the server sends a certificate indicating its identity. By default, the certificate must be verified as trustworthy, or the connection fails. In this context, trustworthiness derives from a chain of digital signatures, rooted in a certification authority.
If authenticity verification is switched off, the connection succeeds regardless of the certificate's trustworthiness.
If authenticity verification is switched on, the BlackBerry Dynamics runtime checks certificate trustworthiness using operating system services. See the javax.net.ssl and android.net reference documentation on the android.com developer website.

This method must be called before connect.

Switching off authenticity verification implicitly also switches off host name verification, see disableHostVerification.

See also

SSL/TLS Security, above

connect() [1/3]

void connect	(	SocketAddress	remoteAddr,
		int	timeout
	)		throws IOException

Call this method to connect the socket to the specified remote end point, with the specified time out.

This method blocks until establishment of the connection succeeds or fails, or the time out expires.

The end point address is specified by an InetSocketAddress object. The object must be created using the createUnresolved() method, and not by using the new operator. This prevents the host name from being looked up on a Domain Name System (DNS) server that is outside the enterprise. The host name itself may be sensitive data, and looking it up on a DNS server outside the enterprise would leak that data.

The following code snippet illustrates correct construction of an end point address object for use with this method.

// The following is correct:
InetSocketAddress addr = InetSocketAddress.createUnresolved(host, port);
 
// The following is incorrect:
// InetSocketAddress wrong_addr = new InetSocketAddress(host, port);

Parameters

remoteAddr	SocketAddress specifying the remote end point. Typically includes the port number and server address of a host.
timeout	Length of time out in milliseconds, or 0 for never. If set for an enterprise end point, must be at least 30 seconds.

Exceptions

IllegalArgumentException	If remoteAddr is invalid or not supported, or if the timeout is negative.
IOException	If the socket is already connected, or if connection failed due to an error, or if connection couldn't be established within the specified time out.
UnsupportedOperationException	If remoteAddr was created with the new operator.

In this version of the SDK, this is the only standard connect method that is supported by this subclass.

connect() [2/3]

void connect	(	String	hostname,
		int	port,
		int	timeout
	)		throws IOException

Call this method to connect the socket to the specified remote end point, with the specified time out. The end point is specified as a separate host name and port number.

This method blocks until establishment of the connection succeeds or fails, or the time out expires.

Parameters

hostname	String containing the host name of remote end point.
port	int representation of the port number of the remote end point.
timeout	Length of time out in milliseconds, or 0 for never.

connect() [3/3]

void connect

(

SocketAddress

remoteAddr

)

This connect method isn't supported by this subclass. Use connect(SocketAddress,int) or connect(String,int,int) instead.