Package com.isode.dsapi.internal

Class IsodeDirectorySession

java.lang.Object
com.isode.dsapi.DirectorySession
com.isode.dsapi.internal.IsodeDirectorySession
All Implemented Interfaces:
SWIG_DSAPIConstants
Direct Known Subclasses:
TracedIsodeDirectorySession
public class IsodeDirectorySession extends DirectorySession
This class subclasses DirectorySession to provide extra functionality which is specific to Isode applications, but does not need to be part of the public java-dsapi interface.

Currently, the only functionality available in addition to DirectorySession is the ability (enabled by default) to have various information read from the DSA after a successful bind operation. This is achieved by having the postBindHook() method call loadIsodeInfo(). If required, setQuickBind(boolean) can be used to prevent these reads being attempted.

Author:
nh

  • Constructor Details

  • Method Details

    • setQuickBind

      public void setQuickBind(boolean enable)
      Determine whether a successful bind operation should be followed by an attempt to read Isode-specific information from the directory. By default, when an IsodeDirectorySession is bound, loadIsodeInfo() will be called to read in information about naming contexts etc.. To prevent that behaviour, and reduce the amount of work performed at bind time, use this method with a parameter of true.
      Parameters:
      enable - true to prevent the class attempting to read extra information after a bind; false to request that an attempt be made to read the extra information.

    • getDirectoryServerDN

      public DN getDirectoryServerDN()
      Returns the Distinguished name of the directory itself, if known.
      Returns:
      the DSA's DN, or null if it is not known.
      See Also:

    • getIsodeDsaDir

      public String getIsodeDsaDir()
      For an Isode Directory Server, returns the location of the DSA directory, if known.
      Returns:
      the DSA's directory path, or null if not known.
      See Also:

    • getServerhostname

      public String getServerhostname()
      Determine the name of the system on which the Isode directory server is running, if possible.

      Some Isode DSAs advertise the name of the system which they are running on, which they derived from a call to the Isode library function "getlocalhost()". By comparing the server's host name with that returned by a call to Isode.getLocalhostname(), a caller can check if the server is running on the same system as the client.

      Returns:
      a String containing the value reported by the server as its own localhostname. If the server does not report any information, then this method will return null.
      Since:
      15.0
      See Also:

    • isServerOnLocalSystem

      public boolean isServerOnLocalSystem()
      Determine (if possible) whether the server that is connected on this session is running on the local system.

      In some cases (e.g. D2 DSAs) it will not be possible to establish the server's hostname, in which case this method will always return false whether or not the server is running on the local system.

      Returns:
      true if the hostname reported by the server as its localhost is the same as the hostname for the system that the caller is using. False if the server is not running on the same system, or if the server's hostname is unknown.
      Since:
      15.0
      See Also:

    • getIsodeManagerDNs

      public List<DN> getIsodeManagerDNs()
      For an Isode Directory Server, returns an array of DNs representing DSA Manager values, if known.
      Returns:
      the DSA manager DNs, or empty if the information is not known.
      See Also:

    • getStrongAuthImplementationVersion

      public int getStrongAuthImplementationVersion() throws NotBoundException
      Determine the strong authentication implementation version advertised by this DSA, or -1 if the DSA does advertise any version.
      Returns:
      the strong implementation version, which will be -1 if none is advertised.
      Throws:
      NotBoundException - if the DSA has not yet been bound to.
      Since:
      14.4
      See Also:

    • isStrongAuthActive

      public boolean isStrongAuthActive() throws NotImplementedException, NotBoundException
      For a session that has been bound, determine whether this DSA reports that strong authentication is active.

      For DSAs which do not advertise strong authentication information, this method will throw a NotImplementedException.

      Callers can use getStrongAuthImplementationVersion() to ascertain whether the DSA reports strong authentication configuration information.

      Returns:
      true if the DSA reports that strong authentication is enabled, false if the DSA reports that it's disabled.
      Throws:
      NotImplementedException - if the DSA does advertise any strong authentication configuration information.
      NotBoundException - if the DSA has not yet been bound to.
      Since:
      14.4
      See Also:

    • getStrongAuthTrustAnchors

      public List<byte[]> getStrongAuthTrustAnchors() throws NotImplementedException, NotBoundException
      For a session which has been bound, obtain a list of the strong authentication trust anchors that this DSA is using. This function does a directory read operation on the Root DSE to get the trustAnchors.

      For DSAs which do not advertise strong authentication information, this method will throw a NotImplementedException.

      Callers can use getStrongAuthImplementationVersion() to ascertain whether the DSA reports strong authentication configuration information.

      Returns:
      a list containing the BER representation of each of the advertised trust anchors, or null if none are advertised.
      Throws:
      NotImplementedException - if the DSA does advertise any strong authentication configuration information.
      NotBoundException - if the DSA has not yet been bound to.
      Since:
      14.4
      See Also:

    • getStrongAuthCertificates

      public List<byte[]> getStrongAuthCertificates() throws NotImplementedException, NotBoundException
      For a session which has been bound, obtain a list of the untrusted certificates which may be used by this DSA when performing certificate verification.

      Note that this function does a directory read operation on the Root DSE to get the information, and so will return current information rather than whatever was read when the session was bound.

      For DSAs which do not advertise strong authentication information, this method will throw a NotImplementedException.

      Callers can use getStrongAuthImplementationVersion() to ascertain whether the DSA reports strong authentication configuration information.

      Returns:
      a list containing the BER representation of each of the advertised certificates, or null if none is advertised.
      Throws:
      NotImplementedException - if the DSA does advertise any strong authentication configuration information, or if the local schema does not understand the "strongAuthCertificate" attribute type.
      NotBoundException - if the DSA has not yet been bound to.
      Since:
      15.0
      See Also:

    • getStrongAuthServerCertificate

      public byte[] getStrongAuthServerCertificate() throws NotImplementedException, NotBoundException
      For a session which has been bound, find the certificate which is being advertised as the server for strong authentication (X.509).

      Note that this function does a directory read operation on the Root DSE to get the information, and so will return current information rather than whatever was read when the session was bound.

      For DSAs which do not advertise strong authentication information, this method will throw a NotImplementedException.

      Callers can use getStrongAuthImplementationVersion() to ascertain whether the DSA reports strong authentication configuration information.

      Returns:
      a byte array containing the BER representation of the server's certificate, or null if none is advertised.
      Throws:
      NotImplementedException - if the DSA does advertise any strong authentication configuration information, or if the local schema does not understand the "strongAuthServerCertificate" attribute type.
      NotBoundException - if the DSA has not yet been bound to.
      Since:
      15.0
      See Also:

    • getIsodeWhoAmI

      public DN getIsodeWhoAmI() throws NotImplementedException
      Returns a DN representing the authorization identity that the DSA has associated with this DirectorySession object, if available.

      Note that this functionality is supported only for versions of Isode directory servers since IsodeDirectorySession.DsaVersion.D3.

      Returns:
      a DN representing the identity of the bound session, so far as the DSA is concerned. A value of null indicates an anonymous bind.
      Throws:
      NotImplementedException - if the DSA does not support this functionality.
      Since:
      15.0
      See Also:

    • preBindHook

      protected void preBindHook() throws NotBoundException
      Remove any stale directory information we may have before attempting a bind
      Overrides:
      preBindHook in class DirectorySession
      Throws:
      NotBoundException - The directory will not be able to be set up.

    • postBindHook

      protected void postBindHook()
      Load Isode-specific useful info after a bind
      Overrides:
      postBindHook in class DirectorySession

    • preUnbindHook

      protected void preUnbindHook()
      Remove Isode-specific useful info when unbinding
      Overrides:
      preUnbindHook in class DirectorySession

    • loadIsodeInfo

      public void loadIsodeInfo()
      Perform a "best-efforts" attempt to read various information about the directory. This is typically done when a new IsodeDirectorySession is bound, but may be requested at any subsequent time (e.g. if there is reason to believe that something has changed such as a new naming context or updated RBAC policy).

      It may also be appropriate to call this method for an object where setQuickBind(boolean) has been used to disable the loading of this information at bind time.

      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library
      See Also:

    • readEntry

      public Entry readEntry(DN dn, Selection sel, CommonArgs cargs) throws NativeLibraryException, NoSuchAttributeException, NotBoundException, NotImplementedException, NullPointerException, IndicationException, SignedOpFailedException, DirectoryOperationFailedException
      Perform a synchronous read of a specific directory entry and return an Entry object (avoiding the need for callers to process the Indication). Should the specified entry not exist, this method returns null rather than throwing a NoSuchEntryException.

      This method overrides the functionality in the base class so that extra information may be included in the entry returned.

      For an Isode DSA, there are certain attributes that may be present on the root entry which will are only returned when specifically requested (i.e. you won't see them for a Selection that requests all user+oper attributes). Since the loadIsodeInfo() method is likely to have read these when the directory was bound, this method can merge the values into the returned entry.

      Overrides:
      readEntry in class DirectorySession
      Parameters:
      dn - DN of the entry to read. Must not be null.
      sel - Selection representing the required selection. Must not be null.
      cargs - Common arguments, null indicates defaults.
      Returns:
      The entry as read from the directory, or null no such entry was found. If dn represents the root entry, then an attempt will be made to include extra attributes in the value returned.
      Throws:
      IndicationException - if the underlying layer returned an Indication that represents a failure status from the DSA.
      NotBoundException - if this DirectorySession is not currently bound.
      DirectoryOperationFailedException - if the operation was sent to the directory, and the directory returned an "operation failed" status with no extra indication or information.
      NullPointerException - if dn or sel is null.
      NotImplementedException - if an attempt was made to perform a signed operation on a session which has not been strongly authenticated.
      SignedOpFailedException - if for a signed read, an error occurred when attempting to sign the read request.
      IncompleteReadException - if the read operation completed, but information in the indication suggests that it is not possible to be certain whether the entry was successfully read. Callers may extract the Indication from the exception object in order to decide what action to take.
      NoSuchAttributeException - if sel names attributes which this entry does not contain.
      NativeLibraryException - if an unrecoverable error was detected by the native library
      Since:
      14.4
      See Also:

    • getDsaVersion

      public IsodeDirectorySession.DsaVersion getDsaVersion()
      DSA version of the directory.
      Returns:
      The DSA version if known, DsaVersion.UNKNOWN otherwise.
      Since:
      15.0

    • getDsaVendorVersion

      public String getDsaVendorVersion()
      Determine the dsa vendor version, if available
      Returns:
      the value of the "vendorversion" attribute on the DSA's root entry, or null if no value was present
      Since:
      15.0
      See Also:

    • getDsaVendorName

      public String getDsaVendorName()
      Determine the dsa vendor name, if available
      Returns:
      the value of the "vendorname" attribute on the DSA's root entry, or null if no value was present
      Since:
      15.0
      See Also:

    • initConfigManager

      public ConfigManager initConfigManager() throws IncorrectVersionException
      Initialise config manager. If the config manager was initialised before, it re-initialises it.

      No directory operations are performed in this method.

      Returns:
      config manager
      Throws:
      IncorrectVersionException - if the version of DSA is not compatible
      Since:
      15.0

    • getConfigManager

      public ConfigManager getConfigManager()
      Get config manager
      Returns:
      config manager, can be null
      Since:
      15.0
      See Also:

    • getConfigDN

      public DN getConfigDN()
      Return the DN of the entry that contains configuration information for this DSA. In the case of a D2 DSA, the entry will be the DSA's own DN (e.g. "cn=dsa, o=isode"). For a D3 DSA, the entry will be "cn=core,cn=config". If the DSA's version is unknown, the method returns null.
      Returns:
      the DN of the entry that contains configuration information, which will be null if the entry DN cannot be determined.
      Since:
      15.0

    • isHGECipherAvailable

      public boolean isHGECipherAvailable()
      Determine whether the DSA is advertising the cipher suite CryptoUtils.CIPHER_SUITES.TLS_RSA_WITH_AES_128_GCM_SHA256 in its list tlsAvailableCiphers. DSAs without HGE capability will not do this, and so it is likely that if the cipher is being offered by an Isode DSA, then that means the DSA has an HGE license (or is a dev build).
      Returns:
      true if the DSA is advertising a cipher suite that would not be available unless it has HGE capability; false if the DSA was not offering such a suite.
      Since:
      15.0

    • getTlsAvailableCipherSuites

      public List<String> getTlsAvailableCipherSuites()
      Get the list of available cipher suites from the dsa
      Returns:
      list of available cipher suites list as strings each containing a number representing a cipher suite value which could be turned into a enum using CryptoUtils.CIPHER_SUITES
      Since:
      15.0

    • getDsaPresentationAddress

      public PresentationAddress getDsaPresentationAddress()
      Get the presentation address of the dsa
      Returns:
      the dsa's presentation address or null if the access point attribute of the dsa could not be determined
      Since:
      15.0

    • getAvailableGDAMs

      public List<DN> getAvailableGDAMs()
      Get the list of available GDAM DNs from the dsa. "Available" GDAMs are those which don't currently contain any naming context.

      The list will be empty if there are no available GDAMs or if the information could not be read.

      Returns:
      list of available GDAM DNs, will never be null
      Since:
      15.0

    • getMasterGDAMs

      public List<DN> getMasterGDAMs()
      Get the list of "master" GDAM DNs from the DSA. "Master" GDAMs are those which contain master information. New locally mastered naming contexts can be added to any GDAM in this list.

      The list will be empty if there are no GDAMs mastered on this system, or if the information could not be read.

      Returns:
      list of available master DNs, will never be null
      Since:
      15.0

    • getShadowGDAMs

      public List<DN> getShadowGDAMs()
      Get the list of "shadow" GDAM DNs from the dsa. "Shadow" GDAMs are those which contain shadowed data.

      The list will be empty if there are no shadow GDAMs or if the information could not be read.

      Returns:
      list of available GDAM DNs, will never be null
      Since:
      15.0

    • getNamingContexts

      public List<DN> getNamingContexts()
      Return the list of DNs representing values for "namingContexts" as read from the root entry of the DSA, if known.
      Returns:
      the naming contexts for this DSA, empty if the information is not known.
      Since:
      15.0

    • getSaslInstalledMechanisms

      public List<String> getSaslInstalledMechanisms() throws NotBoundException
      Return a list containing the "saslInstalledMechanisms" that are advertised by this DSA on the root entry. This list is computed by the DSA based on the SASL plugins available, and so is a list of mechanisms which could be enabled, rather than a list of mechanisms which is being used.
      Returns:
      a list of Strings, with each String containing the name of a SASL mechanism. If the DSA does not provide this information, then the list returned will have no elements (i.e. the method won't return null).
      Throws:
      NotBoundException - if the DSA has not yet been bound to.
      Since:
      15.0

    • getPwdAvailableSchemeGenerators

      public List<String> getPwdAvailableSchemeGenerators() throws NotBoundException
      Return a list containing the available password scheme generators that are advertised by this DSA on the root entry.
      Returns:
      a list of Strings, which each String containing the name of a password scheme generator. If the DSA does not report any information, then the list returned will have no elements (i.e. the method won't return null)
      Throws:
      NotBoundException - if the DSA has not yet been bound to.
      Since:
      15.0

    • getPwdAvailableSchemeComparators

      public List<String> getPwdAvailableSchemeComparators() throws NotBoundException
      Return a list containing the available password scheme comparators that are advertised by this DSA on the root entry.
      Returns:
      a list of Strings, which each String containing the name of a password scheme comparator. If the DSA does not report any information, then the list returned will have no elements (i.e. the method won't return null)
      Throws:
      NotBoundException - if the DSA has not yet been bound to.
      Since:
      15.0

    • getTlsDefaultCipherSuites

      public List<String> getTlsDefaultCipherSuites() throws NotBoundException
      Return a list containing the ciphers that the DSA advertises in the root entry as being members of the "DEFAULT" set of ciphers.
      Returns:
      list of available cipher suites list as strings each containing a number representing a cipher suite value which could be turned into a enum using CryptoUtils.CIPHER_SUITES. If there is no information from the DSA, an empty list (i.e. not null) will be returned.
      Throws:
      NotBoundException - if the DSA has not yet been bound to.
      Since:
      15.0

    • setBaseDN

      public DN setBaseDN(DN baseDN)
      Specify a base DN to be used to constrain which portion of the directory tree may be accessed through this DirectorySession. If specified, then all operations which attempt to read or update entries that are not at or below baseDN (with the exception of the root entry) will result in a NoSuchEntryException being thrown. Attempts to read the root entry are always permitted, regardless of whether a base DN has been specified. However other operations like search, add, delete, modify, rename are not permitted on the root entry.
      Parameters:
      baseDN - the base DN to use; may be null to indicate that no base DN restriction applies.
      Returns:
      the previous base DN, which may be null.
      Since:
      14.6
      See Also:

    • getBaseDN

      public DN getBaseDN()
      Determine the base DN being used to constrain which portion of the directory tree may be accessed through this DirectorySession.
      Returns:
      the base DN currently being used; may be null if no base DN has been specified.
      Since:
      14.6
      See Also:

    • loadSIOAttributesFromAlternateDN

      public boolean loadSIOAttributesFromAlternateDN(DN... modifiedDNs)
      Ensure cached SIO values are up to date. The SIO values will be re-read from the directory if the "alternatePolicyDN" has changed using the function setAlternateDNForSIO(DN), or if any of the DNs specified in modifiedDNs matches the current "alternatePolicyDN". Otherwise, the method will return without re-reading anything from the directory.
      Parameters:
      modifiedDNs - a list of DNs representing entries that the caller knows have been modified. If any of these match the entry containing SIO information, then the entry will be re-read to make sure SIO information is up to date.
      Returns:
      true if SIO attributes were reloaded or if the alternate DN has been removed so as to use default DSA policy, false otherwise
      Since:
      15.1
      See Also:

    • setAlternateDNForSIO

      public boolean setAlternateDNForSIO(DN alternateDn)
      Set alternate DN which should be used to read SIO related information
      Parameters:
      alternateDn - alternate DN to read SIO related information, set it to null to clear the alternate DN so that default DN used by the DSA would be used for SIO related attributes
      Returns:
      true if setting the alternate DN resulted in reload of SIO related attributes (policy, label and clearance catalogs) and false otherwise
      Since:
      15.1
      See Also:

    • getAlternateDNForSIO

      public DN getAlternateDNForSIO()
      Get the DN that is being used to get SIO related stuff (security policy,catalogs)
      Returns:
      alternate policy DN if configured using setAlternateDNForSIO(DN). Otherwise it returns the DSA's config DN that is used for storing RBAC policy
      Since:
      15.1
      See Also:

    • getSecurityPolicy

      public JRPolicy getSecurityPolicy()
      Get the security policy read from the alternate policy DN if specified or from the DSA's default entry for SIO attributes
      Returns:
      a JRPolicy object constructed from policy xml from alternate policy DN if specified or from the DSA's default entry for SIO attributes. It can be null if attribute is not present or invalid
      Since:
      15.1
      See Also:

    • getMultiPolicy

      public JRMultiPolicy getMultiPolicy()
      Get the multi-policy object which comprises of a primary policy and optional number of secondary policies. The primary and seconadary policies are the attributes read from the alternate policy DN if specified or from the default entry of the DSA
      Returns:
      a Multi Policy object constructed from primary policy and optional seconadry policies read from from alternate policy DN if specified or from the DSA's default entry for SIO attributes. It can be null if primary policy attribute is not present or invalid
      Since:
      15.3
      See Also:

    • getSecurityClearanceCatalog

      public JRClearanceCatalog getSecurityClearanceCatalog()
      Get the security clearance catalog read from the alternate policy DN if specified or from the DSA's default entry for SIO attributes. It is stored as an XML in the entry.
      Returns:
      security clearance catalog , can be null if no JRClearanceCatalog could be created from the xml or if xml is absent
      Since:
      15.1
      See Also:

    • getSecurityLabelCatalog

      public JRLabelCatalog getSecurityLabelCatalog()
      Get the security label catalog read from the alternate policy DN if specified or from the DSA's default entry for SIO attributes. It is stored as an XML in the entry.
      Returns:
      security label catalog, can be null if no JRLabelCatalog could be created from the xml or if xml is absent
      Since:
      15.1
      See Also:

    • getIsodeLicenseInfo

      public com.isode.util.Licensing.IsodeLicenseInfo getIsodeLicenseInfo()
      Get Isode License Information derived from one of the attributes of the post 15.0 Isode DSA.
      Returns:
      isode license information object, will be null for pre-15.1 DSAs and non-isode directory servers
      Since:
      15.1

    • getDSAVersionString

      public String getDSAVersionString()
      Return the value of the attribute "dsaVersion" which was on the root entry of the DSA.
      Returns:
      the value of "dsaVersion", or null if no value was present.
      Since:
      15.0

    • isActiveDirectory

      public boolean isActiveDirectory()
      Determine whether this appears to be an Active Directory server. The flag is set if the directory server reports a set of supportedControl values matching those documented by Microsoft.
      Returns:
      true if this looks like an Active Directory, false otherwise.
      Since:
      15.2
      See Also: