com.entrust.toolkit.x509.directory

Class EntrustSSLSocketFactory

java.lang.Object

javax.net.SocketFactory

javax.net.ssl.SSLSocketFactory

com.entrust.toolkit.x509.directory.EntrustSSLSocketFactory

public class EntrustSSLSocketFactory
extends javax.net.ssl.SSLSocketFactory

Custom socket factory used for creating SSLSockets. This class is used to setup LDAP connections over SSL, and will be configured with the following characteristics:

• An LDAPSTrustManager will be configured using trusted certificates stored in a Singleton object. This is required because the LDAP Context instantiates this class by calling the static getDefault() method. Used in this context, the data configuring the factory must be passed in a static context.
• Hostname Verification (Server Identity Check) specified in RFC 2830 section 3.6 will be performed on every SSLSocket created by this class.
• The default set of Ciphersuites supported by the underlying SSLSocketFactory class will be enabled. If strong cryptographic algorithms are allowed, a stronger set of cipher suites will also be enabled.
• A HandshakeCompleteListener is registered, to retrieve information on the socket parameters used the "com.entrust.toolkit.x509.directory.HandshakeCompleteInfo.trace=4" System.property can be specified at runtime to display this information

Since:

7.2 Patch

See Also:

EntrustHostnameVerifier, HandshakeCompleteInfo

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EntrustSSLSocketFactory.InetHandling Define Enumeration for Inet Handling

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEFAULT_SSL_PROVIDER

Constructor Summary

Constructors

Constructor and Description
EntrustSSLSocketFactory(javax.net.ssl.TrustManager[] tms, javax.net.ssl.KeyManager[] kms, java.security.SecureRandom sr) Initializes an EntrustSSLSocketFactory from an array of TrustManagers, an array of KeyManagers, and a Secure random number generator.
EntrustSSLSocketFactory(javax.net.ssl.TrustManager[] tms, javax.net.ssl.KeyManager[] kms, java.security.SecureRandom sr, java.lang.String provider) Initializes an EntrustSSLSocketFactory from an array of TrustManagers, an array of KeyManagers, and a Secure random number generator.

Method Summary

Modifier and Type	Method and Description
java.net.Socket	createSocket() Creates an unconnected SSLSocket.
java.net.Socket	createSocket(java.net.InetAddress inaddr, int port) Creates a socket and connects it to the specified port number at the specified address.
java.net.Socket	createSocket(java.net.InetAddress address, int port, java.net.InetAddress localhost, int localport) Creates a socket and connects it to the specified remote host on the specified remote port.
java.net.Socket	createSocket(java.net.Socket socket, java.lang.String hostname, int port, boolean autoclose) Returns a socket layered over an existing socket connected to the named host, at the given port.
java.net.Socket	createSocket(java.lang.String hostname, int port) Create the SSLSocket.
java.net.Socket	createSocket(java.lang.String hostname, int port, java.net.InetAddress localhost, int localport) Creates an SSLSocket and connects it to the specified remote host on the specified remote port.
static javax.net.SocketFactory	getDefault() Get the default socket from a static instance.
java.lang.String[]	getDefaultCipherSuites() Returns the defaultCipherSuites used by this SSLSocket
EntrustSSLSocketFactory.InetHandling	getInetAddressHandling() Return how the socket should be configured when created with an InetAddress.
java.lang.String[]	getProtocols() Gets the supported protocols
java.lang.String[]	getSupportedCipherSuites() Returns the Supported Ciphersuites
static EntrustSSLSocketFactory.InetHandling	readInetHandlingProperty() Reads the system property com.entrust.toolkit.x509.directory.EntrustSSLSocketFactory.InetHandling
static void	setDefault(javax.net.ssl.X509TrustManager tm, javax.net.ssl.X509KeyManager km, java.security.SecureRandom random, java.lang.String provider) Set the X509TrustManager, X509KeyManager and SecureRandom which should be used by the static call to getDefault().
void	setEnabledCipherSuites(java.lang.String[] ciphers) Sets the Cipher Suites which should be used.
void	setHostnameVerifier(javax.net.ssl.HostnameVerifier verifier) Allows the end user to set a custom HostnameVerifier.
void	setInetAddressHandling(EntrustSSLSocketFactory.InetHandling handling) This API allows the socket to be configured with how a Socket created with the InetAddress class should be handled.
void	setProtocols(java.lang.String[] protocols) Sets the supported protocols.

Methods inherited from class javax.net.ssl.SSLSocketFactory

createSocket

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_SSL_PROVIDER

public static final java.lang.String DEFAULT_SSL_PROVIDER

See Also:

Constant Field Values

Constructor Detail

EntrustSSLSocketFactory

public EntrustSSLSocketFactory(javax.net.ssl.TrustManager[] tms,
                               javax.net.ssl.KeyManager[] kms,
                               java.security.SecureRandom sr,
                               java.lang.String provider)

Initializes an EntrustSSLSocketFactory from an array of TrustManagers, an array of KeyManagers, and a Secure random number generator.

Parameters:

tms - the TrustManagers

kms - the KeyManagers

sr - the SecureRandom

provider - the provider

EntrustSSLSocketFactory

public EntrustSSLSocketFactory(javax.net.ssl.TrustManager[] tms,
                               javax.net.ssl.KeyManager[] kms,
                               java.security.SecureRandom sr)

Initializes an EntrustSSLSocketFactory from an array of TrustManagers, an array of KeyManagers, and a Secure random number generator.

Parameters:

tms - the TrustManagers

kms - the KeyManagers

sr - The SecureRandom

Method Detail

readInetHandlingProperty

public static EntrustSSLSocketFactory.InetHandling readInetHandlingProperty()
                                                                     throws java.net.SocketException

Reads the system property com.entrust.toolkit.x509.directory.EntrustSSLSocketFactory.InetHandling

Returns:

the InetHandling read from the property

Throws:

java.net.SocketException

getDefault

public static javax.net.SocketFactory getDefault()

Get the default socket from a static instance.

Note this class gets the key material for the LDAPSTrustManager by using the LDAPSTrustStoreSingleton object. If no key material has been supplied, then the LDAPS connection will fail.

Returns:

SocketFactory A newly created socket factory configured with an LDAPSTrustManager.

Throws:

java.security.cert.CertificateException

CertificationRootException

setDefault

public static void setDefault(javax.net.ssl.X509TrustManager tm,
                              javax.net.ssl.X509KeyManager km,
                              java.security.SecureRandom random,
                              java.lang.String provider)

Set the X509TrustManager, X509KeyManager and SecureRandom which should be used by the static call to getDefault().

Parameters:

tm - The X509TrustManager

km - The X509KeyManager

random - The SecureRandom

provider - The provider name

Since:

7.2 SP1

createSocket

public java.net.Socket createSocket(java.net.Socket socket,
                                    java.lang.String hostname,
                                    int port,
                                    boolean autoclose)
                             throws java.io.IOException

Returns a socket layered over an existing socket connected to the named host, at the given port. This constructor can be used when tunneling SSL through a proxy or when negotiating the use of SSL over an existing socket. The host and port refer to the logical peer destination.

Hostname verification will be performed using the EntrustHostnameVerifier. A HandshakeCompleteInfo listener object is also registered using the SSLSocket's addHandshakeCompleteListener(). This can be used to determine information about the socket that was used to create the SSL connection.

Specified by:

createSocket in class javax.net.ssl.SSLSocketFactory

Parameters:

socket - The existing socket

hostname - the hostname of the SSL server

port - the port of the SSL server

autoclose - true indicates the underlying socket should be closed when this socket is closed, false indicates the underlying socket should not be closed.

Returns:

the Socket

Throws:

java.io.IOException

createSocket

public java.net.Socket createSocket(java.net.InetAddress address,
                                    int port,
                                    java.net.InetAddress localhost,
                                    int localport)
                             throws java.io.IOException

Creates a socket and connects it to the specified remote host on the specified remote port. The socket will also be bound to the local address and port supplied. This socket is configured using the socket options established for this factory.

Hostname verification will be performed using the EntrustHostnameVerifier. A HandshakeCompleteInfo listener object is also registered using the SSLSocket's addHandshakeCompleteListener(). This can be used to determine information about the socket that was used to create the SSL connection.

Specified by:

createSocket in class javax.net.SocketFactory

Parameters:

address - The IP address

port - the port of the SSL server

localhost - IP address of the local host

localport - The local port

Returns:

the Socket

Throws:

java.io.IOException

createSocket

public java.net.Socket createSocket(java.net.InetAddress inaddr,
                                    int port)
                             throws java.io.IOException

Creates a socket and connects it to the specified port number at the specified address.

Hostname verification will be performed using the EntrustHostnameVerifier. A HandshakeCompleteInfo listener object is also registered using the SSLSocket's addHandshakeCompleteListener(). This can be used to determine information about the socket that was used to create the SSL connection.

Specified by:

createSocket in class javax.net.SocketFactory

Parameters:

inaddr - The inet address of the SSL server

port - the port of the SSL server

Returns:

the Socket

Throws:

java.io.IOException

createSocket

public java.net.Socket createSocket(java.lang.String hostname,
                                    int port,
                                    java.net.InetAddress localhost,
                                    int localport)
                             throws java.io.IOException

Creates an SSLSocket and connects it to the specified remote host on the specified remote port. The socket will also be bound to the local address and port supplied. Hostname verification will be performed using the EntrustHostnameVerifier. A HandshakeCompleteInfo listener object is also registered using the SSLSocket's addHandshakeCompleteListener(). This can be used to determine information about the socket that was used to create the SSL connection.

Specified by:

createSocket in class javax.net.SocketFactory

Throws:

java.io.IOException

createSocket

public java.net.Socket createSocket()
                             throws java.io.IOException

Creates an unconnected SSLSocket.

Overrides:

createSocket in class javax.net.SocketFactory

Throws:

java.io.IOException

createSocket

public java.net.Socket createSocket(java.lang.String hostname,
                                    int port)
                             throws java.io.IOException

Create the SSLSocket. Hostname verification will be performed using the EntrustHostnameVerifier. A HandshakeCompleteInfo listener object is also registered using the SSLSocket's addHandshakeCompleteListener(). This can be used to determine information about the socket that was used to create the SSL connection.

Specified by:

createSocket in class javax.net.SocketFactory

Parameters:

hostname - The hostname of the SSL server which will be used to make the connection

port - the port number of the SSL server

Throws:

java.io.IOException

See Also:

HandshakeCompleteInfo

getDefaultCipherSuites

public java.lang.String[] getDefaultCipherSuites()

Returns the defaultCipherSuites used by this SSLSocket

Specified by:

getDefaultCipherSuites in class javax.net.ssl.SSLSocketFactory

getSupportedCipherSuites

public java.lang.String[] getSupportedCipherSuites()

Returns the Supported Ciphersuites

Specified by:

getSupportedCipherSuites in class javax.net.ssl.SSLSocketFactory

setEnabledCipherSuites

public void setEnabledCipherSuites(java.lang.String[] ciphers)

Sets the Cipher Suites which should be used. This method overrides the default settings with the suites specified by this class.

Parameters:

ciphers - the list of cipher suites which should be used by this class.

setInetAddressHandling

public void setInetAddressHandling(EntrustSSLSocketFactory.InetHandling handling)

This API allows the socket to be configured with how a Socket created with the InetAddress class should be handled. InetHandling is an enumerated type defined as follows:

public enum InetHandling {HOSTNAME, IPADDRESS, REJECT, COMPAT}

• HOSTNAME - An InetAddress will be created with a hostname
• IPADDRESS - The InetAddress will be created with an IP Address
• REJECT - The default setting, throws an exception if sockets are created with an InetAddress
• COMPAT - Compatible with previous versions of the toolkit. Uses Session.getPeerHost to lookup the hostname

Note, if the HOSTNAME or IPADDRESS setting is used, it will be up to the client application to enforce that InetAddress objects are created with that type of object. Failure to do so may result in a DNS lookup which makes the implementation vulnerable to DNS attacks.

Note: Using a hostname to create the socket is always safe.

Parameters:

handling - enumerated type.

Since:

7.2 SP2 Patch

getInetAddressHandling

public EntrustSSLSocketFactory.InetHandling getInetAddressHandling()
                                                            throws java.io.IOException

Return how the socket should be configured when created with an InetAddress.

This will be the value set using the setInetAddressHandling(InetHandling) or the default value which is defined in the System property com.entrust.toolkit.x509.directory.EntrustSSLSocketFactory.InetHandling variable

Returns:

an InetHandling enumerate type, which will contain one of the following values:

 REJECT which will throw an exception
 HOSTNAME which will assume InetAddress is created with a hostname
 IPADDRESS which will assume InetAddress is created with an IP
 COMPAT - Compatible with previous versions of the toolkit.  Uses Session.getPeerHost
          to lookup the hostname
 

Throws:

java.io.IOException - if inetHandling has not been set and the default value set using the system property is set incorrectly

Since:

7.2 SP2 Patch

setHostnameVerifier

public void setHostnameVerifier(javax.net.ssl.HostnameVerifier verifier)

Allows the end user to set a custom HostnameVerifier. The default use case is to use an EntrustHostnameVerifier.

Note: Setting this value to null will turn off hostname verification

Parameters:

verifier - the custom HostnameVerifier to be set

getProtocols

public java.lang.String[] getProtocols()

Gets the supported protocols

Returns:

the supported protocols

Since:

8.0 patch

setProtocols

public void setProtocols(java.lang.String[] protocols)

Sets the supported protocols.

Parameters:

protocols - the supported protocols to set

Since:

8.0 patch