Package com.isode.dsapi

Class SASLParameters

java.lang.Object
com.isode.dsapi.SASLParameters
Direct Known Subclasses:
SASLParametersProfile
public class SASLParameters extends 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)

  • Field Details

    • SASL_AUTHNAME

      public static final String SASL_AUTHNAME
      The callback parameter used to represent a username used for authentication.
      See Also:

    • SASL_SECRET

      public static final String SASL_SECRET
      The callback parameter used to represent a SASL secret.
      See Also:

    • SASL_REALM

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

    • SASL_OAUTHBEARER

      public static final String SASL_OAUTHBEARER
      The callback parameter used to get the OAuth2 access token
      Since:
      R20.0
      See Also:

    • BEST_SSF

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

    • mechanisms

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

    • properties

      protected HashMap<String,String> properties
      Properties for this SASLParams.

    • callbackParams

      protected HashMap<String,String> callbackParams
      Callback parameters for this SASLParams.

  • Constructor Details

    • SASLParameters

      public SASLParameters(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 Details

    • getMechanismsString

      public 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 EnumSet<SASLMechanism> getMechanismsSet()
      Returns set of mechanism names.
      Returns:
      set of mechanism names (not null)

    • setMechanisms

      public final void setMechanisms(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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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

      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:

    • getOAuth2RefreshToken

      public String getOAuth2RefreshToken()
      Get the refresh token
      Returns:
      the refresh token as a String or null
      See Also:

    • setOAuth2RefreshToken

      public void setOAuth2RefreshToken(String token)
      Set the refresh token
      Parameters:
      token - the refresh token as a String
      See Also:

    • getOAuth2ClientId

      public String getOAuth2ClientId()
      Get the OAuth2 client id
      Returns:
      the client id or null
      See Also:

    • setOAuth2ClientId

      public void setOAuth2ClientId(String clientId)
      Set the OAuth2 client id
      Parameters:
      clientId - the id as a String
      See Also:

    • deleteOAuth2ClientId

      public void deleteOAuth2ClientId()
      Delete the OAuth2 client id from the properties

    • getOAuth2ClientSecret

      public String getOAuth2ClientSecret()
      Get the OAuth2 client's secret
      Returns:
      the secret as a String

    • setOAuth2ClientSecret

      public void setOAuth2ClientSecret(String secret)
      Set the OAuth2 client's secret. Note that it is stored in the callbackParams to leverage encryption

    • deleteOAuth2ClientSecret

      public void deleteOAuth2ClientSecret()
      Delete the OAuth2 client secret

    • getOAuth2ClientRedirect

      public String getOAuth2ClientRedirect()
      Get OAuth2 client's redirect URI

    • setOAuth2ClientRedirect

      public void setOAuth2ClientRedirect(String uri)
      Set OAuth2 client's redirect URI

    • deleteOAuth2ClientRedirect

      public void deleteOAuth2ClientRedirect()
      Delete OAuth2 client's redirect URI

    • getOAuth2Server

      public String getOAuth2Server()
      Get OAuth2 server address

    • setOAuth2Server

      public void setOAuth2Server(String server)
      Set OAuth2 server's address

    • deleteOAuth2Server

      public void deleteOAuth2Server()
      Delete OAuth2 server address

    • getOAuth2AuthorizePort

      public String getOAuth2AuthorizePort()
      Get OAuth2 server's authorize port

    • setOAuth2AuthorizePort

      public void setOAuth2AuthorizePort(int port)
      Set OAuth2 server's authorize port

    • deleteOAuth2AuthorizePort

      public void deleteOAuth2AuthorizePort()
      Delete OAuth2 server's authorize port

    • getOAuth2TokenPort

      public String getOAuth2TokenPort()
      Get OAuth2 server's token port

    • setOAuth2TokenPort

      public void setOAuth2TokenPort(int port)
      Set OAuth2 server's token port

    • deleteOAuth2TokenPort

      public void deleteOAuth2TokenPort()
      Delete OAuth2 server's token port

    • 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:

    • 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:

    • setCallbackParameter

      public String setCallbackParameter(String parameterName, 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 String getCallbackParameter(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 String removeCallbackParameter(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 String toString()
      Return a string representation of this object.
      Overrides:
      toString in class Object
      Returns:
      a String representation of the object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object