Package com.isode.dsapi

Class SASLParameters

  • public class SASLParameters
extends java.lang.Object
    SASLParameters is a class which contains a collection of parameters that are used for a SASL bind. Specifically, the idea is that a SASLParameters object be instantiated and configured before using using as either a parameter to BindParams(SASLParameters) or BindParams.setSASL(SASLParameters).

    Depending on the SASL mechanism used, the properties and parameters for a SASL bind will vary.

    Since:
    16.1 (internal 14.6)

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  SASLParameters.SSF
      A convenience class for managing a min/max SSF (Security Strength Factor) pair.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int BEST_SSF
      The value that should be used to specify "best available" security strength factor.
      protected java.util.HashMap<java.lang.String,​java.lang.String> callbackParams
      Callback parameters for this SASLParams.
      protected java.util.EnumSet<SASLMechanism> mechanisms
      A set of SASL mechanisms.
      protected java.util.HashMap<java.lang.String,​java.lang.String> properties
      Properties for this SASLParams.
      static java.lang.String SASL_AUTHNAME
      The callback parameter used to represent a username used for authentication.
      static java.lang.String SASL_REALM
      The callback parameter used to represent a SASL realm.
      static java.lang.String SASL_SECRET
      The callback parameter used to represent a SASL secret.

    • Constructor Summary

      Constructors 
      Constructor Description
      SASLParameters​(SASLParameters other)
      Construct a new object by copying another (so that subsequent changes to the original object won't affect this one).
      SASLParameters​(java.lang.String mechanisms)
      Create a new SASLParameters object specifying nothing but one or more mechanism names.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean equals​(java.lang.Object obj)  
      SASLParameters.SSF getActualSSF()
      Determine the values that will be used for security strength factor on this system at this time.
      boolean getADCompatibility()
      Determine whether AD compatibility mode is enabled.
      java.lang.String getCallbackParameter​(java.lang.String parameterName)
      Get the value of a specific SASL callback parameter from this object.
      boolean getForwardSecrecy()
      Get the "Forward Secrecy" security flag.
      int getMaxBufferSize()
      Get the maximum buffer size used by the security layer.
      java.util.EnumSet<SASLMechanism> getMechanismsSet()
      Returns set of mechanism names.
      java.lang.String getMechanismsString()
      Return names of the SASL mechanisms.
      boolean getNoActive()
      Get the "No Active" security flag.
      boolean getNoAnonymous()
      Get the "No Anonymous" security flag.
      boolean getNoDictionary()
      Get the "No Dictionary" security flag.
      boolean getNoPlaintext()
      Get the "No Plaintext" security flag.
      boolean getPassCredentials()
      Get the "Pass Credentials" security flag.
      SASLParameters.SSF getSSF()
      Determine the security strength factor (SSF) values associated with this object.
      int hashCode()  
      java.lang.String removeCallbackParameter​(java.lang.String parameterName)
      Removes a specific callback parameter from this object.
      void setADCompatibility​(boolean enable)
      Set or clear "AD compatibility mode" for this this object.
      java.lang.String setCallbackParameter​(java.lang.String parameterName, java.lang.String parameterValue)
      Set a SASL callback parameter.
      void setForwardSecrecy​(boolean enable)
      Set the "Forward Secrecy" security flag.
      void setMaxBufferSize​(int size)
      Set the maximum buffer size used by the security layer.
      void setMechanisms​(java.lang.String mechanisms)
      Sets mechanisms.
      void setNoActive​(boolean enable)
      Set the "No Active" security flag.
      void setNoAnonymous​(boolean enable)
      Set the "No Anonymous" security flag.
      void setNoDictionary​(boolean enable)
      Set the "No Dictionary" security flag.
      void setNoPlaintext​(boolean enable)
      Set the "No Plaintext" security flag.
      void setPassCredentials​(boolean enable)
      Set the "Pass Credentials" security flag.
      void setSSF​(SASLParameters.SSF ssf)
      Specify or clear the Security Strength Factor (SSF) associated with this object.
      java.lang.String toString()
      Return a string representation of this object.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • SASL_AUTHNAME

        public static final java.lang.String SASL_AUTHNAME
        The callback parameter used to represent a username used for authentication.
        See Also:
        Constant Field Values

      • SASL_SECRET

        public static final java.lang.String SASL_SECRET
        The callback parameter used to represent a SASL secret.
        See Also:
        Constant Field Values

      • SASL_REALM

        public static final java.lang.String SASL_REALM
        The callback parameter used to represent a SASL realm.
        Since:
        R18.1
        See Also:
        Constant Field Values

      • BEST_SSF

        public static final int BEST_SSF
        The value that should be used to specify "best available" security strength factor.
        See Also:
        Constant Field Values

      • mechanisms

        protected java.util.EnumSet<SASLMechanism> mechanisms
        A set of SASL mechanisms. At least one mechanism is always required.

      • properties

        protected java.util.HashMap<java.lang.String,​java.lang.String> properties
        Properties for this SASLParams.

      • callbackParams

        protected java.util.HashMap<java.lang.String,​java.lang.String> callbackParams
        Callback parameters for this SASLParams.

    • Constructor Detail

      • SASLParameters

        public SASLParameters​(java.lang.String mechanisms)
        Create a new SASLParameters object specifying nothing but one or more mechanism names.
        Parameters:
        mechanisms - must not be null and contain at least one proper mechanism name. If more than one mechanism is specified, the names should be space separated, e.g. "GSSAPI NTLM".

      • SASLParameters

        public SASLParameters​(SASLParameters other)
        Construct a new object by copying another (so that subsequent changes to the original object won't affect this one).
        Parameters:
        other - another SASLParameters object (not null)

    • Method Detail

      • getMechanismsString

        public java.lang.String getMechanismsString()
        Return names of the SASL mechanisms. This will never be null. If more than one mechanism is specified, the String will contain the name of each mechanism, separated by spaces.
        Returns:
        the SASL mechanisms (not null)

      • getMechanismsSet

        public java.util.EnumSet<SASLMechanism> getMechanismsSet()
        Returns set of mechanism names.
        Returns:
        set of mechanism names (not null)

      • setMechanisms

        public final void setMechanisms​(java.lang.String mechanisms)
        Sets mechanisms.
        Parameters:
        mechanisms - must not be null and contain at least one proper mechanism name. If more than one mechanism is specified, the names should be space separated, e.g. "GSSAPI NTLM".

      • setSSF

        public void setSSF​(SASLParameters.SSF ssf)
        Specify or clear the Security Strength Factor (SSF) associated with this object.

        Note that this sets the "requested" SSF values; that is, the values which will be requested when a SASL bind is attempted. The "actual" SSF values used may be different (and may vary from system to system).

        Parameters:
        ssf - the requested min/max security strength factor
        See Also:
        getSSF(), getActualSSF()

      • setMaxBufferSize

        public void setMaxBufferSize​(int size)
        Set the maximum buffer size used by the security layer.
        Parameters:
        size - the requested size, or -1 to use a default size. Using 0 will disable the security layer.
        Since:
        16.1 (internal 15.2)

      • getMaxBufferSize

        public int getMaxBufferSize()
        Get the maximum buffer size used by the security layer.
        Returns:
        the size
        Since:
        16.1 (internal 15.2)
        See Also:
        setMaxBufferSize(int)

      • setNoPlaintext

        public void setNoPlaintext​(boolean enable)
        Set the "No Plaintext" security flag. This will prevent SASL binds from using plaintext-based mechanisms.

        The PLAIN and LOGIN mechanisms are plaintext.

        Parameters:
        enable - true to prevent plaintext mechanisms, false to allow them.
        Since:
        16.1 (internal 15.2)

      • getNoPlaintext

        public boolean getNoPlaintext()
        Get the "No Plaintext" security flag.
        Returns:
        true if plaintext mechanisms are prevented, false if they are allowed.
        Since:
        16.1 (internal 15.2)
        See Also:
        setNoPlaintext(boolean)

      • setNoActive

        public void setNoActive​(boolean enable)
        Set the "No Active" security flag. This will prevent SASL binds from using mechanisms that do not protect against active (i.e. non-dictionary) attacks.

        The GSSAPI and SCRAM mechanisms protect against active attacks.

        Parameters:
        enable - true to require mechanisms that protect against active attacks, false to allow ones that don't.
        Since:
        16.1 (internal 15.2)

      • getNoActive

        public boolean getNoActive()
        Get the "No Active" security flag.
        Returns:
        true if mechanisms protecting against active attacks are required, false if ones that don't are allowed.
        Since:
        16.1 (internal 15.2)
        See Also:
        setNoActive(boolean)

      • setNoDictionary

        public void setNoDictionary​(boolean enable)
        Set the "No Dictionary" security flag. This will prevent SASL binds from using mechanisms that do not protect against passive (i.e. dictionary) attacks.

        The SRP mechanism protects against dictionary attacks.

        Parameters:
        enable - true to require mechanisms that protect against dictionary attacks, false to allow ones that don't.
        Since:
        16.1 (internal 15.2)

      • getNoDictionary

        public boolean getNoDictionary()
        Get the "No Dictionary" security flag.
        Returns:
        true if mechanisms protecting against dictionary attacks are required, false if ones that don't are allowed.
        Since:
        16.1 (internal 15.2)
        See Also:
        setNoDictionary(boolean)

      • setForwardSecrecy

        public void setForwardSecrecy​(boolean enable)
        Set the "Forward Secrecy" security flag. This will prevent SASL binds from using mechanisms that do not protect against secrecy breakage affecting future (i.e. "forward") sessions.

        The OTP and SRP mechanisms provide forward secrecy protection.

        Parameters:
        enable - true to require mechanisms that provide forward secrecy, false to allow ones that don't.
        Since:
        16.1 (internal 15.2)

      • getForwardSecrecy

        public boolean getForwardSecrecy()
        Get the "Forward Secrecy" security flag.
        Returns:
        true if mechanisms providing forward secrecy protection are required, and false to allow ones that don't.
        Since:
        16.1 (internal 15.2)
        See Also:
        setForwardSecrecy(boolean)

      • setNoAnonymous

        public void setNoAnonymous​(boolean enable)
        Set the "No Anonymous" security flag. This will prevent SASL binds from using mechanisms that only give anonymous authentication.

        The ANONYMOUS mechanism provides anonymous authentication.

        Parameters:
        enable - true to prevent mechanisms that provide anonymous authentication, false to allow ones that do.
        Since:
        16.1 (internal 15.2)

      • getNoAnonymous

        public boolean getNoAnonymous()
        Get the "No Anonymous" security flag.
        Returns:
        true if mechanisms providing anonymous authentication are prevented, and false to allow anonymous mechanisms.
        Since:
        16.1 (internal 15.2)
        See Also:
        setNoAnonymous(boolean)

      • setPassCredentials

        public void setPassCredentials​(boolean enable)
        Set the "Pass Credentials" security flag. This will prevent SASL binds from using mechanisms that can impersonate the user when talking to other services.

        The LOGIN, PLAIN and GSSAPI mechanisms pass credentials.

        Parameters:
        enable - true if mechanisms passing credentials are required, and false if other mechanisms are allowed.
        Since:
        16.1 (internal 15.2)

      • getPassCredentials

        public boolean getPassCredentials()
        Get the "Pass Credentials" security flag.
        Returns:
        true if mechanisms passing credentials are required and false to if other mechanisms are allowed.
        Since:
        16.1 (internal 15.2)
        See Also:
        setPassCredentials(boolean)

      • setADCompatibility

        public void setADCompatibility​(boolean enable)
        Set or clear "AD compatibility mode" for this this object.

        RFC 4752 Section 3.3 defines three bits that determine the level of security used for GSSAPI binds:

        • No security layer (bit value 1)
        • Integrity protection (bit value 2)
        • Confidentiality protection (bit value 4)

        The GSS-API requires that integrity protection be provided when confidentiality is requested, and so the default behaviour of the GSSAPI library when requesting confidentiality is that only the "confidentiality" bit is set.

        However, Active Directory requires that when confidentiality is requested, the "integrity" option must be specified as well, and so requests where only the confidentiality bit is set may be rejected.

        Callers may therefore use the "Active Directory compatibility" setting which will set values which accord with Active Directory's requirements.

        Note that some servers may reject a bind from a client which uses both integrity and confidentiality in this way, which means that the "Active Directory compatibility" mode may cause connections to fail (i.e. it may not always be appropriate to enable this option).

        This flag has no effect for SASL binds which are not using GSSAPI.

        Parameters:
        enable - true to enable Active Directory compatibility mode, false to disable it
        See Also:
        getADCompatibility()

      • getADCompatibility

        public boolean getADCompatibility()
        Determine whether AD compatibility mode is enabled.
        Returns:
        true if AD compatibility mode is enabled, false if it isn't
        See Also:
        setADCompatibility(boolean)

      • getSSF

        public SASLParameters.SSF getSSF()
        Determine the security strength factor (SSF) values associated with this object.

        Note that the actual SSF used at bind time may be different; see getActualSSF().

        Returns:
        the requested security strength factor.
        See Also:
        setSSF(SSF), getActualSSF()

      • getActualSSF

        public SASLParameters.SSF getActualSSF()
                                throws NotImplementedException
        Determine the values that will be used for security strength factor on this system at this time. These values may differ from those requested, depending on constraints such as license.

        This method can be used to determine which of the three following cases applies:

        1. The specified SSF can be used on this system
        2. A specified SSF of BEST_SSF is limited by license restrictions, etc.
        3. The specified SSF cannot be provided on this system

        For example 

             SSF requested = new SSF(-1, SASLParameters.BEST_SSF);
     sp.setSSF(requested);
     try {
         SSF actual = sp.getSSF();
         if (actual.equals(requested)) {
             System.out.println("got what I wanted"); // case 1
         }
         else {
             System.out.println("Asked for " + requested " +
             "but got " + actual); // case 2
         }
     }
     catch (NotImplementedException e) {
         System.out.println("Current configuration does not permit " +
         requested); // case 3
     }
        Returns:
        the security strength factors that will be used on this system.
        Throws:
        NotImplementedException - if the values requested are not allowed (e.g. because the license prohibits it).
        See Also:
        setSSF(SSF), getSSF()

      • setCallbackParameter

        public java.lang.String setCallbackParameter​(java.lang.String parameterName,
                                             java.lang.String parameterValue)
        Set a SASL callback parameter. Any existing parameter of the same name will be replaced, and its value returned to the caller (in case he's interested).

        SASL callback parameters are stored in encrypted form in the BindProfile file.

        Note that to remove a callback parameter, use removeCallbackParameter(String) (setting the value to null is not quite the same).

        Parameters:
        parameterName - name of SASL property; mechanism dependent
        parameterValue - value of SASL property
        Returns:
        the previous value of this property, or null if it was not previously set.

      • getCallbackParameter

        public java.lang.String getCallbackParameter​(java.lang.String parameterName)
        Get the value of a specific SASL callback parameter from this object.
        Parameters:
        parameterName - the parameter name
        Returns:
        the parameter value, or null if no such parameter is present

      • removeCallbackParameter

        public java.lang.String removeCallbackParameter​(java.lang.String parameterName)
        Removes a specific callback parameter from this object.
        Parameters:
        parameterName - the parameter name
        Returns:
        the previous value of this property, or null if it was not previously set.

      • toString

        public java.lang.String toString()
        Return a string representation of this object.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a String representation of the object

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object