Package org.jivesoftware.openfire.fast

Class FastTokenManager

java.lang.Object
org.jivesoftware.openfire.fast.FastTokenManager
public class FastTokenManager extends Object
Manages FAST (XEP-0484) authentication tokens. Tokens are stored per user, client and mechanism in current/new slots. The recoverable token string is required to verify the initiator HMAC and produce the responder HMAC.

  • Field Details

    • NAMESPACE

      public static final String NAMESPACE
      XEP-0484 namespace
      See Also:

    • HT_SHA_256_NONE

      public static final String HT_SHA_256_NONE
      HT-SHA-256-NONE: original HT draft, SHA-256, no channel binding.
      See Also:

    • HT_SHA_256_UNIQ

      public static final String HT_SHA_256_UNIQ
      HT-SHA-256-UNIQ: original HT draft, SHA-256, tls-unique channel binding.
      See Also:

    • HT_SHA_256_ENDP

      public static final String HT_SHA_256_ENDP
      HT-SHA-256-ENDP: original HT draft, SHA-256, tls-server-end-point channel binding.
      See Also:

    • HT_SHA_256_EXPR

      public static final String HT_SHA_256_EXPR
      HT-SHA-256-EXPR: original HT draft, SHA-256, tls-exporter channel binding.
      See Also:

    • HT_SHA_512_NONE

      public static final String HT_SHA_512_NONE
      HT-SHA-512-NONE: original HT draft, SHA-512, no channel binding.
      See Also:

    • HT_SHA_512_UNIQ

      public static final String HT_SHA_512_UNIQ
      HT-SHA-512-UNIQ: original HT draft, SHA-512, tls-unique channel binding.
      See Also:

    • HT_SHA_512_ENDP

      public static final String HT_SHA_512_ENDP
      HT-SHA-512-ENDP: original HT draft, SHA-512, tls-server-end-point channel binding.
      See Also:

    • HT_SHA_512_EXPR

      public static final String HT_SHA_512_EXPR
      HT-SHA-512-EXPR: original HT draft, SHA-512, tls-exporter channel binding.
      See Also:

    • HT_SHA3_512_NONE

      public static final String HT_SHA3_512_NONE
      See Also:

    • HT_SHA3_512_UNIQ

      public static final String HT_SHA3_512_UNIQ
      See Also:

    • HT_SHA3_512_ENDP

      public static final String HT_SHA3_512_ENDP
      See Also:

    • HT_SHA3_512_EXPR

      public static final String HT_SHA3_512_EXPR
      See Also:

    • HT2_SHA_256_NONE

      public static final String HT2_SHA_256_NONE
      HT2-SHA-256-NONE: HT2 draft, SHA-256, no channel binding.
      See Also:

    • HT2_SHA_256_UNIQ

      public static final String HT2_SHA_256_UNIQ
      HT2-SHA-256-UNIQ: HT2 draft, SHA-256, tls-unique channel binding.
      See Also:

    • HT2_SHA_256_ENDP

      public static final String HT2_SHA_256_ENDP
      HT2-SHA-256-ENDP: HT2 draft, SHA-256, tls-server-end-point channel binding.
      See Also:

    • HT2_SHA_256_EXPR

      public static final String HT2_SHA_256_EXPR
      HT2-SHA-256-EXPR: HT2 draft, SHA-256, tls-exporter channel binding.
      See Also:

    • HT2_SHA_512_NONE

      public static final String HT2_SHA_512_NONE
      HT2-SHA-512-NONE: HT2 draft, SHA-512, no channel binding.
      See Also:

    • HT2_SHA_512_UNIQ

      public static final String HT2_SHA_512_UNIQ
      HT2-SHA-512-UNIQ: HT2 draft, SHA-512, tls-unique channel binding.
      See Also:

    • HT2_SHA_512_ENDP

      public static final String HT2_SHA_512_ENDP
      HT2-SHA-512-ENDP: HT2 draft, SHA-512, tls-server-end-point channel binding.
      See Also:

    • HT2_SHA_512_EXPR

      public static final String HT2_SHA_512_EXPR
      HT2-SHA-512-EXPR: HT2 draft, SHA-512, tls-exporter channel binding.
      See Also:

    • HT2_SHA3_512_NONE

      public static final String HT2_SHA3_512_NONE
      See Also:

    • HT2_SHA3_512_UNIQ

      public static final String HT2_SHA3_512_UNIQ
      See Also:

    • HT2_SHA3_512_ENDP

      public static final String HT2_SHA3_512_ENDP
      See Also:

    • HT2_SHA3_512_EXPR

      public static final String HT2_SHA3_512_EXPR
      See Also:

    • ENABLE_FAST

      public static final SystemProperty<Boolean> ENABLE_FAST
      Enables FAST (XEP-0484), which lets clients re-authenticate with a long-lived token instead of their password.

    • TOKEN_EXPIRY

      public static final SystemProperty<Duration> TOKEN_EXPIRY
      How long an issued FAST token remains valid. This is the window in which a leaked token, or a token belonging to a password changed outside Openfire (as with LDAP), can still be used to authenticate - lower values shorten that exposure at the cost of more frequent full re-authentication.

    • TOKEN_ROTATION_THRESHOLD

      public static final SystemProperty<Duration> TOKEN_ROTATION_THRESHOLD
      How close to expiry a token must be before a successful authentication issues a replacement. It must be comfortably longer than the longest interval at which a client is expected to reconnect, or clients will find their token expired and have to re-authenticate with a password.

    • MECHANISMS

      public static final List<String> MECHANISMS

  • Method Details

    • featureElement

      public static org.dom4j.Element featureElement()
      Returns an XML element advertising FAST as an inline feature for use in SASL2 (XEP-0388) inline feature advertisement.
      Returns:
      a <fast/> element in the NAMESPACE namespace

    • featureElement

      public static org.dom4j.Element featureElement(@Nonnull Collection<String> mechanisms)

    • isMechanism

      public static boolean isMechanism(@Nonnull String mechanism)

    • hashAlgorithmForMechanism

      public static String hashAlgorithmForMechanism(@Nonnull String mechanism)
      Extracts the JCA hash algorithm name from a mechanism name of the form HT-SHA-256-NONE, HT2-SHA-512-UNIQ, etc.

      The second segment (between the first and second -) is the hash family (e.g. SHA) and the third segment is the bit length (e.g. 256), giving a JCA name of SHA-256 or SHA-512.

      Parameters:
      mechanism - the FAST SASL mechanism name (cannot be null)
      Returns:
      the JCA algorithm name, e.g. "SHA-256" or "SHA-512"
      Throws:
      IllegalArgumentException - if the mechanism name does not follow the expected pattern

    • hmacAlgorithmForMechanism

      public static String hmacAlgorithmForMechanism(@Nonnull String mechanism)
      Returns the JCA HMAC algorithm name corresponding to the hash used by the given mechanism. For example, "SHA-256" maps to "HmacSHA256", "SHA-512" to "HmacSHA512".
      Parameters:
      mechanism - the FAST SASL mechanism name (cannot be null)
      Returns:
      the JCA HMAC algorithm name

    • issueToken

      @Nonnull public static FastToken issueToken(@Nonnull String username, @Nonnull String clientId, @Nonnull String mechanism)
      Issues a new FAST token for the given username, client identifier and mechanism, storing it in the database. Any unacknowledged new token for the same user, mechanism and client is replaced. The current token remains valid until the client proves possession of this new token. The generated token is a Base64 Unicode string. Its UTF-8 representation is persisted so that both HT families can verify and produce their mutual-authentication HMACs.
      Parameters:
      username - the local username (cannot be null)
      clientId - the client identifier (cannot be null)
      mechanism - the FAST SASL mechanism name (cannot be null)
      Returns:
      the newly issued FastToken containing the UTF-8 token bytes and expiry

    • validateTokenHt2

      public static FastTokenManager.Ht2ValidationResult validateTokenHt2(@Nonnull String username, @Nonnull String clientId, @Nonnull String mechanism, @Nonnull byte[] initiatorHashedToken, @Nonnull byte[] cbData, @Nonnull String extraInitiatorValues, @Nonnull String extraResponderValues)
      Validates an HT2 FAST token presented by a client using HMAC verification (draft-ietf-kitten-sasl-ht). The client sends HMAC(token, "Initiator" || cbData || extraValues) as the initiator-hashed-token. This method fetches the stored UTF-8 token bytes from the database and recomputes the expected HMAC for comparison. If the new token is valid, it is promoted to current. If a current token is nearing expiry, a replacement is issued into the new slot. The optional replacement is returned together with the responder HMAC. If validation fails, null is returned.
      Parameters:
      username - the local username (cannot be null)
      mechanism - the FAST SASL mechanism name, must start with "HT2-" (cannot be null)
      initiatorHashedToken - the HMAC bytes presented by the client (cannot be null)
      cbData - the channel-binding data; empty byte array for NONE variant (cannot be null)
      extraInitiatorValues - the extra initiator key/value pairs string; empty string if none (cannot be null)
      extraResponderValues - the extra responder key/value pairs string; empty string if none (cannot be null)
      Returns:
      a FastTokenManager.Ht2ValidationResult on success, or null on failure

    • validateTokenHt2

      public static FastTokenManager.Ht2ValidationResult validateTokenHt2(@Nonnull String username, @Nonnull String clientId, @Nonnull String mechanism, @Nonnull byte[] initiatorHashedToken, @Nonnull byte[] cbData, @Nonnull String extraInitiatorValues, @Nonnull String extraResponderValues, Long replayCount)

    • invalidateTokens

      public static void invalidateTokens(@Nonnull String username)
      Invalidates all FAST tokens for the given username.
      Parameters:
      username - the local username (cannot be null)

    • invalidateToken

      public static void invalidateToken(@Nonnull String username, @Nonnull String mechanism, @Nonnull String clientId)

    • purgeExpiredTokens

      public static void purgeExpiredTokens()
      Purges all expired FAST tokens from the database.