com.ongres.scram.client

Class ScramClient

java.lang.Object

com.ongres.scram.client.ScramClient

public final class ScramClient
extends Object

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MessageFlow.Stage
static interface	ScramClient.FinalBuildStage Builder stage for the optional atributes and the final build() call.
static interface	ScramClient.MechanismsBuildStage Builder stage for the advertised mechanisms.
static interface	ScramClient.PasswordBuildStage Builder stage for the password (or a ClientKey/ServerKey, or SaltedPassword).
static interface	ScramClient.UsernameBuildStage Builder stage for the required username.

Method Summary

Modifier and Type	Method and Description
static ScramClient.MechanismsBuildStage	builder() Creates a builder for ScramClient instances.
ClientFinalMessage	clientFinalMessage() Returns the text representation of a SCRAM client-final-message.
ClientFirstMessage	clientFirstMessage() Returns the text representation of a SCRAM client-first-message.
ScramMechanism	getScramMechanism() Returns the scram mechanism negotiated by this SASL client.
ServerFinalMessage	serverFinalMessage(String serverFinalMessage) Process and verify the server-final-message, from its String representation.
ServerFirstMessage	serverFirstMessage(String serverFirstMessage) Process the server-first-message, from its String representation.

Methods inherited from class java.lang.Object

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

Method Detail

getScramMechanism

public ScramMechanism getScramMechanism()

Returns the scram mechanism negotiated by this SASL client.

Returns:

the SCRAM mechanims selected during the negotiation

clientFirstMessage

public ClientFirstMessage clientFirstMessage()

Returns the text representation of a SCRAM client-first-message.

Returns:

The client-first-message

serverFirstMessage

public ServerFirstMessage serverFirstMessage(String serverFirstMessage)
                                      throws ScramParseException

Process the server-first-message, from its String representation.

Parameters:

serverFirstMessage - The server-first-message

Throws:

ScramParseException - If the message is not a valid server-first-message

IllegalArgumentException - If the message is null or empty

clientFinalMessage

public ClientFinalMessage clientFinalMessage()

Returns the text representation of a SCRAM client-final-message.

Returns:

The client-final-message

serverFinalMessage

public ServerFinalMessage serverFinalMessage(String serverFinalMessage)
                                      throws ScramParseException,
                                             ScramServerErrorException,
                                             ScramInvalidServerSignatureException

Process and verify the server-final-message, from its String representation.

Parameters:

serverFinalMessage - The server-final-message

Throws:

ScramParseException - If the message is not a valid

ScramServerErrorException - If the message is an error

ScramInvalidServerSignatureException - If the verification fails

IllegalArgumentException - If the message is null or empty

builder

public static ScramClient.MechanismsBuildStage builder()

Creates a builder for ScramClient instances.

Returns:

Builder instance to contruct a ScramClient