Package org.apache.hc.client5.http.impl.auth

Class ScramScheme

java.lang.Object
org.apache.hc.client5.http.impl.auth.ScramScheme
All Implemented Interfaces:
AuthScheme
@Contract(threading=UNSAFE) @Experimental public final class ScramScheme extends Object implements AuthScheme
Strict HTTP SCRAM client implementing SCRAM-SHA-256 per RFC 7804 with SCRAM core per RFC 5802/7677.

HTTP SCRAM uses no channel binding (GS2 header "n,,"; c=biws).

Experimental: This API is work in progress and may change without notice in a future release.

Since:
5.6

  • Constructor Summary

    Constructors
    Constructor
    Description
    ScramScheme()
    Default policy: warn if i < 4096, no hard enforcement; SHA-256 only.
    ScramScheme(int warnMinIterations, int minIterationsRequired, int maxIterationsAllowed, SecureRandom rnd)
    Constructor with custom iteration policy.
    ScramScheme(int warnMinIterations, int minIterationsRequired, SecureRandom rnd)
    Constructor with custom iteration policy.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    generateAuthResponse(org.apache.hc.core5.http.HttpHost host, org.apache.hc.core5.http.HttpRequest request, org.apache.hc.core5.http.protocol.HttpContext context)
    Generates an authorization response based on the current state.
    String
    getName()
    Returns textual designation of the scheme.
    Principal
    getPrincipal()
    Returns Principal whose credentials are used.
    String
    getRealm()
    Returns authentication realm.
    boolean
    isChallengeComplete()
    Authentication process may involve a series of challenge-response exchanges.
    boolean
    isChallengeExpected()
    SCRAM must inspect final responses to verify v= in Authentication-Info.
    boolean
    isConnectionBased()
    SCRAM is per-request (no connection binding).
    boolean
    isResponseReady(org.apache.hc.core5.http.HttpHost host, CredentialsProvider credentialsProvider, org.apache.hc.core5.http.protocol.HttpContext context)
    Allow response when: - INIT (preemptive client-first) — only if creds have been prepared - ANNOUNCED (401 without data) - SERVER_FIRST_RCVD (ready to send client-final)
    void
    processChallenge(AuthChallenge authChallenge, org.apache.hc.core5.http.protocol.HttpContext context)
    Legacy entry point: wraps AuthenticationException as MalformedChallengeException.
    void
    processChallenge(org.apache.hc.core5.http.HttpHost host, boolean challenged, AuthChallenge authChallenge, org.apache.hc.core5.http.protocol.HttpContext context)
    Handles 401 challenges (with/without data) and final responses carrying Authentication-Info (any status code).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • ScramScheme

      public ScramScheme()
      Default policy: warn if i < 4096, no hard enforcement; SHA-256 only.
      Since:
      5.6

    • ScramScheme

      public ScramScheme(int warnMinIterations, int minIterationsRequired, SecureRandom rnd)
      Constructor with custom iteration policy.
      Parameters:
      warnMinIterations - warn if iteration count is lower than this (0 disables warnings)
      minIterationsRequired - fail if iteration count is lower than this (0 disables enforcement)
      rnd - optional secure random source (null uses system default)
      Since:
      5.6

    • ScramScheme

      public ScramScheme(int warnMinIterations, int minIterationsRequired, int maxIterationsAllowed, SecureRandom rnd)
      Constructor with custom iteration policy.
      Parameters:
      warnMinIterations - warn if iteration count is lower than this (0 disables warnings)
      minIterationsRequired - fail if iteration count is lower than this (0 disables enforcement)
      maxIterationsAllowed - fail if iteration count is greater than this (must be positive)
      rnd - optional secure random source (null uses system default)
      Since:
      5.6

  • Method Details

    • getName

      public String getName()
      Returns textual designation of the scheme.
      Specified by:
      getName in interface AuthScheme
      Returns:
      the name of the given authentication scheme
      Since:
      5.6

    • isConnectionBased

      public boolean isConnectionBased()
      SCRAM is per-request (no connection binding).
      Specified by:
      isConnectionBased in interface AuthScheme
      Returns:
      true if the scheme is connection based, false if the scheme is request based.
      Since:
      5.6

    • isChallengeExpected

      public boolean isChallengeExpected()
      SCRAM must inspect final responses to verify v= in Authentication-Info.
      Specified by:
      isChallengeExpected in interface AuthScheme
      Returns:
      true if responses with non 401/407 response codes must be processed by the scheme.
      Since:
      5.6

    • processChallenge

      public void processChallenge(AuthChallenge authChallenge, org.apache.hc.core5.http.protocol.HttpContext context) throws MalformedChallengeException
      Legacy entry point: wraps AuthenticationException as MalformedChallengeException.
      Specified by:
      processChallenge in interface AuthScheme
      Parameters:
      authChallenge - the auth challenge
      context - HTTP context
      Throws:
      MalformedChallengeException - in case the auth challenge is incomplete, malformed or otherwise invalid.
      Since:
      5.6
      See Also:

    • processChallenge

      public void processChallenge(org.apache.hc.core5.http.HttpHost host, boolean challenged, AuthChallenge authChallenge, org.apache.hc.core5.http.protocol.HttpContext context) throws MalformedChallengeException, AuthenticationException
      Handles 401 challenges (with/without data) and final responses carrying Authentication-Info (any status code).
      Specified by:
      processChallenge in interface AuthScheme
      Parameters:
      host - HTTP host
      challenged - true if the response was unauthorised (401/407)
      authChallenge - the auth challenge or null if no challenge was received
      context - HTTP context
      Throws:
      MalformedChallengeException - in case the auth challenge is incomplete,
      AuthenticationException - in case the authentication process is unsuccessful.
      Since:
      5.6

    • isChallengeComplete

      public boolean isChallengeComplete()
      Description copied from interface: AuthScheme
      Authentication process may involve a series of challenge-response exchanges. This method tests if the authorization process has been fully completed (either successfully or unsuccessfully), that is, all the required authorization challenges have been processed in their entirety.

      Please note if the scheme returns true from this method in response to a challenge, it effectively implies a failure to respond to this challenge and termination of the authentication process.

      Specified by:
      isChallengeComplete in interface AuthScheme
      Returns:
      true if the authentication process has been completed, false otherwise.
      Since:
      5.6

    • getRealm

      public String getRealm()
      Description copied from interface: AuthScheme
      Returns authentication realm. If the concept of an authentication realm is not applicable to the given authentication scheme, returns null.
      Specified by:
      getRealm in interface AuthScheme
      Returns:
      the authentication realm
      Since:
      5.6

    • isResponseReady

      public boolean isResponseReady(org.apache.hc.core5.http.HttpHost host, CredentialsProvider credentialsProvider, org.apache.hc.core5.http.protocol.HttpContext context) throws AuthenticationException
      Allow response when: - INIT (preemptive client-first) — only if creds have been prepared - ANNOUNCED (401 without data) - SERVER_FIRST_RCVD (ready to send client-final)
      Specified by:
      isResponseReady in interface AuthScheme
      Parameters:
      credentialsProvider - The credentials to be used for authentication
      context - HTTP context
      Returns:
      true if an authorization response can be generated and the authentication handshake can proceed, false otherwise.
      Throws:
      AuthenticationException - if authorization string cannot be generated due to an authentication failure
      Since:
      5.6

    • generateAuthResponse

      public String generateAuthResponse(org.apache.hc.core5.http.HttpHost host, org.apache.hc.core5.http.HttpRequest request, org.apache.hc.core5.http.protocol.HttpContext context) throws AuthenticationException
      Description copied from interface: AuthScheme
      Generates an authorization response based on the current state. Some authentication schemes may need to load user credentials required to generate an authorization response from a CredentialsProvider prior to this method call.
      Specified by:
      generateAuthResponse in interface AuthScheme
      Parameters:
      request - The request being authenticated
      context - HTTP context
      Returns:
      authorization header
      Throws:
      AuthenticationException - if authorization string cannot be generated due to an authentication failure
      Since:
      5.6
      See Also:

    • getPrincipal

      public Principal getPrincipal()
      Returns Principal whose credentials are used.
      Specified by:
      getPrincipal in interface AuthScheme
      Returns:
      user principal
      Since:
      5.6
      See Also: