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

All Methods Instance Methods Concrete Methods
`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()`