Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)
Android APIs
public class

SSLCertificateSocketFactory

extends SSLSocketFactory
java.lang.Object
   ↳ javax.net.SocketFactory
     ↳ javax.net.ssl.SSLSocketFactory
       ↳ android.net.SSLCertificateSocketFactory

Class Overview

SSLSocketFactory implementation with several extra features:

  • Timeout specification for SSL handshake operations
  • Hostname verification in most cases (see WARNINGs below)
  • Optional SSL session caching with SSLSessionCache
  • Optionally bypass all SSL certificate checks
The handshake timeout does not apply to actual TCP socket connection. If you want a connection timeout as well, use createSocket() and connect(SocketAddress, int) , after which you must verify the identity of the server you are connected to.

Most SSLSocketFactory implementations do not verify the server's identity, allowing man-in-the-middle attacks. This implementation does check the server's certificate hostname, but only for createSocket variants that specify a hostname. When using methods that use InetAddress or which return an unconnected socket, you MUST verify the server's identity yourself to ensure a secure connection.

One way to verify the server's identity is to use getDefaultHostnameVerifier() to get a HostnameVerifier to verify the certificate hostname.

On development devices, "setprop socket.relaxsslcheck yes" bypasses all SSL certificate and hostname checks for testing purposes. This setting requires root access.

Summary

Public Constructors
SSLCertificateSocketFactory (int handshakeTimeoutMillis)
This constructor was deprecated in API level 8. Use getDefault(int) instead.
Public Methods
Socket createSocket ( String host, int port)
Creates a new socket which is connected to the remote host specified by the parameters host and port .

This method verifies the peer's certificate hostname after connecting (unless created with getInsecure(int, SSLSessionCache) ).

Socket createSocket ( String host, int port, InetAddress localAddr, int localPort)
Creates a new socket which is connected to the remote host specified by the parameters host and port .

This method verifies the peer's certificate hostname after connecting (unless created with getInsecure(int, SSLSessionCache) ).

Socket createSocket ( InetAddress addr, int port, InetAddress localAddr, int localPort)
Creates a new socket which is connected to the remote host specified by the InetAddress address .

Warning: Hostname verification is not performed with this method.

Socket createSocket ( InetAddress addr, int port)
Creates a new socket which is connected to the remote host specified by the InetAddress host .

Warning: Hostname verification is not performed with this method.

Socket createSocket ( Socket k, String host, int port, boolean close)
Creates an SSLSocket over the specified socket that is connected to the specified host at the specified port.

This method verifies the peer's certificate hostname after connecting (unless created with getInsecure(int, SSLSessionCache) ).

Socket createSocket ()
Creates a new socket which is not connected to any remote host.
static SocketFactory getDefault (int handshakeTimeoutMillis)
Returns a new socket factory instance with an optional handshake timeout.
static SSLSocketFactory getDefault (int handshakeTimeoutMillis, SSLSessionCache cache)
Returns a new socket factory instance with an optional handshake timeout and SSL session cache.
String[] getDefaultCipherSuites ()
Returns the names of the cipher suites that are enabled by default.
static SSLSocketFactory getHttpSocketFactory (int handshakeTimeoutMillis, SSLSessionCache cache)
Returns a socket factory (also named SSLSocketFactory, but in a different namespace) for use with the Apache HTTP stack.
static SSLSocketFactory getInsecure (int handshakeTimeoutMillis, SSLSessionCache cache)
Returns a new instance of a socket factory with all SSL security checks disabled, using an optional handshake timeout and SSL session cache.
byte[] getNpnSelectedProtocol ( Socket socket)
Returns the Next Protocol Negotiation (NPN) protocol selected by client and server, or null if no protocol was negotiated.
String[] getSupportedCipherSuites ()
Returns the names of the cipher suites that are supported and could be enabled for an SSL connection.
void setHostname ( Socket socket, String hostName)
Turns on Server Name Indication (SNI) on a given socket.
void setKeyManagers ( KeyManager[] keyManagers)
Sets the KeyManager s to be used for connections made by this factory.
void setNpnProtocols (byte[][] npnProtocols)
Sets the Next Protocol Negotiation (NPN) protocols that this peer is interested in.
void setTrustManagers ( TrustManager[] trustManager)
Sets the TrustManager s to be used for connections made by this factory.
void setUseSessionTickets ( Socket socket, boolean useSessionTickets)
Enables session ticket support on the given socket.
[Expand]
Inherited Methods
From class javax.net.ssl.SSLSocketFactory
From class javax.net.SocketFactory
From class java.lang.Object

Public Constructors

public SSLCertificateSocketFactory (int handshakeTimeoutMillis)

Added in API level 1

This constructor was deprecated in API level 8.
Use getDefault(int) instead.

Public Methods

public Socket createSocket ( String host, int port)

Added in API level 1

Creates a new socket which is connected to the remote host specified by the parameters host and port . The socket is bound to any available local address and port.

This method verifies the peer's certificate hostname after connecting (unless created with getInsecure(int, SSLSessionCache) ).

Parameters
host the remote host address the socket has to be connected to.
port the port number of the remote host at which the socket is connected.
Returns
  • the created connected socket.
Throws
IOException

public Socket createSocket ( String host, int port, InetAddress localAddr, int localPort)

Added in API level 1

Creates a new socket which is connected to the remote host specified by the parameters host and port . The socket is bound to the local network interface specified by the InetAddress localHost on port localPort .

This method verifies the peer's certificate hostname after connecting (unless created with getInsecure(int, SSLSessionCache) ).

Parameters
host the remote host address the socket has to be connected to.
port the port number of the remote host at which the socket is connected.
localAddr the local host address the socket is bound to.
localPort the port number of the local host at which the socket is bound.
Returns
  • the created connected socket.
Throws
IOException

public Socket createSocket ( InetAddress addr, int port, InetAddress localAddr, int localPort)

Added in API level 1

Creates a new socket which is connected to the remote host specified by the InetAddress address . The socket is bound to the local network interface specified by the InetAddress localHost on port localPort .

Warning: Hostname verification is not performed with this method. You MUST verify the server's identity after connecting the socket to avoid man-in-the-middle attacks.

Parameters
addr the remote host address the socket has to be connected to.
port the port number of the remote host at which the socket is connected.
localAddr the local host address the socket is bound to.
localPort the port number of the local host at which the socket is bound.
Returns
  • the created connected socket.
Throws
IOException

public Socket createSocket ( InetAddress addr, int port)

Added in API level 1

Creates a new socket which is connected to the remote host specified by the InetAddress host . The socket is bound to any available local address and port.

Warning: Hostname verification is not performed with this method. You MUST verify the server's identity after connecting the socket to avoid man-in-the-middle attacks.

Parameters
addr the host address the socket has to be connected to.
port the port number of the remote host at which the socket is connected.
Returns
  • the created connected socket.
Throws
IOException

public Socket createSocket ( Socket k, String host, int port, boolean close)

Added in API level 1

Creates an SSLSocket over the specified socket that is connected to the specified host at the specified port.

This method verifies the peer's certificate hostname after connecting (unless created with getInsecure(int, SSLSessionCache) ).

Parameters
k the socket.
host the host.
port the port number.
close true if socket s should be closed when the created socket is closed, false if the socket s should be left open.
Returns
  • the creates ssl socket.
Throws
IOException

public Socket createSocket ()

Added in API level 1

Creates a new socket which is not connected to any remote host. You must use connect(SocketAddress) to connect the socket.

Warning: Hostname verification is not performed with this method. You MUST verify the server's identity after connecting the socket to avoid man-in-the-middle attacks.

Returns
  • the created unconnected socket.
Throws
IOException

public static SocketFactory getDefault (int handshakeTimeoutMillis)

Added in API level 1

Returns a new socket factory instance with an optional handshake timeout.

Parameters
handshakeTimeoutMillis to use for SSL connection handshake, or 0 for none. The socket timeout is reset to 0 after the handshake.
Returns
  • a new SSLSocketFactory with the specified parameters

public static SSLSocketFactory getDefault (int handshakeTimeoutMillis, SSLSessionCache cache)

Added in API level 8

Returns a new socket factory instance with an optional handshake timeout and SSL session cache.

Parameters
handshakeTimeoutMillis to use for SSL connection handshake, or 0 for none. The socket timeout is reset to 0 after the handshake.
cache The SSLSessionCache to use, or null for no cache.
Returns
  • a new SSLSocketFactory with the specified parameters

public String[] getDefaultCipherSuites ()

Added in API level 1

Returns the names of the cipher suites that are enabled by default.

Returns
  • the names of the cipher suites that are enabled by default.

public static SSLSocketFactory getHttpSocketFactory (int handshakeTimeoutMillis, SSLSessionCache cache)

Added in API level 8

Returns a socket factory (also named SSLSocketFactory, but in a different namespace) for use with the Apache HTTP stack.

Parameters
handshakeTimeoutMillis to use for SSL connection handshake, or 0 for none. The socket timeout is reset to 0 after the handshake.
cache The SSLSessionCache to use, or null for no cache.
Returns
  • a new SocketFactory with the specified parameters

public static SSLSocketFactory getInsecure (int handshakeTimeoutMillis, SSLSessionCache cache)

Added in API level 8

Returns a new instance of a socket factory with all SSL security checks disabled, using an optional handshake timeout and SSL session cache.

Warning: Sockets created using this factory are vulnerable to man-in-the-middle attacks!

Parameters
handshakeTimeoutMillis to use for SSL connection handshake, or 0 for none. The socket timeout is reset to 0 after the handshake.
cache The SSLSessionCache to use, or null for no cache.
Returns
  • an insecure SSLSocketFactory with the specified parameters

public byte[] getNpnSelectedProtocol ( Socket socket)

Returns the Next Protocol Negotiation (NPN) protocol selected by client and server, or null if no protocol was negotiated.

Parameters
socket a socket created by this factory.
Throws
IllegalArgumentException if the socket was not created by this factory.

public String[] getSupportedCipherSuites ()

Added in API level 1

Returns the names of the cipher suites that are supported and could be enabled for an SSL connection.

Returns
  • the names of the cipher suites that are supported.

public void setHostname ( Socket socket, String hostName)

Turns on Server Name Indication (SNI) on a given socket.

Parameters
socket a socket created by this factory.
hostName the desired SNI hostname, null to disable.
Throws
IllegalArgumentException if the socket was not created by this factory.

public void setKeyManagers ( KeyManager[] keyManagers)

Sets the KeyManager s to be used for connections made by this factory.

public void setNpnProtocols (byte[][] npnProtocols)

Sets the Next Protocol Negotiation (NPN) protocols that this peer is interested in.

For servers this is the sequence of protocols to advertise as supported, in order of preference. This list is sent unencrypted to all clients that support NPN.

For clients this is a list of supported protocols to match against the server's list. If there is no protocol supported by both client and server then the first protocol in the client's list will be selected. The order of the client's protocols is otherwise insignificant.

Parameters
npnProtocols a non-empty list of protocol byte arrays. All arrays must be non-empty and of length less than 256.

public void setTrustManagers ( TrustManager[] trustManager)

Sets the TrustManager s to be used for connections made by this factory.

public void setUseSessionTickets ( Socket socket, boolean useSessionTickets)

Enables session ticket support on the given socket.

Parameters
socket a socket created by this factory
useSessionTickets true to enable session ticket support on this socket.
Throws
IllegalArgumentException if the socket was not created by this factory.