Package com.isode.dsapi.profile

Class BindProfile

java.lang.Object
com.isode.dsapi.profile.BindProfile
All Implemented Interfaces:
Comparable<BindProfile>
public class BindProfile extends Object implements Comparable<BindProfile>
This class provides a way to keep track of a set of information about a Directory to which a user might want to bind. A collection of these objects may be stored on disk (using a BindProfileList) so that it can persist across separate invocations of the main application.

Arbitrary information may be stored in the profile using either profileSettings or multiValuedSettings.

The class provides a number of methods to create a bound directory session. In all these cases, DSAPI's certificate validation checks are disabled for the bind, and instead any certificate presented by a server is checked using information from the BindProfile (see verifySessionCertificates(DirectorySession)). Normally, a certificate verification failure will result in the bind failing with an NotBoundException, but by using bind(CommonArgs, boolean), a caller may specify that any failure to verify certificates should result in the bind operation succeeding, with a list of the certificates being returned to the caller for further verification. So, for example, an interactive application may wish to present certificates to the user so that he can decide whether or not to continue.

Implementation note on versioning

BindProfile objects are typically, but not always, associated with a BindProfileList. BindProfileList objects have a version which is used to determine their file format, and this may affect which bits of a BindProfile can be loaded/saved. Specifically, when adding new functionality to a BindProfile that is incompatible with earlier BindProfileList implementations, implementors must consider whether the minimumBPLVersion variable should be updated.

For example, if the field "SASLMech" is added to BindProfile, and the BindProfileList class is updated so that it saves and loads "SASLMech", then the code in this class would say something like: 

 public void setSASLMech(String mech) {
    // Requires at least BPL version 2
    minimumBPLVersion = Math.max(minimumBPLVersion,2);
    ...
 }
so that an attempt to save a BindProfile with a "SASLMech" into a "v1" BindProfileList on disk will fail. When the BindProfileList loads in BindProfiles, it should use these "set" methods, so the version info will automatically be kept correct.

If any new fields are added to the BindProfile class, the copy constructor BindProfile(BindProfile) must be updated to copy those fields.

Author:
nh
See Also:

  • Field Details

    • minimumBPLVersion

      protected int minimumBPLVersion
      The minimum version of the BindProfileList implementation which could be used to save this object. By default this is V1, but when a feature is added to this class which requires extra support from the BPL, the corresponding setter method will need to update the field.

      This field is read directly by BindProfileList.saveConfiguration() - no getter method is provided.

    • displayName

      protected String displayName

    • bindProfileAddress

      protected final BindProfileAddress bindProfileAddress

    • dsaDN

      protected DN dsaDN

    • bindDN

      protected DN bindDN

    • userDN

      protected DN userDN

    • ap

      protected AccessPoint ap

    • managed

      protected boolean managed

    • canBind

      protected boolean canBind

    • dsaDir

      protected String dsaDir

    • serviceName

      protected String serviceName

    • x509Identity

      protected Identity x509Identity

    • x509IdentityFileName

      protected File x509IdentityFileName

    • x509StaleIdsForBpList

      protected List<File> x509StaleIdsForBpList
      This keeps a track of all the stale identities associated with this bind profile that gets generated as a result of modification to identity again and again. These identities would be deleted when the bind profile is saved.

    • extraXML

      protected List<String> extraXML
      Contains a collection of XML chunks that appeared inside the "dsa" tag for this BindProfile but were not parsed because they were unrecognised.

    • profileCommonArgs

      public CommonArgs profileCommonArgs
      Common arguments to be associated with this Bind Profile. When a new session is created using bind(), the new IsodeDirectorySession object will contain a reference to this object in its defaultCommonArgs.
      See Also:

    • profileSettings

      public HashMap<String,String> profileSettings
      Public HashMap associated with this Bind Profile. This is used to store application-specific settings associated with the profile. The HashMap should only contain String->String key->value mappings.
      See Also:

    • multiValuedSettings

      public HashMap<String,Set<String>> multiValuedSettings
      Public HashMap of HashSets associated with the BindProfile. This is used to store application-specific settings for multi-valued settings associated with the profile.
      Since:
      14.4
      See Also:

    • bindType

      protected BindType bindType
      Will be one of ANONYMOUS, SIMPLE or STRONG.

  • Constructor Details

    • BindProfile

      public BindProfile(BindProfile orig)
      Create a new BindProfile as a copy of an existing BindProfile.

      This constructor does not copy the access point (the DSA DN of which needs to be unique among all bind profiles in a list) and the managed flag (which can be true only if the access point is present).

      Parameters:
      orig - The original BindProfile to copy

    • BindProfile

      protected BindProfile(BindProfileAddress bindProfileAddress, DN dsaDN, DN bindDN, DN userDN, SASLParametersProfile saslparams, BindType bindType) throws IllegalArgumentException
      Constructor used by BindProfileList and other constructors in this class to create a new object. It is expected that the caller will use various "set" methods to set up other fields.
      Parameters:
      bindProfileAddress - the BindProfileAddress of the DSA. This must not be null
      dsaDN - the DSA's DN (required for strong binds)
      bindDN - the bindDN (simple bind)
      userDN - the userDN (strong bind)
      saslparams - a reference to the SASLParameters object to be used in the case of a SASL bind. This parameter is ignored unless bindType is SASL, in which case it must not be null. This method makes a copy of saslparams.
      bindType - one of ANONYMOUS, SIMPLE, STRONG or SASL
      Throws:
      IllegalArgumentException - if
      • bindType is invalid
      • presentationAddress is null
      • bindDN is null when bindType is SIMPLE
      • dsaDN is null when bindType is STRONG
      • saslMech is null when bindType is SASL
      Since:
      14.6

    • BindProfile

      public BindProfile(BindProfileAddress bindProfileAddress, DN bindDN, String password) throws IllegalArgumentException
      Create a bind profile based on simple authentication.
      Parameters:
      bindProfileAddress - the bindProfileAddress representing the DSA. Must not be null.
      bindDN - the bindDN. Must not be null.
      password - the password associated with bindDN. This may be null, in which case a password will have to be provided when a bind is attempted using this BindProfile.
      Throws:
      IllegalArgumentException - if presentationAddress, bindDN or password is null

    • BindProfile

      public BindProfile(BindProfileAddress bindProfileAddress, DN dsaDN, DN userDN, String identityPassphrase, Identity identity) throws IllegalArgumentException
      Create a new BindProfile object which will use strong authentication.
      Parameters:
      bindProfileAddress - the BindProfileAddress of the DSA. Must not be null.
      dsaDN - the DSA's DN (must not be null)
      userDN - the userDN (may be null)
      identityPassphrase - the passphrase to decrypt the user's identity file on the local system. This may be null, in which case a password will have to be provided when a bind is attempted using this BindProfile.
      identity - X509 Identity that will be used in Strong Binds
      Throws:
      IllegalArgumentException - if presentationAddress, dsaDN or password is null.

    • BindProfile

      public BindProfile(BindProfileAddress bindProfileAddress) throws IllegalArgumentException
      Create a BindProfile representing an anonymous connection.
      Parameters:
      bindProfileAddress - the BindProfileAddress of the DSA. Must not be null.
      Throws:
      IllegalArgumentException - if presentationAddress is null.

    • BindProfile

      public BindProfile(BindProfileAddress bindProfileAddress, SASLParametersProfile saslParams)
      Create a BindProfile representing a connection using SASL authentication.
      Parameters:
      bindProfileAddress - the BindProfileAddress of the DSA. Must not be null.
      saslParams - a reference to an existing SASLParameters. The constructor makes a copy of this object, and so subsequent changes to the object used in this call will not affect the parameters used for a subsequent bind operation. Callers wishing to examine or update the SASLParameters associated with a BindProfile should use getSASLParameters() to obtain a reference to the active set of parameters.
      Since:
      14.6
      See Also:

  • Method Details

    • bind

      public BindProfile.BoundSession bind(CommonArgs bindCommonArgs) throws DSAPIException, NativeLibraryException
      Convenience method to create and bind new IsodeDirectorySession from this object. The returned value contains both the IsodeDirectorySession and the Indication that was returned as a result of the bind operation.

      Typically, bindCommonArgs are used to request password policy information (see RequestPasswordPolicy) and so are unrelated to any CommonArgs associated with the BindProfile. Setting this parameter to null causes a default set of CommonArgs to be used (see default CommonArgs).

      Note that applications interested in password policy should consider handling IndicationExceptions that are thrown by this method: such exceptions will contain a reference to an Indication which may contain password policy information relevant to the bind failure (e.g. "password expired").

      This method will throw a NotBoundException if the server presents certificates which are not trusted.

      Parameters:
      bindCommonArgs - common arguments to be used for the bind operation. If this is null, then default CommonArgs will be used.
      Returns:
      a BoundSession object.
      Throws:
      DSAPIException - if the bind fails
      NativeLibraryException - if an unrecoverable error was detected by the native library.
      See Also:

    • bind

      public IsodeDirectorySession bind() throws DSAPIException, NativeLibraryException
      Convenience method to create a new IsodeDirectorySession from this object, for callers who are not interested in specifying any bind CommonArgs, or obtaining a bind Indication, or doing any certificate verification themselves.

      This method will throw a NotBoundException if the server presents certificates which are not trusted.

      Returns:
      a bound IsodeDirectorySession.
      Throws:
      DSAPIException - if the bind fails
      NativeLibraryException - if an unrecoverable error was detected by the native library.
      See Also:

    • bind

      public BindProfile.BoundSession bind(CommonArgs bindCommonArgs, boolean callerCanVerify) throws DSAPIException, NativeLibraryException
      Performs a bind of the type appropriate for the bind profile. This method allows a caller to specify whether or not he is capable of performing certificate verification himself.

      Any certificates that are returned by the server will be verified using verifySessionCertificates(DirectorySession).

      If verification fails, then the behaviour of the method in this case depends on the setting of the callerCanVerify flag.

      If callerCanVerify is false then connection will be dropped, and a NotBoundException will be thrown.

      If callerCanVerify is true then BindProfile.BoundSession object returned by this method will contain a DirectorySession.SessionCertificates object which the caller is expected to use to perform his own verification (e.g. by showing them to the user and asking if they're OK).

      Parameters:
      bindCommonArgs - common arguments to be used for the bind operation. If this is null, then default CommonArgs will be used (with disableVerification turned on).
      callerCanVerify - true if the caller is able to perform certificate verification, false otherwise.
      Returns:
      a BoundSession object. If callerCanVerify was set to true then the caller must check in here to see if any SessionCertificates are present, and handle them appropriately.
      Throws:
      NotBoundException - if the server presents certificates that are not listed in the bind profile, and callerCanVerify was set to false
      DSAPIException - if the bind fails
      NativeLibraryException - if an unrecoverable error was detected by the native library.
      Since:
      14.6

    • bindWithTrace

      public BindProfile.BoundSession bindWithTrace(CommonArgs bindCommonArgs, boolean callerCanVerify, com.isode.nettrace.observers.NettraceObserver observer) throws DSAPIException, NativeLibraryException
      Creates a traced bind (a bind with a Nettrace attached) of the type appropriate for the bind profile. This method allows a caller to specify whether or not he is capable of performing certificate verification himself.

      Any certificates that are returned by the server will be verified using verifySessionCertificates(DirectorySession).

      If verification fails, then the behavior of the method in this case depends on the setting of the callerCanVerify flag.

      If callerCanVerify is false then connection will be dropped, and a NotBoundException will be thrown.

      If callerCanVerify is true then BindProfile.BoundSession object returned by this method will contain a DirectorySession.SessionCertificates object which the caller is expected to use to perform his own verification (e.g. by showing them to the user and asking if they're OK).

      Parameters:
      bindCommonArgs - common arguments to be used for the bind operation. If this is null, then default CommonArgs will be used (with disableVerification turned on).
      callerCanVerify - true if the caller is able to perform certificate verification, false otherwise.
      observer - a NettraceObserver to register with the Nettrace. It will receives all messages Nettrace receives and decodes.
      Returns:
      a BoundSession object. If callerCanVerify was set to true then the caller must check in here to see if any SessionCertificates are present, and handle them appropriately.
      Throws:
      NotBoundException - if the server presents certificates that are not listed in the bind profile, and callerCanVerify was set to false
      DSAPIException - if the bind fails
      NativeLibraryException - if an unrecoverable error was detected by the native library.
      Since:
      16.0

    • anonymousBind

      public BindProfile.BoundSession anonymousBind(CommonArgs bindCommonArgs) throws DSAPIException, NativeLibraryException
      Create and bind new IsodeDirectorySession from this object, but regardless of the embedded bindType, this method will perform only an anonymous bind.

      This method is typically useful in cases where a BindProfileList has been loaded without a passphrase having been specified, in which case the resultant BindProfiles are likely not to have valid passwords, and so can't be used with the normal bind method.

      The returned value contains both the IsodeDirectorySession and the Indication that was returned as a result of the bind operation.

      Typically, bindCommonArgs are used to request password policy information (see RequestPasswordPolicy) and so are unrelated to any CommonArgs associated with the BindProfile. Setting this parameter to null causes a default set of CommonArgs to be used (see default CommonArgs).

      Note that applications interested in password policy should consider handling IndicationExceptions that are thrown by this method: such exceptions will contain a reference to an Indication which may contain password policy information relevant to the bind failure (e.g. "password expired").

      This method will throw a NotBoundException if the server presents certificates which are not trusted. Use anonymousBind(CommonArgs, boolean) for greater control over what happens in this situation.

      Parameters:
      bindCommonArgs - common arguments to be used for the bind operation. If this is null, then default CommonArgs will be used.
      Returns:
      a BoundSession object.
      Throws:
      DSAPIException - if the bind fails
      NativeLibraryException - if an unrecoverable error was detected by the native library.
      See Also:

    • anonymousBind

      public IsodeDirectorySession anonymousBind() throws DSAPIException, NativeLibraryException
      Convenience method to create an anonymously bound IsodeDirectorySession from this object, for callers who are not interested in specifying any bind CommonArgs, or obtaining a bind Indication.

      This method will throw a NotBoundException if the server presents certificates which are not trusted. Use anonymousBind(CommonArgs, boolean) for greater control over what happens in this situation.

      Returns:
      a bound IsodeDirectorySession.
      Throws:
      DSAPIException - if the bind fails
      NativeLibraryException - if an unrecoverable error was detected by the native library.
      See Also:

    • anonymousBind

      public BindProfile.BoundSession anonymousBind(CommonArgs bindCommonArgs, boolean callerCanVerify) throws DSAPIException
      Create and bind new IsodeDirectorySession from this object, but regardless of the embedded bindType, this method will perform only an anonymous bind.

      This method is typically useful in cases where a BindProfileList has been loaded without a passphrase having been specified, in which case the resultant BindProfiles are likely not to have valid passwords, and so can't be used with the normal bind method.

      The returned value contains both the IsodeDirectorySession and the Indication that was returned as a result of the bind operation, as well as SessionCertificates (if certificate verification failed and the user specified callerCanVerify).

      Typically, bindCommonArgs are used to request password policy information (see RequestPasswordPolicy) and so are unrelated to any CommonArgs associated with the BindProfile. Setting this parameter to null causes a default set of CommonArgs to be used (see default CommonArgs).

      Note that applications interested in password policy should consider handling IndicationExceptions that are thrown by this method: such exceptions will contain a reference to an Indication which may contain password policy information relevant to the bind failure (e.g. "password expired").

      Parameters:
      bindCommonArgs - common arguments to be used for the bind operation. If this is null, then default CommonArgs will be used.
      callerCanVerify - true if the caller is able to perform certificate verification, false otherwise.
      Returns:
      a BoundSession if the bind was successful.
      Throws:
      DSAPIException
      Since:
      14.6

    • setBindDN

      public void setBindDN(DN bindDN)
      Set the bind DN associated with this object, for a simple bind.
      Parameters:
      bindDN - to set
      Throws:
      IllegalArgumentException - if a null DN is passed

    • getBindDN

      public DN getBindDN()
      Returns the bindDN associated with this object (simple bind)
      Returns:
      the bindDN.

    • getUserDN

      public DN getUserDN()
      Return the userDN associated with this object (strong bind)
      Returns:
      the bindDN.

    • getBindType

      public BindType getBindType()
      Determine the type of bind associated with this object.
      Returns:
      one of ANONYMOUS, SIMPLE, or STRONG

    • getDsaDN

      public DN getDsaDN()
      Determine the DSA DN associated with this object. This value is only meaningful when strong authentication is being used.
      Returns:
      the dsaDN

    • getBindProfileAddress

      public BindProfileAddress getBindProfileAddress()
      Determine the BindProfileAddress for this object
      Returns:
      the BindProfileAddress. This will never be null.
      Since:
      15.0

    • setSimpleBindPassword

      public final void setSimpleBindPassword(String password)
      Change the "simple bind" password associated with this object. Subsequent simple bind operations will use the new password. If password is null, then a password will need to be supplied when using this BindProfile to perform a simple bind.
      Parameters:
      password - the password to used for simple binds, or null if no simple bind password is to be associated with this BindProfile.
      Since:
      14.6
      See Also:

    • getSimpleBindPassword

      public String getSimpleBindPassword()
      Get the password that will be used when performing a simple bind. Note this method replaces "getPassword"
      Returns:
      the simple bind password, or null if there isn't one.
      Since:
      14.6

    • getSASLParameters

      public SASLParametersProfile getSASLParameters()
      Determine the SASL parameters associated with this BindProfile. This method returns a reference to the active set of parameters being used, and so changes made to it will affect subsequent bind operations.
      Returns:
      the SASL parameters, or null if this is not a BindProfile that's got a bindType of SASL.
      Since:
      14.6

    • toString

      public String toString()
      Return a user-friendly String representation of this object.
      Overrides:
      toString in class Object
      Returns:
      a String representation of the object.

    • getDisplayName

      public String getDisplayName()
      Returns:
      Returns the displayName.

    • setDisplayName

      public void setDisplayName(String displayName)
      Parameters:
      displayName - The displayName to set.

    • putSetting

      public void putSetting(String key, String value)
      Put or change a setting in the profileSettings. These are application-specific key-value pairs stored by the bind profile.
      Parameters:
      key - Key
      value - Value, or null to delete the setting

    • putMultiValuedSetting

      public void putMultiValuedSetting(String key, String value)
      Add or update the list of values associated with a specific multivalued setting in the bind profile.
      Parameters:
      key - key
      value - the value to be associated with key. Use null to remove all settings associated with key.
      Since:
      14.4

    • putAttributeBlock

      public void putAttributeBlock(AttributeBlock block)
      Add an AttributeBlock to the bind profile
      Parameters:
      block - AttributeBlock to add which must not be null
      Since:
      16.6

    • getAttributeBlocks

      public List<AttributeBlock> getAttributeBlocks(String type)
      Get a list of AttributeBlocks with a specific type field
      Parameters:
      type - The type of AttributeBlock to return, which must not be null
      Returns:
      List of AttributeBlocks which will never be null
      Since:
      16.6

    • getAttributeBlocks

      public List<AttributeBlock> getAttributeBlocks()
      Gets a list of all the attribute blocks in the bind profile.
      Returns:
      A list of all the attribute blocks in the bind profile.
      Since:
      17.0

    • clearAttributeBlocks

      public void clearAttributeBlocks(String type)
      Remove all AttributeBlocks of a given type from the bind profile
      Parameters:
      type - Type to remove, which must not be null
      Since:
      16.6

    • attributeBlockIterator

      public Iterator<AttributeBlock> attributeBlockIterator()
      Get an iterator over all the AttributeBlocks
      Returns:
      iterator, which will never be null
      Since:
      16.6

    • setAttributes

      public void setAttributes(Collection<? extends AttributeBlock> blocks)
      Clear all existing AttributeBlocks and replace with new set
      Parameters:
      blocks - replacement collection of AttributeBlocks, which may be null
      Since:
      16.6

    • clearAttributesOfType

      public void clearAttributesOfType(String type)
      Remove all AttributeBlock of the given type
      Parameters:
      type - Type of AttributeBlock to remove, all AttributeBlock of this type will be removed from the bind profiles attributes. Can be null.
      Since:
      17.0

    • addAttributes

      public void addAttributes(Collection<AttributeBlock> blocks)
      Adds the given Collection of AttributeBlock to the bind profiles attributes list. The added blocks will be appended to the end of the attribute list in the order they are returned by the Collection's iterator.
      Parameters:
      blocks - The Collection of AttributeBlock to add, should not be null
      Since:
      17.0

    • replaceAttributesOfType

      public void replaceAttributesOfType(String type, Collection<AttributeBlock> blocks)
      Removes all AttributeBlock of the given type from the bind profiles attribute list then appends the given Collection of AttributeBlock to the end of the list.
      Parameters:
      type - The type of AttributeBlock to remove. Can be null
      blocks - The Collection of

    • getSetting

      public String getSetting(String key)
      Read a setting from the profileSettings. These are application-specific key-value pairs stored by the bind profile.
      Parameters:
      key - Key
      Returns:
      Value, or null if not found

    • hasSetting

      public boolean hasSetting(String key)
      Indicates if the profile has a setting for the given key.
      Parameters:
      key - A key to check.
      Returns:
      true if the profile has a setting for that key, false otherwise.
      Since:
      17.0

    • hasAnySetting

      public boolean hasAnySetting(Collection<String> keys)
      Indicates if the profile has a a setting for any of the given keys.
      Parameters:
      keys - A Collection of keys, should not be null
      Returns:
      true if their exists a value for at least one of the keys, false otherwise.
      Since:
      17.0

    • hasAnySetting

      public boolean hasAnySetting(String... keys)
      Indicates if the profile has a a setting for any of the given keys.
      Parameters:
      keys - List of keys.
      Returns:
      true if their exists a value for at least one of the keys, false otherwise.
      Since:
      17.0

    • multiValueSettingsIterator

      public Iterator<String> multiValueSettingsIterator()
      Return an iterator over all the available multiValued settings in the bind profile. The Strings returned can be used to obtain values, with multiValueIterator(String)
      Returns:
      an Iterator which will be empty if no values are present.
      Since:
      14.4
      See Also:

    • multiValueIterator

      public Iterator<String> multiValueIterator(String key)
      Return an iterator over a specific set of multivalues in the bind profile.
      Parameters:
      key - the key
      Returns:
      an Iterator which will be empty if no values match key.
      Since:
      14.4
      See Also:

    • multiValueCount

      public int multiValueCount(String key)
      Get the number of values for the given multi value key.
      Parameters:
      key - key string, not null
      Returns:
      number of values (0 or more)

    • compareTo

      public int compareTo(BindProfile bb)
      Compare ordering for list display.
      Specified by:
      compareTo in interface Comparable<BindProfile>

    • isPasswordRequired

      public boolean isPasswordRequired()
      Determine whether a password must be provided when this BindProfile is used to make a connection.
      Returns:
      true for a SIMPLE BindProfile that has no simpleBindPassword, or for a STRONG BindProfile that has no identityPassphrase.

    • setIdentity

      public final void setIdentity(Identity identity)
      Set the x509Identity for this BindProfile. A copy is made of the supplied Identity (so if callers subsequently muck about with the Identity, it won't affect the value stored in this object). The caller is responsible for making sure that the BindProfile's identityPassphrase is consistent with this value.
      Parameters:
      identity - Identity object, which may be null.
      Since:
      14.6
      See Also:

    • getX509Identity

      public Identity getX509Identity()
      Return the X.509 Identity associated with this object (strong bind).
      Returns:
      X.509 Identity

    • removeIdentity

      public void removeIdentity(String identityFileNameOrPath)
      Remove the identity from the identities specific directory when a bind profile is removed or saved
      Parameters:
      identityFileNameOrPath - full path of identity file or filename if the identity exists in the identify specific directory
      Since:
      16.3

    • generateIdentity

      public void generateIdentity(Identity identity, String idPassphrase, boolean deleteOldFile) throws IOException
      Generate an internal Isode specific P12 identity for the given X.509 identity. The Isode specific identity will have a generated name ,will be protected with a random passphrase and stored internally in Isode specific directory.

      Any P12 file that was previously referred to by this BindProfile object will be left alone, unless deleteOldFile is set to true, in which case it will be marked for deletion which means it will be deleted when bind profile list are saved. This may be helpful if there is a chance that something other than this bind profile has a reference to the P12 file in question (e.g. an older version of "isode-bindprofile.xml"

      Parameters:
      identity - X.509 Identity
      idPassphrase - passphrase for the given identity
      deleteOldFile - true to make sure that any P12 file previously referred to by the object will be deleted.
      Throws:
      IOException - if Isode specific identity could not be generated with the new passphrase
      Since:
      15.0

    • generateIdentity

      public void generateIdentity(Identity identity, String idPassphrase) throws IOException
      Generate an internal Isode specific P12 identity for the given X.509 identity. The Isode specific identity will have a generated name ,will be protected with a random passphrase and stored internally in Isode specific directory.

      Usually, it is desirable not to leave "orphan" identities lying around and so this method will mark for deletion any P12 file that had previously been "owned" by this bind profile. To prevent this happening, use generateIdentity(Identity, String, boolean)

      Parameters:
      identity - X.509 Identity
      idPassphrase - passphrase for the given identity
      Throws:
      IOException - if Isode specific identity could not be generated with the new passphrase
      Since:
      14.6
      See Also:

    • getIsodeX509IdentityFileName

      public String getIsodeX509IdentityFileName()
      Get the name of the Isode Specific Identity File Name that had been generated using the method generateIdentity(Identity, String).
      Returns:
      name of the generated X.509 Identity File, or null if there is none.
      Since:
      14.6

    • doesTrustCertificate

      public boolean doesTrustCertificate(SSLCertificate cert)
      Determine whether this BindProfile knows about (that is, it trusts) a particular certificate. This method does not perform full certificate validation, just checks to see whether the specified certificate is listed in the bind profile.
      Parameters:
      cert - the certificate to check
      Returns:
      true if the BindProfile trusts cert, or false if it doesn't.
      Since:
      14.6

    • getTrustedCerts

      public List<SSLCertificate> getTrustedCerts()
      Get the list of trusted certificates for this bind profile
      Returns:
      list of trusted certificates, not null but can be empty and the list will contain only non-null values
      Since:
      16.3

    • getTrustedCertsWithKeys

      public Map<String,SSLCertificate> getTrustedCertsWithKeys()
      Get the list of trusted certificates for this bind profile
      Returns:
      list of trusted certificates, not null but can be empty. It is possible to have null certificates for keys if the certificate is not found in the trust store
      Since:
      16.3

    • clearTrustedCerts

      public void clearTrustedCerts() throws IOException
      Remove all trusted certificates from bind profile
      Throws:
      IOException - if there was an error while initialising the trust store
      Since:
      16.3

    • addCertificateToBpTrustStore

      public String addCertificateToBpTrustStore(SSLCertificate cert) throws IOException
      Add the given certificate to trust store of the bind profile
      Parameters:
      cert - certificate to add, not null
      Returns:
      key with which the certificate is referred in bind profile, not null
      Throws:
      IOException - if there was an error writing certificate to trust store
      Since:
      16.3

    • removeTrustedCertFromBp

      public void removeTrustedCertFromBp(String key) throws IOException
      Remove trusted certificate from bind profile and trust store with the given key
      Parameters:
      key - key used for referring the trusted certificate, not null
      Throws:
      IOException - if there was an error in removing certificate from trust store
      Since:
      16.3

    • x509VerifyCertificate

      public VerifyResult x509VerifyCertificate(SSLCertificate certificate) throws CryptoException
      Call the X.509 library to perform certificate verification using parameters stored in this BindProfile.

      This method uses the CertificateVerifier class to verify the specified certificate, using

      • trustAnchors consisting of the trust anchors defined by the BindProfile's trustStore which the BindProfile trusts
      • otherCerts defined by the BindProfile's identity
      Additionally, should the relevant settings be present in the BindProfile, they will be used to specify an LDAP server that the certificate verification mechanism may use:
      • ldapHost
      • ldapPort
      • checkCRL
      Parameters:
      certificate - certificate to be verified
      Returns:
      a VerifyResult containing the result of the verification, (which the caller can look in to see whether verification worked)
      Throws:
      CryptoException - an error occurred when trying to perform verification
      Since:
      14.6

    • x509VerifyCertificate

      public VerifyResult x509VerifyCertificate(SSLCertificate certificate, List<SSLCertificate> trustAnchors, List<SSLCertificate> otherCerts) throws CryptoException
      Call the X.509 library to perform certificate verification with CRL checking using parameters stored in this BindProfile.

      This method uses the CertificateVerifier class to verify the specified certificate, using

      • trustAnchors
      • otherCerts
      Additionally, should the relevant settings be present in the BindProfile, they will be used to specify an LDAP server that the certificate verification mechanism may use:
      • ldapHost
      • ldapPort
      Parameters:
      certificate - certificate to be verified
      trustAnchors - trust anchors to be used for certificate verification, can be null
      otherCerts - other certificates to be used for certificate verification, can be null
      Returns:
      a VerifyResult containing the result of the verification, (which the caller can look in to see whether verification worked)
      Throws:
      CryptoException - an error occurred when trying to perform verification
      Since:
      16.3

    • getExtraXML

      public String getExtraXML()
      Return a String containing any "extra" XML (tags and contents) that were contained in this BindProfile's definition but were not recognised. This data will be re-written to the file if it is saved.
      Returns:
      a String containing all the XML which was not parsed, or null if there was none.
      Since:
      14.6
      See Also:

    • getIdentityPassphrase

      public String getIdentityPassphrase()
      Returns the passphrase used to decrypt the X.509 identity file associated with this BindProfile.
      Returns:
      p12 passphrase
      Since:
      14.6

    • setIdentityPassphrase

      public final void setIdentityPassphrase(String newPassphrase)
      Set the passphrase used to decrypt the X.509 identity file associated with this BindProfile.
      Parameters:
      newPassphrase - new passphrase
      Since:
      14.6
      See Also:

    • passwordDataRemoved

      public boolean passwordDataRemoved()
      Determine whether password data was removed from this object when it was loaded from a BindProfileList.

      When loading a BindProfileList in "readonly" mode (i.e. without specifying a passphrase), any passwords in the BindProfileList are ignored (because they cannot be decrypted) and the BindProfile objects will have null values. However, it may be useful for an application to know whether a password was present, because that would imply it would be worth re-loading the BindProfileList in read/write mode to obtain those passwords.

      Returns:
      true if this object was
      • loaded from a read-only BindProfileList, and
      • one or more (encrypted) passwords was removed when it was read
      false is returned in all other cases.
      Since:
      14.6

    • getKnownDsaPA

      public PresentationAddress getKnownDsaPA()
      Returns the known DSA presentation address associated with this BindProfile. This value will be null unless the BindProfile has an access point.
      Returns:
      known DSA presentation address, or null if there is none.
      Since:
      15.0

    • getKnownDsaDN

      public DN getKnownDsaDN()
      Returns the known DSA DN associated with this BindProfile. This value will be null unless the BindProfile has an access point.
      Returns:
      known DSA DN, or null if there is none.
      Since:
      15.0

    • getAP

      public AccessPoint getAP()
      Returns the access point associated with this BindProfile, if there is one.
      Returns:
      access point, or null if there is none.
      Since:
      15.0

    • isManaged

      public boolean isManaged()
      Returns the managed flag associated with this BindProfile.
      Returns:
      managed flag
      Since:
      15.0

    • isBindable

      public boolean isBindable()
      Returns whether this Bind Profile is bindable.
      Returns:
      bindable flag - TRUE if profile contains reliable bind profile address, FALSE otherwise
      Since:
      15.0

    • setKnownDsaDetails

      public void setKnownDsaDetails(AccessPoint ap, boolean managed) throws IllegalArgumentException
      Sets the known DSA details associated with this BindProfile.
      Parameters:
      ap - Access point, can be null
      managed - Managed flag
      Throws:
      IllegalArgumentException - if managed flag is true when access point is null.
      Since:
      15.0

    • setBindable

      public void setBindable(boolean canBind)
      Sets the bindable flag associated with this BindProfile.
      Parameters:
      canBind - Bindable flag
      Since:
      15.0

    • setDsadir

      public String setDsadir(String dsaDir)
      Sets the DSA directory associated with this BindProfile.
      Parameters:
      dsaDir - DSA directory (use null to mean no value)
      Returns:
      the previous setting (which may be null)
      Since:
      15.0

    • getDsadir

      public String getDsadir()
      Gets the DSA directory associated with this BindProfile.
      Returns:
      String representation of the DSA's directory, or null if no DSA directory has been set.
      Since:
      15.0

    • setServiceName

      public void setServiceName(String name)
      Sets the Windows service name or Solaris FMRI associated with this BindProfile.
      Parameters:
      name - Windows service name or Solaris FMRI (use null to mean not used on Windows or Solaris)
      Since:
      15.0

    • getServiceName

      public String getServiceName()
      Gets the Windows service name or Solaris FMRI associated with this BindProfile.
      Returns:
      String representation of the Windows service name or Solaris FMRI, or null if none has been set.
      Since:
      15.0

    • getPorts

      public Set<Integer> getPorts()
      Get the port numbers which appear to be referenced by the addresses in this BindProfile. The method returns port numbers that appear in either the BindProfileAddress or the Presentation Address (if they are non-null).

      Note that this method is "best efforts" - it may not always be possible to deduce all the port numbers from the address. Additionally, some types of BindProfile (e.g. "xmpp://...") don't have port numbers at all.

      The intention is that this method can be used as a way of suggesting to the user which port numbers may be in use already (e.g. "you appear to have a bind profile which uses port xxxx") rather than as a way of getting definitive information.

      Returns:
      a Set of Integers representing port numbers that are referenced by the addresses in this bind profile. This will be an empty set if no port numbers were found.
      Since:
      15.0

    • isManagedOnLocalSystem

      public boolean isManagedOnLocalSystem()
      Determine whether this BindProfile appears to be associated with a managed DSA on the local system.

      The return value of the method should be fairly reliable although it may not be correct if the user is using a bind profile file which has been copied from another system, or if he has edited the bind profile file, or if he has deleted the DSA's directory.

      Returns:
      true if this is a managed DSA that has a DSA directory which exists on this system, false otherwise.
      Since:
      15.0

    • getTag

      public String getTag()
      Get the XML tag which should be used when writing this Bind Profile to file.
      Returns:
      tag XML tag value which will not be null
      Since:
      15.2

    • setTag

      public void setTag(String tag)
      Set XML tag to be used when writing to disc.
      Parameters:
      tag - tag value to use which must not be null
      Since:
      15.2

    • isDsaBindProfile

      public boolean isDsaBindProfile()
      Test whether this is a DSA bind profile or not.
      Returns:
      true if this profile is one for a DSA, false otherwise
      Since:
      15.2

    • getUniqueIDIfSet

      public Optional<String> getUniqueIDIfSet()
      Gets the unique ID for the bind profile if it is set.
      Returns:
      If the unique ID is set for the bind profile, an Optional containing it, otherwise an empty Optional

    • getUniqueIDAndGenerate

      public String getUniqueIDAndGenerate()
      Gets the unique id for the bind profile if it is set, if it is not set generate one then returns that.
      Returns:
      The unique id for the bind profile.

    • isUniqueIDSet

      public boolean isUniqueIDSet()
      Indicates if a unique id is set for the bind profile
      Returns:
      true if a unique id is set for the bind profile, false otherwise.

    • uniqueIDEquals

      public boolean uniqueIDEquals(String id)
      Indicates if the bind profiles unique id is set to the given value.
      Parameters:
      id - The value to compare the bind profile's id to, if null result will be false.
      Returns:
      true if the unique id is set and equal to the given value, false otherwise.

    • hasUniqueIDSet

      public boolean hasUniqueIDSet()
      Indicates if the bind profile has a unique id set for it.
      Returns:
      true if the bind profile has a unique id set for it, false otherwise.

    • setUniqueID

      protected void setUniqueID(String value)
      Sets the unique id for the bind profile.
      Parameters:
      value - The value to set the unique id to. If null no id will be cleared.

    • copyUniqueID

      public void copyUniqueID(BindProfile bp)
      Copies the unique id from another bind profile. (any existing id for this bind profile will be overwritten)
      Parameters:
      bp - The bind profile to copy the id from, if null or if it does not have an unique id then the unique id for this bind profile will be cleared.
      Since:
      17.0

    • copyExtraXML

      public void copyExtraXML(BindProfile bp)
      Copies the the extra xml from another bind profile into this one (any extra xml for this bind profile will be overwritten).
      Parameters:
      bp - the BindProfile to copy the bind profile from.
      Since:
      17.0