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 and Description
ScramScheme() Default policy: warn if i < 4096, no hard enforcement; SHA-256 only.
ScramScheme(int warnMinIterations, int minIterationsRequired, SecureRandom rnd) Constructor with custom iteration policy.

Method Summary

Modifier and Type	Method and Description
String	generateAuthResponse(HttpHost host, HttpRequest request, 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(HttpHost host, CredentialsProvider credentialsProvider, 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, HttpContext context) Legacy entry point: wraps AuthenticationException as MalformedChallengeException.
void	processChallenge(HttpHost host, boolean challenged, AuthChallenge authChallenge, 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 Detail

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

Method Detail

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

AuthScheme.processChallenge(HttpHost, boolean, AuthChallenge, HttpContext)

processChallenge

public void processChallenge(HttpHost host,
                             boolean challenged,
                             AuthChallenge authChallenge,
                             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(HttpHost host,
                               CredentialsProvider credentialsProvider,
                               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

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(HttpHost host,
                                   HttpRequest request,
                                   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

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:

AuthScheme.isResponseReady(HttpHost, CredentialsProvider, HttpContext)

getPrincipal

public Principal getPrincipal()

Returns Principal whose credentials are used.

Specified by:

getPrincipal in interface AuthScheme

Returns:

user principal

Since:

5.6

See Also:

AuthScheme.isConnectionBased()