com.entrust.toolkit.util.net

Class LDAPConnection

java.lang.Object

com.entrust.toolkit.util.net.LDAPConnection

public class LDAPConnection
extends java.lang.Object

An generalized implementation of an LDAP Connection which is used to retrieve any type of data from the Directory. The type of data being retrieved should be specified by the LDAPAttributeType class. The information used to find the information must be contained in a GeneralNames class.

This class is only capable of extracting data from GeneralNames that are of type GeneralName.uniformResourceIdentifier and GeneralName.directoryName. In the case of a directoryName (DN), the user's directory (the directory contained in the validation information provided to the constructor) is searched for data. In the case of an LDAP URL, an appropriate JNDIDirectory is created internally and searched for the specified type of data (unless the LDAP URL does not contain a host, in which case the user's directory is used).

In order to be used with a distribution point that contains an LDAP URL, the URL must be valid LDAP URL according to RFC 2255, and must contain the 'dn' component. If the 'hostport' component does not specify a port, '389' is automatically used by default.

This class is only able to retrieve data from directoryName when the user it is associated with is online (when the user is offline, online methods of data retrieval are not used).

Since:

7.2

See Also:

RFC 2255, The LDAP URL Format

Field Summary

Fields

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

Constructor Summary

Constructors

Constructor and Description
LDAPConnection(LdapDirectory directory, boolean offlineSearch) This creates an LDAPConnection using the specified LdapDirectory object.
LDAPConnection(ValidationInfo validationInfo) The constructor; creates a new LDAPConnection object.
LDAPConnection(ValidationInfo validationInfo, boolean offlineSearch) The constructor; creates a new LDAPConnection object.

Method Summary

Modifier and Type	Method and Description
byte[][]	getAttributeByType(LDAPAttributeType attributeType, GeneralNames dpDistributionPoint) Retrieves all data of the indicated type that exist at the indicated distribution point.
LDAPSearchData	getAttributeFromDPName(GeneralName distributionPointName, LDAPAttributeType attributeType, LdapDirectory defaultDirectory, java.util.Map<java.lang.String,JNDIDirectory> directoryCache, java.util.Map<java.lang.String,java.lang.Long> invalidSearchMap, int invalidSearchTimeout) This method parses the Distribution Point Name, and tries to retrieve information from the directory
int	getConnectTimeout()
int	getReadTimeout()
boolean	isInvalidSearch(java.util.Map<java.lang.String,java.lang.Long> invalidSearches, int invalidSearchTimeout, LDAPSearchData searchData) Method to check if the search being performed is invalid.
void	putInvalidSearch(java.util.Map<java.lang.String,java.lang.Long> invalidSearches, LDAPSearchData searchData) Puts an invalid search in the specified Map which maps an invalidSearchKey to a representation of the System.currentTimeMillis() as a Long value.
void	setConnectTimeout(int milliseconds) Sets the connect timeout for connecting to the LDAP resource in milliseconds.
void	setReadTimeout(int milliseconds) Set the Timeout for reading data from the connection in milliseconds.

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 LdAP connection and read timeout values. Default is 10 seconds.

See Also:

Constant Field Values

Constructor Detail

LDAPConnection

public LDAPConnection(ValidationInfo validationInfo,
                      boolean offlineSearch)

The constructor; creates a new LDAPConnection object.

If no directory is configured in the supplied ValidationInfo, the toolkit will not attempt to lookup LDAP URI's because it is considered to be offline.

Parameters:

validationInfo - the user's certificate validation information (provides access to the user's directory).

offlineSearch - The default is false, meaning a directory must be specified for any searches to be performed. When set to true, LDAP URI's will be searched even if a directory has not been specified.

LDAPConnection

public LDAPConnection(ValidationInfo validationInfo)

The constructor; creates a new LDAPConnection object.

If no directory is configured in the supplied ValidationInfo, the toolkit will not attempt to lookup LDAP URI's because it is considered to be offline.

If lookup of LDAP URI's is required when there is no directory, an invalid directory object can be supplied to indicate that the toolkit is "online". This can be done using the LDAPConnection(LdapDirectory, boolean) method. This will allow any LDAP based URI's to be created and followed as required. LDAP directoryNames will still not work.

Parameters:

validationInfo - the user's certificate validation information (provides access to the user's directory).

LDAPConnection

public LDAPConnection(LdapDirectory directory,
                      boolean offlineSearch)

This creates an LDAPConnection using the specified LdapDirectory object.

The offlineSearch parameter is used to determine whether LDAP URI's will be followed if no directory connection is specified. When no directory connection is specified, this is considered to be offline mode. In offline mode, LDAP directory Names cannot be followed because there is no known directory that can be used to perform the search. However, LDAP URI's contain host and port information and can be used to construct an LdapDirectory object. By default, the toolkit will not attempt to lookup LDAP URI's when there is no directory available. However, setting offlineSearch to true will enable LDAP URI's to be followed even if no directory has been supplied.

Parameters:

directory - The directory to use when looking for LDAP directoryName or URI's. This parameter may be null.

offlineSearch - The default is false, meaning a directory must be specified for any searches to be performed. When set to true, LDAP URI's will be searched even if a directory has not been specified.

Throws:

java.lang.IllegalArgumentException - if directory is set to null and offlineSearch is false (this configuration doesn't make sense since no searches can be performed).

Since:

8.0

Method Detail

getAttributeByType

public byte[][] getAttributeByType(LDAPAttributeType attributeType,
                                   GeneralNames dpDistributionPoint)

Retrieves all data of the indicated type that exist at the indicated distribution point.

Parameters:

attributeType - the type of data to be retrieved

dpDistributionPoint - the distribution point in GeneralNames format from which the data will be loaded

Returns:

an array of byte arrays representing the data retrieved from the specified GeneralName. If no data was found, then null is returned.

getAttributeFromDPName

public LDAPSearchData getAttributeFromDPName(GeneralName distributionPointName,
                                             LDAPAttributeType attributeType,
                                             LdapDirectory defaultDirectory,
                                             java.util.Map<java.lang.String,JNDIDirectory> directoryCache,
                                             java.util.Map<java.lang.String,java.lang.Long> invalidSearchMap,
                                             int invalidSearchTimeout)

This method parses the Distribution Point Name, and tries to retrieve information from the directory

Parameters:

distributionPointName - The GeneralName distribution point name, containing the location to search.

attributeType - The type of attribute being searched.

defaultDirectory - The default Directory object to use for the search

directoryCache - The Map that contains a cache of previously used directories. This is optional. If no cache is used, a new directory will be created each time one is needed as long as the UserConfigSettings isRSInternalDirCreateEnabled setting is enabled.

invalidSearchMap - The Map used if the invalid search map will be used. This is optional, and may be null if the invalid search map will not be used

invalidSearchTimeout - The amount of time an Invalid search is considered valid, this is optional. A value of 0 or less indicates the invalid search Map will not be used.

Returns:

The LDAPSearchData containing the results of the search

isInvalidSearch

public boolean isInvalidSearch(java.util.Map<java.lang.String,java.lang.Long> invalidSearches,
                               int invalidSearchTimeout,
                               LDAPSearchData searchData)

Method to check if the search being performed is invalid. A search is considered invalid if the search was performed, but no valid data was returned.

The LDAPSearchData.getInvalidSearchKey() is mapped to the current time when the putInvalidSearch(Map, LDAPSearchData) method was called. This method therefore checks to make sure the invalid search is still invalid based on the given invalidSearchTimeout value. It does this using the following formula:

 System.currentTimeMillis() < (invalidTime.longValue() + invalidSearchTimeout) 
 

This method returns true to indicate an invalid search was found, false if no invalid search was found.

Parameters:

invalidSearches - the Map containing invalid searches, which were added using the putInvalidSearch(Map, LDAPSearchData) method.

invalidSearchTimeout - the length of time the invalid search data will be considered invalid.

searchData - the LDAPSearchData containing the parameters used for the LDAP search

Returns:

true if it is an invalid Search, false if it is not an invalid search

putInvalidSearch

public void putInvalidSearch(java.util.Map<java.lang.String,java.lang.Long> invalidSearches,
                             LDAPSearchData searchData)

Puts an invalid search in the specified Map which maps an invalidSearchKey to a representation of the System.currentTimeMillis() as a Long value. The invalidSearchKey is computed by the LDAPSearchData.getInvalidSearchKey() method.

Parameters:

invalidSearches - The Map containing a String searchKey, and Long time value

searchData - The LDAPSearchData containing the results of an Ldap search

setReadTimeout

public void setReadTimeout(int milliseconds)

Set the Timeout for reading data from the connection in milliseconds. If set to 0 then no read timeout will be used.

Parameters:

milliseconds -

getReadTimeout

public int getReadTimeout()

Returns:

the value of the read timeout in milliseconds

setConnectTimeout

public void setConnectTimeout(int milliseconds)

Sets the connect timeout for connecting to the LDAP resource in milliseconds. If set to 0 then no read timeout will be used.

Parameters:

milliseconds -

getConnectTimeout

public int getConnectTimeout()

Returns:

the value of the connect timeout in milliseconds