com.entrust.toolkit.util

Class HttpsDirectoryClientJSSE

java.lang.Object

com.entrust.toolkit.util.HttpsDirectoryClientJSSE

All Implemented Interfaces:

LdapDirectory

Direct Known Subclasses:

HttpsDirectoryClient

public class HttpsDirectoryClientJSSE
extends java.lang.Object
implements LdapDirectory

The HttpsDirectoryClientJSSE class uses the HttpURLConnection class to make a connection to the HttpDirectoryServlet. This class will work with both HTTP and HTTPS based URL's. The type will be selected automatically based on the protocol specified in the urlString in the constructor.

This class differs from HttpsDirectoryClient because it uses the URLConnection class to make the network connection instead of using a Socket directly. This will allow the use of the JVM's default URLStreamHandler when making the connection (if desired).

For HTTP based URL's, the SSLSocketFactory and HostnameVerfier parameters may be set to null.

For HTTPS based URL's, the SSLSocketFactory and HostnameVerifier parameters may be used to configure the SSL connection (depending on the URLStreamHandler that is in use). If no SSLSocketFactory is used, the default SSLSocketFactory from the HttpsURLConnection class will be used. If no HostnameVerifier is supplied, the default HostnameVerifier from the HttpsURLConnection class will be used.

To use tunneling:

1. Install the HttpDirectoryServlet class. The documentation for the HttpDirectoryServlet class describes how to install this class.
2. Configure the server to enable SSL (if that is required). The procedure for this step depends on the Web server you use.

Since:

8.0

See Also:

HttpDirectoryServlet, HttpDirectoryClient

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_TIMEOUT The default timeout value used for the http connection and read timeout values.

Constructor Summary

Constructors

Constructor and Description
HttpsDirectoryClientJSSE(HttpsDirectoryClientJSSE copy) This is the copy constructor.
HttpsDirectoryClientJSSE(java.lang.String urlString) Creates an HttpsDirectoryClientJSSE using an HttpsURLConnection object.
HttpsDirectoryClientJSSE(java.lang.String urlString, javax.net.ssl.SSLSocketFactory factory, javax.net.ssl.HostnameVerifier hostnameVerifier, java.net.URLStreamHandler streamHandler) Creates an HttpsDirectoryClient using an HttpsURLConnection object.

Method Summary

Modifier and Type	Method and Description
byte[][]	getAttr(java.lang.String dn, java.lang.String attributeToFind) Implements the getAttr method of the LdapDirectory interface.
X509CRL[]	getCRLs(java.lang.String distributionPoint, boolean wantARL) Implements the getCRLs() method of the LdapDirectory interface.
java.net.URL	getURL() Return the base URL used to make the URLConnection
boolean	isAvailable() Determines whether the remote servlet is available.
void	setClientCredentials(java.security.cert.X509Certificate verificationCertificate, java.security.cert.X509Certificate caCertificate, java.security.PrivateKey signingKey) This method is never used by this implementation.
void	setConnectionTimeout(int timeout) Sets the connection timeout used when making the connection to the HTTP servlet
void	setReadTimeout(int timeout) Sets the read timeout used when reading data from the HTTP servlet.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_TIMEOUT

public static final int DEFAULT_TIMEOUT

The default timeout value used for the http connection and read timeout values. Default is 10 seconds.

See Also:

Constant Field Values

Constructor Detail

HttpsDirectoryClientJSSE

public HttpsDirectoryClientJSSE(java.lang.String urlString,
                                javax.net.ssl.SSLSocketFactory factory,
                                javax.net.ssl.HostnameVerifier hostnameVerifier,
                                java.net.URLStreamHandler streamHandler)
                         throws java.net.MalformedURLException,
                                java.net.UnknownHostException,
                                java.io.IOException

Creates an HttpsDirectoryClient using an HttpsURLConnection object. To configure the SSL parameters used by the HttpsURLConnection created by this object, an SSLSocketFactory and HostnameVerifier may be supplied. The port will be obtained from the URL string, or if it does not exist it will use port 80 for http or 443 for https

If a null SSLSocketFactory is supplied, the default SSLSocketFactory setup for use with the HttpsURLConnection will be used.

If a null HostnameVerifier is supplied, the default HostnameVerifier setup for use with the HttpsURLConnection will be used.

If a null URLStreamHandler is supplied, the default URLStreamStreamHandler for the specified protocol will be used.

Parameters:

urlString - the URL string of the Directory servlet. specifies the port.

factory - The SSLSocketFactory that will be used to create the sockets used by this class

hostnameVerifier - The HostnameVerifier used to verify the hostname used when an SSL connection is used.

streamHandler - The URLStreamHandler that will be used to perform the protocol side of the connection.

Throws:

java.net.MalformedURLException - if urlString is not a valid URL.

java.net.UnknownHostException - if the host specified in urlString cannot be contacted.

java.io.IOException - if there is an IO problem after connecting to the host.

HttpsDirectoryClientJSSE

public HttpsDirectoryClientJSSE(java.lang.String urlString)
                         throws java.net.MalformedURLException,
                                java.net.UnknownHostException,
                                java.io.IOException

Creates an HttpsDirectoryClientJSSE using an HttpsURLConnection object. To configure the SSL parameters used by the HttpsURLConnection created by this object, the default SSLSocketFactory and HostnameVerifier will be used. The port will be obtained from the URL string, or if it does not exist it will use port 80 for http or 443 for https

Parameters:

urlString - the URL string of the Directory servlet.

Throws:

java.net.MalformedURLException - if urlString is not a valid URL.

java.net.UnknownHostException - if the host specified in urlString cannot be contacted.

java.io.IOException - if there is an IO problem after connecting to the host.

HttpsDirectoryClientJSSE

public HttpsDirectoryClientJSSE(HttpsDirectoryClientJSSE copy)

This is the copy constructor. It creates a new Instance of this class by copying internal values

Parameters:

copy - The HttpsDirectoryClientJSSE to copy

Method Detail

getURL

public java.net.URL getURL()

Return the base URL used to make the URLConnection

Returns:

the base URL used to make the URLConnection

getAttr

public byte[][] getAttr(java.lang.String dn,
                        java.lang.String attributeToFind)
                 throws javax.naming.NamingException

Implements the getAttr method of the LdapDirectory interface.

This method sends an HTML GET request to the proxy servlet, requesting a Directory search. The search specifies a particular attribute at a particular Directory entry, which is specified by a distinguished name (DN). The getAttr method reads the servlet's response and returns the attribute as an array of byte arrays.

Given a DN and a desired attribute (using X.509 names such as userCertificate, dn, cn, email, and so on), this method returns a byte array containing the attributes certificate, CRL, DN, and email address.

The following code fragment is an example of typical usage. In this case each element of the result is a byte array representation of one of the user's certificates.

     getAttr( "cn=Roger Ramjet, o=Lompoc, c=US", "userCertificate" );
 

Specified by:

getAttr in interface LdapDirectory

Parameters:

dn - the distinguished name

attributeToFind - the attribute to find

Returns:

the attributes as a byte array, or null if no attribute is found

Throws:

javax.naming.NameNotFoundException - if the DN does not exist in the directory

javax.naming.InvalidNameException - if the DN is not a valid DN, for example o=,c=CA

javax.naming.TimeLimitExceededException - if the search timeout value has been set at the servlet, and the search takes longer than the value set.

javax.naming.CommunicationException - if there is a problem communicating with the directory, or there are too many concurrent searches happening already and another search cannot be started.

javax.naming.NamingException - if an error other than those listed above occurs.

getCRLs

public X509CRL[] getCRLs(java.lang.String distributionPoint,
                         boolean wantARL)
                  throws javax.naming.NamingException,
                         java.security.cert.CRLException

Implements the getCRLs() method of the LdapDirectory interface.

This methos sends an HTML GET request to the proxy servlet, requesting a Directory search for CRLs or ARLs at a particular distribution point. It reads the servlet's response and returns an array of CRLs or ARLs.

Specified by:

getCRLs in interface LdapDirectory

Parameters:

distributionPoint - the DN as defined in a certificate

wantARL - a boolean flag indicating that an ARL is required

Returns:

An array of CRLs or ARLs.

Throws:

javax.naming.NamingException - thrown if the search fails

java.security.cert.CRLException - thrown for other errors

isAvailable

public boolean isAvailable()

Determines whether the remote servlet is available.

This does not guarantee that the servlet can communicate with the directory.

Specified by:

isAvailable in interface LdapDirectory

Returns:

true to indicate it is available, false otherwise

setClientCredentials

public void setClientCredentials(java.security.cert.X509Certificate verificationCertificate,
                                 java.security.cert.X509Certificate caCertificate,
                                 java.security.PrivateKey signingKey)

This method is never used by this implementation. It is only included because this class implements LdapDirectory which requires this method to be implemented.

Specified by:

setClientCredentials in interface LdapDirectory

Parameters:

verificationCertificate - a verification certificate

caCertificate - the CA certificate that issued verificationCertificate

signingKey - the private signing key that signs messages verified by verificationCertificate

setConnectionTimeout

public void setConnectionTimeout(int timeout)

Sets the connection timeout used when making the connection to the HTTP servlet

Parameters:

timeout - The timeout value in seconds

setReadTimeout

public void setReadTimeout(int timeout)

Sets the read timeout used when reading data from the HTTP servlet.

Parameters:

timeout - The timeout value in seconds