com.entrust.toolkit.x509.directory

Class JNDIDirectory

java.lang.Object

com.entrust.toolkit.x509.directory.JNDIDirectory

All Implemented Interfaces:

LdapDirectory

Direct Known Subclasses:

SMProxyDirectory

public class JNDIDirectory
extends java.lang.Object
implements LdapDirectory

Provides an interface to a JNDI Directory.

By default, referrals from the principal directory to other directories are automatically followed using anonymous authentication. If special configuration of a referred directory is required (non-anonymous authentication), this can be accomplished by attaching a pre-configured directory instance that will be used during referral processing by calling attachReferredDirectory(JNDIDirectory).

The JNDIDirectory class uses the Java Naming and Directory Interface (JNDI) as the means of retrieving the data.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	LDAP_VERSION_2
static java.lang.String	LDAP_VERSION_3

Constructor Summary

Constructors

Constructor and Description
JNDIDirectory(javax.naming.directory.DirContext dir) Deprecated. This constructor is for backward-compatibility purposes only. Some of the functionality of this class is not available when this constructor is used. Toolkit users wishing to use their own DirContext instance should write their own LdapDirectory implementation.
JNDIDirectory(JNDIDirectory dir) Copy constructor that creates new object with existing parameters.
JNDIDirectory(java.lang.String URL) Constructs a JNDIDirectory object using an URL and parse its path and query values.
JNDIDirectory(java.lang.String ipAddress, int port) Constructs a JNDIDirectory object using Directory IP address and port number as arguments.

Method Summary

Modifier and Type	Method and Description
void	attachReferredDirectory(JNDIDirectory referredDirectory) Attaches a JNDIDirectory that could be used by this instance to follow LDAP referrals in its principal Directory.
void	close() Closes all of the referred Directories and the principal Directory.
javax.naming.directory.DirContext	connect() Connects to the Directory.
byte[][]	getAttr(java.lang.String DN, java.lang.String attributeToFind) Search the Directory for a given attribute within a DN entry.
AuthenticationType	getAuthenticationtType()
int	getConnectionTimeout() returns the Directory connection timeout used by the underlying socket implementation.
X509CRL[]	getCRLs(java.lang.String distributionPoint, boolean wantARL) Finds the CRLs or ARLs from a distribution point.
static LdapDirectory	getInstance(java.lang.String endPoint, int port, java.lang.Object parms) Returns a LdapDirectory object based on the type of LdapDirectory used.
static LdapDirectory	getInstance(java.lang.String endPoint, int port, java.lang.Object parms, boolean useSMProxy) Returns a LdapDirectory object based on the type of LdapDirectory used.
static LdapDirectory	getInstance(java.net.URL url) Retrieves
LDAPSConfig	getLDAPSConfig()
java.lang.String	getLdapVersion() An accessor method that retrieves the LDAP version.
int	getSearchTimeout() Gets the Directory search timeout.
int	getSoConnectionTimeout() returns the socket connection timeout used by the underlying socket implementation..
java.lang.String	getURL() An accessor method that retrieves the URL.
boolean	isAvailable() Determines whether the Directory is available.
void	resetAuthentication() Resets the parameters required for authenticating to Microsoft Active Directory.
javax.naming.NamingEnumeration	Search(java.lang.String searchBase, java.lang.String searchExpr) Searches the principal Directory for a given entry within a searchbase hierarchy, automatically following LDAP referrals.
byte[][]	Search(java.lang.String searchBase, java.lang.String searchExpr, java.lang.String attributeToFind) Searches the Directory for a given attribute within a searchbase hierarchy.
void	setAuthentication(java.lang.String securityLevel, java.lang.String userName, SecureStringBuffer password) Sets the parameters required for authenticating to Microsoft Active Directory.
void	setAuthenticationType(AuthenticationType at) Sets custom AuthenticationType parameters eg.
void	setClientCredentials(java.security.cert.X509Certificate[] chain, java.security.PrivateKey signingKey) Set client credentials for authenticating to a server.
void	setClientCredentials(java.security.cert.X509Certificate verificationCertificate, java.security.cert.X509Certificate caCertificate, java.security.PrivateKey signingKey) Not available.
void	setConnectionTimeout(int connectionTimeout) Sets the Directory connection timeout.
void	setLDAPSConfig(LDAPSConfig config) Set the LDAPS Configuration parameters.
void	setLdapVersion(java.lang.String ldapVersion) An accessor method that sets the LDAP version.
static void	setMaxConcurrentSearches(int max) Deprecated. no longer required since the search timeout is now controlled by the "com.sun.jndi.ldap.read.timeout" value. This JNDI read timeout value has the same effect as the "search" timeout value used by the toolkit. If there is a problem when a search is done then it will time out based on the value of the setSearchTimeout(int).
void	setSearchTimeout(int searchTimeout) Sets the timeout when searching the Directory.
void	setSoConnectionTimeout(int connectionTimeout) Sets the Directory connection timeout used by the underlying socket implementation.

Methods inherited from class java.lang.Object

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

Field Detail

LDAP_VERSION_2

public static final java.lang.String LDAP_VERSION_2

See Also:

Constant Field Values

LDAP_VERSION_3

public static final java.lang.String LDAP_VERSION_3

See Also:

Constant Field Values

Constructor Detail

JNDIDirectory

public JNDIDirectory(java.lang.String ipAddress,
                     int port)

Constructs a JNDIDirectory object using Directory IP address and port number as arguments.

A URL in the format ldap://ipAddress:port is constructed from this information and stored for later use. The application must call the connect() method before a connection to the URL is established.

This is the principal Directory for this instance.

Parameters:

ipAddress - the Directory IP address as a string, for example, 1.2.3.4

port - the port number

JNDIDirectory

public JNDIDirectory(java.lang.String URL)
              throws javax.naming.NamingException

Constructs a JNDIDirectory object using an URL and parse its path and query values.

A URL in the format ldapscheme://ipAddress:port is required

ldapschemes supported are ldap and ldaps (for secure LDAP using SSL). The application must call the connect() method before a connection to the URL is established.

This is the principal Directory for this instance.

Parameters:

URL - The LDAP URL

Throws:

javax.naming.NamingException

JNDIDirectory

@Deprecated
public JNDIDirectory(javax.naming.directory.DirContext dir)

Deprecated. This constructor is for backward-compatibility purposes only. Some of the functionality of this class is not available when this constructor is used. Toolkit users wishing to use their own DirContext instance should write their own LdapDirectory implementation.

Constructor used to minimize number of Directory connections.

The argument, dir is an initialized JNDI DirContext

The Toolkit will not attempt to manage the provided context. If communication errors occur while using the context, the Toolkit will attempt to create an equivalent DirContext object for future searches. When calling close(), the Toolkit will not attempt to close dir, the context must be closed explicitly outside of the Toolkit.

Parameters:

dir - a javax.naming.directory.DirContext object.

JNDIDirectory

public JNDIDirectory(JNDIDirectory dir)

Copy constructor that creates new object with existing parameters.

The argument, dir is an initialized JNDIDirectory

Parameters:

dir - a com.entrust.toolkit.x509.directory.JNDIDirectory object.

Method Detail

getInstance

public static LdapDirectory getInstance(java.lang.String endPoint,
                                        int port,
                                        java.lang.Object parms)
                                 throws java.lang.ClassNotFoundException,
                                        java.lang.SecurityException,
                                        java.lang.NoSuchMethodException,
                                        java.lang.IllegalArgumentException,
                                        java.lang.InstantiationException,
                                        java.lang.IllegalAccessException,
                                        java.lang.reflect.InvocationTargetException

Returns a LdapDirectory object based on the type of LdapDirectory used. The Java toolkit contains four types of LdapDirectory Objects which can be created by this method based on the type of data passed in:

• JNDIDirectory - The regular JNDIDirectory object, which will use the constructor which takes an IPAdress and Port.
• MultipleDirectories - A Directory object which uses an INI to configure multiple directories. If the passed in parameters is an INI file then this method will return an instance of MultipleDirectores.
• HttpDirectoryClient - The HttpDirectoryClient which takes a String URL, and a port number. If no port number is supplied in the URL it will use a default port 80
• HttpsDirectoryClient - The HttpsDirectoryClient takes a String URL, and a port number. If no port number is supplied it will use a default of port 443. If a third parameter is supplied it is expected it would be the SSLClientContext to configure the SSL parameters

Returns:

A LdapDirectory object or null if one could not be created

Throws:

java.lang.ClassNotFoundException

java.lang.NoSuchMethodException

java.lang.SecurityException

java.lang.reflect.InvocationTargetException

java.lang.IllegalAccessException

java.lang.InstantiationException

java.lang.IllegalArgumentException

Since:

7.2 SP2 Patch

getInstance

public static LdapDirectory getInstance(java.lang.String endPoint,
                                        int port,
                                        java.lang.Object parms,
                                        boolean useSMProxy)
                                 throws java.lang.ClassNotFoundException,
                                        java.lang.SecurityException,
                                        java.lang.NoSuchMethodException,
                                        java.lang.IllegalArgumentException,
                                        java.lang.InstantiationException,
                                        java.lang.IllegalAccessException,
                                        java.lang.reflect.InvocationTargetException

Returns a LdapDirectory object based on the type of LdapDirectory used. The Java toolkit contains four types of LdapDirectory Objects which can be created by this method based on the type of data passed in:

• JNDIDirectory - The regular JNDIDirectory object, which will use the constructor which takes an IPAdress and Port.
• MultipleDirectories - A Directory object which uses an INI to configure multiple directories. If the passed in parameters is an INI file then this method will return an instance of MultipleDirectores.
• HttpDirectoryClient - The HttpDirectoryClient which takes a String URL, and a port number. If no port number is supplied in the URL it will use a default port 80
• HttpsDirectoryClient - The HttpsDirectoryClient takes a String URL, and a port number. If no port number is supplied it will use a default of port 443. If a third parameter is supplied it is expected it would be the SSLClientContext to configure the SSL parameters

Returns:

An LdapDirectory object or null if one could not be created

Throws:

java.lang.ClassNotFoundException

java.lang.NoSuchMethodException

java.lang.SecurityException

java.lang.reflect.InvocationTargetException

java.lang.IllegalAccessException

java.lang.InstantiationException

java.lang.IllegalArgumentException

Since:

8.0 Patch

getInstance

public static LdapDirectory getInstance(java.net.URL url)
                                 throws java.lang.SecurityException,
                                        java.lang.NoSuchMethodException,
                                        java.lang.IllegalArgumentException,
                                        java.lang.InstantiationException,
                                        java.lang.IllegalAccessException,
                                        java.lang.reflect.InvocationTargetException,
                                        java.lang.ClassNotFoundException

Retrieves

Parameters:

url -

Returns:

LdapDirectory

Throws:

java.lang.SecurityException

java.lang.NoSuchMethodException

java.lang.IllegalArgumentException

java.lang.InstantiationException

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

java.lang.ClassNotFoundException

getURL

public java.lang.String getURL()

An accessor method that retrieves the URL.

Returns:

the URL that was set in the constructor, or null

getLdapVersion

public java.lang.String getLdapVersion()

An accessor method that retrieves the LDAP version.

Returns:

LDAP version that was used to connect to Directory

setLdapVersion

public void setLdapVersion(java.lang.String ldapVersion)
                    throws javax.naming.NamingException

An accessor method that sets the LDAP version.

Parameters:

ldapVersion - the LDAP version that was used to connect to Directory. Must be JNDIDirectory.LDAP_VERSION_2 or JNDIDirectory.LDAP_VERSION_3.

Throws:

javax.naming.NamingException

setAuthentication

public void setAuthentication(java.lang.String securityLevel,
                              java.lang.String userName,
                              SecureStringBuffer password)

Sets the parameters required for authenticating to Microsoft Active Directory.

Parameters:

securityLevel - the authentication mode, normally "simple"

userName - the Microsoft Windows name of an Active Directory user

password - a com.entrust.toolkit.util.SecureStringBuffer that has the Microsoft Windows password of that user

setLDAPSConfig

public void setLDAPSConfig(LDAPSConfig config)

Set the LDAPS Configuration parameters. The parameters that can be set are the following:

• SSLEnabled - Used to determine if an SSL connection should be used for this connection. The default setting is false indicating SSL for this directory is not enabled. If a JNDIDirectory is initialized with an LDAPS URL, this setting will automatically be enabled.
• TrustCerts - Setting allows Trusted Certificates (CA or End Entity to be set). These certificates are used to determined whether the SSL server should be trusted by configuring the LDAPSTrustManager for the default EntrustSSLSocketFactory. If a custom SSLSocketFactory has been specified, these certificates will not be used.
• AllowLDAPSReferrals - Setting used to determine whether LDAPS referrals are allowed. It is possible to have a plain LDAP connection get an LDAPS referral. If this setting is set to false it will not attempt to use LDAPS to follow the referral. This setting is set to true by default.
• SSLSocketFactory - Setting allows a custom SSLSocketFactory to be passed in as a parameter. The Toolkit will make sure the String passed in can be instantiated, and is an instance of an SSLSocketFactory.

Note: It is possible to have SSL Disabled for this directory, but still allow LDAPS Referrals. In this case the LDAPSConfig may be configured with the trusted certificates of any directory which may be referred. If a referred directory (using LDAPS) is attached to the JNDIDirectory object then the trusted certificates required for LDAPS to succeeded will already be configured. However, if AllowLDAPSReferral is set to false, LDAPS will not be attempted for any referrals.

Note 2: Because JNDI creates an instance of an SSLSocketFactory using the static getDefault() method, all trusted certificates must be available from a static location. The certificates stored in the LDAPSConfig are stored in a static memory cache (as well as locally). This means every certificate added through the LDAPSConfig object will be trusted for every subsequent LDAPS connection made with a JNDIDirectory instance.

Parameters:

config - The LDAPSConfig object which contains the SSL Configuration parameters

getLDAPSConfig

public LDAPSConfig getLDAPSConfig()

Returns:

the LDAPS Configuration parameters.

setAuthenticationType

public void setAuthenticationType(AuthenticationType at)

Sets custom AuthenticationType parameters eg. KerborosAuthenticationType

getAuthenticationtType

public AuthenticationType getAuthenticationtType()

resetAuthentication

public void resetAuthentication()

Resets the parameters required for authenticating to Microsoft Active Directory.

Your application should call this method when it has finished using the Microsoft Active Directory. After it returns, this JNDIDirectory instance can no longer authenticate to that directory.

attachReferredDirectory

public void attachReferredDirectory(JNDIDirectory referredDirectory)
                             throws javax.naming.NamingException

Attaches a JNDIDirectory that could be used by this instance to follow LDAP referrals in its principal Directory.

Parameters:

referredDirectory - is a Directory referenced by LDAP referrals in the principal Directory

Throws:

javax.naming.NamingException - if an attempt to connect to the provided JNDIDirectory fails

Since:

7.0

close

public void close()
           throws javax.naming.NamingException

Closes all of the referred Directories and the principal Directory. This method is provided for convenience, so the application does not need to maintain references to each JNDIDirectory it attaches to this instance.

Throws:

javax.naming.NamingException - if a naming exception is encountered

Since:

7.0

isAvailable

public boolean isAvailable()

Determines whether the Directory is available.

NOTE: This method does not determine the current directory connection status but rather reports if the javax.naming.directory.DirContext object exists. If the DirContext object does not exist, a new one will be created using connect().

Specified by:

isAvailable in interface LdapDirectory

Returns:

Returns true if the directory is available, false otherwise.

setSearchTimeout

public void setSearchTimeout(int searchTimeout)

Sets the timeout when searching the Directory.

This method uses the JNDI setting "com.sun.jndi.ldap.read.timeout" to specify the read timeout for an LDAP operation. If the search takes longer than the timeout it aborts the read attempt and a NamingException is thrown.

Parameters:

searchTimeout - the search timeout in milliseconds; by default it is 0 which means no search time out

getSearchTimeout

public int getSearchTimeout()

Gets the Directory search timeout.

Returns:

the search timeout in milliseconds; 0 indicates no search timeout

setMaxConcurrentSearches

public static void setMaxConcurrentSearches(int max)

Deprecated. no longer required since the search timeout is now controlled by the "com.sun.jndi.ldap.read.timeout" value. This JNDI read timeout value has the same effect as the "search" timeout value used by the toolkit. If there is a problem when a search is done then it will time out based on the value of the setSearchTimeout(int).

Parameters:

max - the maximum number of concurrent searches allowed; by default it is 0 which means no limit.

setConnectionTimeout

public void setConnectionTimeout(int connectionTimeout)

Sets the Directory connection timeout.

The Directory connection timeout indicates the maximum amount of time that will be spent attempting to establish a connection to the Directory. If exceeded, an exception is thrown indicating the timeout occurred.

Parameters:

connectionTimeout - connection process timeout in milliseconds; by default it is 0 which means no limit

setSoConnectionTimeout

public void setSoConnectionTimeout(int connectionTimeout)

Sets the Directory connection timeout used by the underlying socket implementation.

The Directory connection timeout indicates the maximum amount of time that will be spent attempting to establish a socket connection to the Directory. If exceeded, an exception is thrown indicating the timeout occurred.

Note: When this feature is used, the underlying Socket implementation must support the unconnected socket API Socket.connect(SocketAddress endpoint, int timeout) and the SSLSocketFactory must support the SSLSocketFactory.createSocket()

Parameters:

connectionTimeout - connection process timeout in milliseconds; by default it is 0 which means no limit

getSoConnectionTimeout

public int getSoConnectionTimeout()

returns the socket connection timeout used by the underlying socket implementation..

The Socket connection timeout indicates the maximum amout ot time that will be spent attempting to establish a connection to the Directory. If exceeded, an exception is thrown indicating the timeout occurred.

Note: When this feature is used, the underlying Socket implementation must support the unconnected socket API Socket.connect(SocketAddress endpoint, int timeout) and the SSLSocketFactory must support the SSLSocketFactory.createSocket()

Returns:

the socket connection timeout in milliseconds

getConnectionTimeout

public int getConnectionTimeout()

returns the Directory connection timeout used by the underlying socket implementation.

The Directory connection timeout indicates the maximum amount of time that will be spent attempting to establish a socket connection to the Directory. If exceeded, an exception is thrown indicating the timeout occurred.

Returns:

the directory connection timeout in milliseconds

connect

public javax.naming.directory.DirContext connect()
                                          throws javax.naming.NamingException

Connects to the Directory.

This method establishes a new JNDI context. The method uses the IP address and port number from the constructor, and returns this context so that the application can use it to create additional JNDIDirectory objects using the same Directory connection.

Returns:

the JNDI DirContext handle

Throws:

javax.naming.NamingException - thrown if the directory is not accessible

Search

public javax.naming.NamingEnumeration Search(java.lang.String searchBase,
                                             java.lang.String searchExpr)
                                      throws javax.naming.NamingException

Searches the principal Directory for a given entry within a searchbase hierarchy, automatically following LDAP referrals.

Search performs a search operation on the JNDI context, using the given searchBase, searchExpr parameters, and a subtree scope. The results are returned as a NamingEnumeration.

Parameters:

searchBase - the starting point for the search

searchExpr - the search expression

Returns:

a NamingEnumeration of the search results, in which any LDAP referrals have already been followed, i.e. invoking NamingException.hasMore() on the returned result will not thow any further javax.naming.ReferralException.

Throws:

javax.naming.NamingException - thrown if the entry is not found, or if the search expression is not formatted correctly

Search

public byte[][] Search(java.lang.String searchBase,
                       java.lang.String searchExpr,
                       java.lang.String attributeToFind)
                throws javax.naming.NamingException

Searches the Directory for a given attribute within a searchbase hierarchy.

Search performs a search operation on the JNDI context, using the given searchBase, searchExpr parameters, and a subtree scope. The results are searched for the specified attributeToFind and, if found, the method returns the matching attributes. If the attributeToFind is not found, the method returns null.

Parameters:

searchBase - the starting point for the search

searchExpr - the search expression

attributeToFind - the attribute to be extracted from the entry

Returns:

the attribute as a byte array

Throws:

javax.naming.NamingException - thrown if the entry is not found or the search expression is malformed

getAttr

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

Search the Directory for a given attribute within a DN entry.

The desired attributes (usually userCertificate, caCertificate, or crossCertificatePair), are extracted from the Directory at the location specified by the Distinguished Name, DN.

The search will be re-tried if there was an error communicating with the Directory on the first search attempt, or if the attribute could not be found using the default LDAP binary syntax.

Specified by:

getAttr in interface LdapDirectory

Parameters:

DN - the distinguished name of the entry

attributeToFind - the attribute to be extracted from the entry

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, 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

Finds the CRLs or ARLs from a distribution point.

This method is required to implement the IX509Directory interface. It is called during the certificate path validation process to retrieve all of the revocation lists from a specific CRL Distribution Point.

Specified by:

getCRLs in interface LdapDirectory

Parameters:

distributionPoint - the name of the distribution point

wantARL - a flag indicating whether an ARL (true) or CRL (false) is required

Returns:

the array of CRLs or ARLs found at the distribution point

Throws:

javax.naming.NamingException - thrown if the CRL is not found or the search expression is cot formatted correctly

java.security.cert.CRLException - if the CRL cannot be parsed.

setClientCredentials

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

Not available.

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

setClientCredentials

public void setClientCredentials(java.security.cert.X509Certificate[] chain,
                                 java.security.PrivateKey signingKey)

Set client credentials for authenticating to a server. This implementation does nothing; it is intended to be overridden by subclasses that need to provide additional authentication, such as for SSL client authentication.