Package com.ongres.scram.client

Class ScramClient

  • All Implemented Interfaces:
    MessageFlow
    public final class ScramClient
extends java.lang.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:
    RFC-5802: Salted Challenge Response Authentication Mechanism (SCRAM) SASL and GSS-API Mechanisms, RFC-7677: SCRAM-SHA-256 and SCRAM-SHA-256-PLUS Simple Authentication and Security Layer (SASL) Mechanisms