Class ScramClient

java.lang.Object
com.ongres.scram.client.ScramClient
All Implemented Interfaces:
MessageFlow
public final class ScramClient extends Object implements MessageFlow
A class that represents a SCRAM client. Use this class to perform a SCRAM negotiation with a SCRAM server. This class performs an authentication execution for a given user, and has state related to it. Thus, it cannot be shared across users or authentication executions.

Example of usage: 

ScramClient scramClient = ScramClient.builder()
    .advertisedMechanisms(Arrays.asList("SCRAM-SHA-256", "SCRAM-SHA-256-PLUS"))
    .username("user")
    .password("pencil".toCharArray())
    .channelBinding("tls-server-end-point", channelBindingData) // client supports channel binding
    .build();

  // The build() call negotiates the SCRAM mechanism to be used. In this example,
  // since the server advertise support for the SCRAM-SHA-256-PLUS mechanism,
  // and the builder is set with the channel binding type and data, the constructed
  // scramClient will use the "SCRAM-SHA-256-PLUS" mechanism for authentication.

// Send the client-first-message ("p=...,,n=...,r=...")
ClientFirstMessage clientFirstMsg = scramClient.clientFirstMessage();
...
// Receive the server-first-message
ServerFirstMessage serverFirstMsg = scramClient.serverFirstMessage("r=...,s=...,i=...");
...
// Send the client-final-message ("c=...,r=...,p=...")
ClientFinalMessage clientFinalMsg = scramClient.clientFinalMessage();
...
// Receive the server-final-message, throw an ScramException on error
ServerFinalMessage serverFinalMsg = scramClient.serverFinalMessage("v=...");

Commonly, a protocol will specify that the server advertises supported and available mechanisms to the client via some facility provided by the protocol, and the client will then select the "best" mechanism from this list that it supports and finds suitable.

When building the ScramClient, it provides mechanism negotiation based on parameters, if channel binding is missing the client will use "n" as gs2-cbind-flag, if the channel binding is set, but the mechanisms send by the server do not advertise the -PLUS version, it will use "y" as gs2-cbind-flag, when both client and server support channel binding, it will use "p=" cb-name as gs2-cbind-flag.

See Also: