TCP sockets, supporting SSL/TLS and communication across the firewall. More...
Inherits GDSocketImpl.
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.
accept()
cannot be used.bind()
method cannot be used.con
nect(SocketAddress)
method cannot be used.java.lang.UnsupportedOperationException
will be thrown.close()
method, in order to prevent resource contention. This applies even if the socket was never connected nor used. (An unused native java.net.Soc
ket
can be safely abandoned without the need for an explicit close.)getInetAddress()
method won't return the address of the connected remote host.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.
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.
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.
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.
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... | |
GDSocket | ( | ) | throws IOException |
Call this function to construct a new socket object. Its state will be: unconnected.
GDSocket | ( | boolean | isSecure | ) | throws IOException |
Call this function to construct a new socket object. Its state will be: unconnected.
isSecure | false to use no security, true to use SSL/TLS security. |
GDSocket | ( | Proxy | proxy | ) | throws Exception |
This constructor isn't supported by this subclass. Use GDSocket() or GDSocket(boolean) instead.
GDSocket | ( | String | dstName, |
int | dstPort | ||
) | throws Exception |
This constructor isn't supported by this subclass. Use GDSocket() or GDSocket(boolean) instead.
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 | ( | String | hostName, |
int | port, | ||
boolean | streaming | ||
) | throws Exception |
This constructor isn't supported by this subclass. Use GDSocket() or GDSocket(boolean) instead.
GDSocket | ( | InetAddress | dstAddress, |
int | dstPort | ||
) | throws Exception |
This constructor isn't supported by this subclass. Use GDSocket() or GDSocket(boolean) instead.
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.
void disableHostVerification | ( | ) |
This method switches off host name verification, when making an SSL/TLS connection. Host name verification is an SSL/TLS security option.
This method must be called before connect
.
Switching off host name verification doesn't switch off authenticity verification, see disablePeerVerification.
void disablePeerVerification | ( | ) |
This method switches off certificate authenticity verification, when making an SSL/TLS connection. Authenticity verification is an SSL/TLS security option.
This method must be called before connect
.
Switching off authenticity verification implicitly also switches off host name verification, see disableHostVerification.
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.
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. |
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.
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.
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. |
void connect | ( | SocketAddress | remoteAddr | ) |
This connect
method isn't supported by this subclass. Use connect(SocketAddress,int) or connect(String,int,int) instead.