Package org.jivesoftware.openfire.net

Class SASLAuthentication

java.lang.Object
org.jivesoftware.openfire.net.SASLAuthentication
public class SASLAuthentication extends Object
SASLAuthentication is responsible for returning the available SASL mechanisms to use and for actually performing the SASL authentication.

The list of available SASL mechanisms is determined by:

  1. The type of UserProvider being used since some SASL mechanisms require the server to be able to retrieve user passwords
  2. Whether anonymous logins are enabled or not.
  3. Whether shared secret authentication is enabled or not.
  4. Whether the underlying connection has been secured or not.
Author:
Hao Chen, Gaston Dombiak

  • Field Details

    • REALM

      public static final SystemProperty<String> REALM

    • APPROVED_REALMS

      public static final SystemProperty<List<String>> APPROVED_REALMS

    • PROXY_AUTH

      public static final SystemProperty<Boolean> PROXY_AUTH

    • SKIP_PEER_CERT_REVALIDATION_CLIENT

      public static final SystemProperty<Boolean> SKIP_PEER_CERT_REVALIDATION_CLIENT
      Consumed by SaslMechanismEligibility, which decides whether the SASL EXTERNAL mechanism can be offered to a client session. The property is declared here because SystemProperty registers by key in a global registry, so it cannot be moved without changing when that registration happens.

    • SSDP_ENABLED

      public static final SystemProperty<Boolean> SSDP_ENABLED
      Controls if the SASL SCRAM Downgrade Protection feature, as specified in XEP-0474, is enabled. When enabled, Openfire will add a hash value to the optional h attribute of server-first-message that is sent to peers when they perform SCRAM-based authentication. This can help them prevent downgrade attacks.

    • EXTERNAL_S2S_REQUIRE_AUTHZID

      public static final SystemProperty<Boolean> EXTERNAL_S2S_REQUIRE_AUTHZID
      Require the peer to provide an authorization identity through SASL (typically in the Initial Response) when authenticating an inbound S2S connection that uses the EXTERNAL SASL mechanism. This is not required by the XMPP protocol specification, but it was required by Openfire versions prior to release 4.8.0. This configuration option is added to allow for backwards compatibility.

    • EXTERNAL_S2S_SKIP_SENDING_AUTHZID

      public static final SystemProperty<Boolean> EXTERNAL_S2S_SKIP_SENDING_AUTHZID
      Send an authorization identity in the Initial Response when attempting to authenticate using the SASL EXTERNAL mechanism with a remote XMPP domain. Sending the authzid in this manner is not required by the XMPP protocol specification, but is recommended in XEP-0178 for compatibility with older server implementations.
      See Also:

    • ENABLE_SASL2

      public static final SystemProperty<Boolean> ENABLE_SASL2
      Enable (or disable) SASL2. This is currently off by default, and means that SASL2 is not advertised in features, primarily.
      See Also:

    • SASL2_REQUIRE_TLS

      public static final SystemProperty<Boolean> SASL2_REQUIRE_TLS
      Require TLS for SASL2. This is currently on by default, and means that SASL2 is not advertised in features without TLS. This setting also governs the no-channel-binding FAST mechanisms (HT-*-NONE and HT2-*-NONE). Disabling it allows those mechanisms on a connection that Openfire does not identify as TLS-encrypted. This is intended only for deployments in which another layer provides equivalent transport security, such as a trusted encrypted network where TLS termination or use by Openfire is undesirable. Channel-binding FAST variants continue to require TLS and their corresponding channel-binding data. Administrators that disable this safeguard are responsible for preventing observation and replay of FAST authentication traffic.
      See Also:

    • SASL_NAMESPACE

      public static final String SASL_NAMESPACE
      See Also:

    • SASL2_NAMESPACE

      public static final String SASL2_NAMESPACE
      See Also:

    • SASL_CHANNEL_BINDING_NAMESPACE

      public static final String SASL_CHANNEL_BINDING_NAMESPACE
      See Also:

    • SASL_LAST_RESPONSE_WAS_PROVIDED_BUT_EMPTY

      public static final String SASL_LAST_RESPONSE_WAS_PROVIDED_BUT_EMPTY
      Java's SaslServer does not allow for null values. This makes it hard to distinguish between an empty (initial) responses (represented in XMPP as a single equals sign character '=', as per RFC-6120 section 6.4.2), and a missing/absent response. This can be problematic when a SASL mechanism implementation is to act differently on each scenario (like the EXTERNAL mechanism, that is to challenge for an authzid when no initial response is provided, but which is to use the stream's 'from' attribute value when the initial response is empty). To work around this shortcoming in Java's SASL implementation, this class will add a session attribute using a key that has the name of this constant's value when it detects a Sasl response that is present, but empty.
      See Also:

    • AVAILABLE_MECHANISMS_FOR_SESSION

      public static final String AVAILABLE_MECHANISMS_FOR_SESSION
      Session Data property name used to store which SASL mechanisms were advertised by the server to the peer as being available for the session that is performing SASL authentication. The value is expected to be a Set of Strings, if any mechanisms were advertised from Openfire to the peer. Instead of using this value directly, consider using SaslMechanismEligibility.getAdvertisableSASLMechanisms(LocalSession), setAdvertisedSASLMechanisms(LocalSession, Set), or getAdvertisedSASLMechanisms(LocalSession) which encapsulate the business-logic related to this constant.
      See Also:

    • AVAILABLE_CHANNEL_BINDING_TYPES_FOR_SESSION

      public static final String AVAILABLE_CHANNEL_BINDING_TYPES_FOR_SESSION
      Session Data property name used to store which channel bindings were advertised by the server to the peer as being available for the session that is performing SASL authentication. The value is expected to be a Set of Strings, if any bindings were advertised from Openfire to the peer. Instead of using this value directly, consider using getAdvertisedChannelBindingTypes(LocalSession) or setAdvertisedChannelBindingTypes(LocalSession, Set) which encapsulate the business-logic related to this constant.
      See Also:

    • SASL2_RESUMED_SESSION

      public static final String SASL2_RESUMED_SESSION
      Session Data property name used, on the temporary session that is negotiating a SASL2 authentication, to hand off the pre-existing session that was resumed inline (XEP-0198 § 9.2) to the caller of handle(LocalSession, Element, boolean). The resumed session itself cannot be represented in SASLAuthentication.Status, so this session data, together with SASLAuthentication.Status.authenticatedResumed, is used instead to communicate the outcome. A caller (typically StanzaHandler) is expected to switch to using the referenced session, and to remove this session data.
      See Also:

    • SCRAM_MECHANISMS_PER_USER

      public static final SystemProperty<Boolean> SCRAM_MECHANISMS_PER_USER
      Controls whether the SCRAM mechanisms that are advertised to a client are tailored to the user that is expected to authenticate. When enabled, the identity that a client claims in the 'from' attribute of its stream header is used to look up which SCRAM mechanisms that user has credentials for, so that no mechanism is offered that cannot succeed. When disabled, every session is offered the mechanisms that any user can be assumed to hold, and no per-user lookup is performed. This removes both the (small) signal that the tailored response gives an unauthenticated peer about which users exist, and the credential lookup that such a peer can otherwise trigger. The cost is that a user holding credentials for a stronger mechanism is not offered it unless every user holds it. Consumed by SaslMechanismEligibility. The property is declared here because SystemProperty registers by key in a global registry, so it cannot be moved without changing when that registration happens.

  • Constructor Details

    • SASLAuthentication

      public SASLAuthentication()

  • Method Details

    • setAdvertisedSASLMechanisms

      public static void setAdvertisedSASLMechanisms(@Nonnull LocalSession session, Set<String> advertisedMechanisms)
      Records a set of SASL mechanism names as having been advertised for/to the given session. Some SASL mechanism implementations depend on this information. Notably, the SASL-SCRAM-SHA* mechanisms depend on it to detect channel binding downgrades. Implementations of LocalSession should call this method when SASL mechanisms are advertised to a session.
      Parameters:
      session - the session for which to record advertised SASL mechanisms (cannot be null).
      advertisedMechanisms - the advertised SASL mechanism names

    • getAdvertisedSASLMechanisms

      public static Optional<Set<String>> getAdvertisedSASLMechanisms(@Nonnull LocalSession session)
      Returns the set of SASL mechanism names that has previously been advertised for/to the given session as being available for use for that session. When advertisement has not (yet) happened when this method is invoked, an empty Optional is returned.
      Parameters:
      session - the session for which to obtain SASL mechanism names (cannot be null).
      Returns:
      a set of mechanism names that have been advertised for/to the session.

    • setAdvertisedChannelBindingTypes

      public static void setAdvertisedChannelBindingTypes(@Nonnull LocalSession session, Set<String> advertisedChannelBindingTypes)
      Records a set of channel binding types as having been advertised for/to the given session. Some SASL mechanism implementations depend on this information. Notably, the SASL-SCRAM-SHA* mechanisms depend on it to detect channel binding downgrades. Implementations of LocalSession should call this method when channel bindings are advertised to a session.
      Parameters:
      session - the session for which to record advertised channel bindings (cannot be null).
      advertisedChannelBindingTypes - the advertised channel binding types

    • getAdvertisedChannelBindingTypes

      public static Optional<Set<String>> getAdvertisedChannelBindingTypes(@Nonnull LocalSession session)
      Returns the set of channel binding types that has previously been advertised for/to the given session as being available for use for that session. When advertisement has not (yet) happened when this method is invoked, an empty Optional is returned.
      Parameters:
      session - the session for which to obtain channel binding types (cannot be null).
      Returns:
      a set of channel binding types that have been advertised for/to the session.

    • handle

      public static SASLAuthentication.Status handle(LocalSession session, org.dom4j.Element doc, boolean usingSASL2)
      Handles the SASL authentication packet. The entity may be sending an initial authentication request or a response to a challenge made by the server. The returned value indicates whether the authentication has finished either successfully or not or if the entity is expected to send a response to a challenge.
      Parameters:
      session - the session that is authenticating with the server.
      doc - the stanza sent by the authenticating entity.
      usingSASL2 - true if the authentication is being performed using SASL2 (XEP-0388); false if using standard SASL (RFC 6120)
      Returns:
      value that indicates whether the authentication has finished either successfully or not or if the entity is expected to send a response to a challenge.

    • verifyCertificate

      @Deprecated(forRemoval=true, since="5.2.0") public static boolean verifyCertificate(X509Certificate trustedCert, String hostname)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Moved to CertificateManager.verifyCertificate(X509Certificate, String)
      Verifies that the given X.509 certificate is valid for the specified hostname. The certificate's server identities are checked against the hostname, with support for wildcard certificates. A wildcard identity (e.g. *.example.com) matches any direct subdomain of the base domain.
      Parameters:
      trustedCert - the X.509 certificate to verify (cannot be null)
      hostname - the hostname to verify the certificate against (cannot be null)
      Returns:
      true if the certificate is valid for the given hostname; false otherwise

    • verifyCertificates

      @Deprecated(forRemoval=true, since="5.2.0") public static boolean verifyCertificates(Certificate[] chain, String hostname, boolean isS2S)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Moved to CertificateManager.verifyCertificates(Certificate[], String, boolean)
      Verifies that the end-entity certificate in the given certificate chain is trusted and valid for the specified hostname. The appropriate trust store is selected based on whether this is a server-to-server (S2S) or client-to-server (C2S) connection.
      Parameters:
      chain - the certificate chain to verify; the end-entity certificate will be extracted and checked against the trust store (may be null or empty, in which case verification will fail)
      hostname - the hostname that the certificate must be valid for (cannot be null)
      isS2S - true if this is a server-to-server connection (uses the S2S trust store); false if this is a client-to-server connection (uses the C2S trust store)
      Returns:
      true if a trusted end-entity certificate is found in the chain and it is valid for the given hostname; false otherwise

    • addSupportedMechanism

      @Deprecated(forRemoval=true, since="5.2.0") public static void addSupportedMechanism(String mechanismName)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Moved to SaslMechanismCatalog.addSupportedMechanism(String)
      Adds a new SASL mechanism to the list of supported SASL mechanisms by the server. The new mechanism will be offered to clients and connection managers as stream features.

      Note: this method simply registers the SASL mechanism to be advertised as a supported mechanism by Openfire. Actual SASL handling is done by Java itself, so you must add the provider to Java.

      Parameters:
      mechanismName - the name of the new SASL mechanism (cannot be null or an empty String).

    • removeSupportedMechanism

      @Deprecated(forRemoval=true, since="5.2.0") public static void removeSupportedMechanism(String mechanismName)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Moved to SaslMechanismCatalog.removeSupportedMechanism(String)
      Removes a SASL mechanism from the list of supported SASL mechanisms by the server.
      Parameters:
      mechanismName - the name of the SASL mechanism to remove (cannot be null or empty, not case-sensitive).

    • getSupportedMechanisms

      @Deprecated(forRemoval=true, since="5.2.0") public static Set<String> getSupportedMechanisms()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Moved to SaslMechanismCatalog.getSupportedMechanisms()
      Returns the list of supported SASL mechanisms by the server. Note that Java may have support for more mechanisms but some of them may not be returned since a special setup is required that might be missing. Use SaslMechanismCatalog.addSupportedMechanism(String) to add new SASL mechanisms.
      Returns:
      the set of supported SASL mechanisms by the server.

    • getImplementedMechanisms

      @Deprecated(forRemoval=true, since="5.2.0") public static Set<String> getImplementedMechanisms()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Moved to SaslMechanismCatalog.getImplementedMechanisms()
      Returns a collection of mechanism names for which the JVM has an implementation available.

      Note that this need not (and likely will not) correspond with the list of mechanisms that is offered to XMPP peer entities, which is provided by #getSupportedMechanisms.

      Returns:
      a collection of SASL mechanism names (never null, possibly empty)

    • getEnabledMechanisms

      @Deprecated(forRemoval=true, since="5.2.0") public static List<String> getEnabledMechanisms()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Moved to SaslMechanismCatalog.getEnabledMechanisms()
      Returns a collection of SASL mechanism names that forms the source pool from which the mechanisms that are eventually being offered to peers are obtained. When a mechanism is not returned by this method, it will never be offered, but when a mechanism is returned by this method, there is no guarantee that it will be offered. Apart from being returned in this method, an implementation must be available (see SaslMechanismCatalog.getImplementedMechanisms() and configuration or other characteristics of this server must not prevent a particular mechanism from being used (see @{link SaslMechanismCatalog.getSupportedMechanisms()}.
      Returns:
      A collection of mechanisms that are considered for use in this instance of Openfire.

    • setEnabledMechanisms

      @Deprecated(forRemoval=true, since="5.2.0") public static void setEnabledMechanisms(List<String> mechanisms)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Moved to SaslMechanismCatalog.setEnabledMechanisms(List)
      Sets the collection of mechanism names that the system administrator allows to be used.
      Parameters:
      mechanisms - A collection of mechanisms that are considered for use in this instance of Openfire. Null to reset the default setting.
      See Also: