Package com.ongres.scram.client
Class ScramClient
- java.lang.Object
-
- com.ongres.scram.client.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.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static class
ScramClient.Builder
Builds instances of typeScramClient
.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.-
Nested classes/interfaces inherited from interface com.ongres.scram.client.MessageFlow
MessageFlow.Stage
-
-
Field Summary
Fields Modifier and Type Field Description private java.lang.String
authzid
private byte[]
cbindData
private java.lang.String
cbindType
private Gs2CbindFlag
channelBinding
private ClientFinalProcessor
clientFinalProcessor
private ClientFirstMessage
clientFirstMessage
private byte[]
clientKey
private MessageFlow.Stage
currentState
private java.lang.String
nonce
private char[]
password
private byte[]
saltedPassword
private ScramMechanism
scramMechanism
private ServerFirstProcessor
serverFirstProcessor
private byte[]
serverKey
private StringPreparation
stringPreparation
private java.lang.String
username
-
Constructor Summary
Constructors Modifier Constructor Description private
ScramClient(@NotNull ScramClient.Builder builder)
Constructs a SCRAM client, to perform an authentication for a given user.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static ScramClient.MechanismsBuildStage
builder()
Creates a builder forScramClient
instances.ClientFinalMessage
clientFinalMessage()
Returns the text representation of a SCRAMclient-final-message
.ClientFirstMessage
clientFirstMessage()
Returns the text representation of a SCRAMclient-first-message
.ScramMechanism
getScramMechanism()
Returns the scram mechanism negotiated by this SASL client.ServerFinalMessage
serverFinalMessage(java.lang.String serverFinalMessage)
Process and verify theserver-final-message
, from its String representation.ServerFirstMessage
serverFirstMessage(java.lang.String serverFirstMessage)
Process theserver-first-message
, from its String representation.
-
-
-
Field Detail
-
scramMechanism
private final ScramMechanism scramMechanism
-
channelBinding
private final Gs2CbindFlag channelBinding
-
stringPreparation
private final StringPreparation stringPreparation
-
username
private final java.lang.String username
-
password
private final char[] password
-
saltedPassword
private final byte[] saltedPassword
-
clientKey
private final byte[] clientKey
-
serverKey
private final byte[] serverKey
-
cbindType
private final java.lang.String cbindType
-
cbindData
private final byte[] cbindData
-
authzid
private final java.lang.String authzid
-
nonce
private final java.lang.String nonce
-
currentState
private MessageFlow.Stage currentState
-
clientFirstMessage
private ClientFirstMessage clientFirstMessage
-
serverFirstProcessor
private ServerFirstProcessor serverFirstProcessor
-
clientFinalProcessor
private ClientFinalProcessor clientFinalProcessor
-
-
Constructor Detail
-
ScramClient
private ScramClient(@NotNull @NotNull ScramClient.Builder builder)
Constructs a SCRAM client, to perform an authentication for a given user. This class can not be instantiated directly, use abuilder()
is used instead.- Parameters:
builder
- The Builder used to initialize this client
-
-
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 SCRAMclient-first-message
.- Specified by:
clientFirstMessage
in interfaceMessageFlow
- Returns:
- The
client-first-message
-
serverFirstMessage
public ServerFirstMessage serverFirstMessage(java.lang.String serverFirstMessage) throws ScramParseException
Process theserver-first-message
, from its String representation.- Specified by:
serverFirstMessage
in interfaceMessageFlow
- Parameters:
serverFirstMessage
- Theserver-first-message
- Throws:
ScramParseException
- If the message is not a valid server-first-messagejava.lang.IllegalArgumentException
- If the message is null or empty
-
clientFinalMessage
public ClientFinalMessage clientFinalMessage()
Returns the text representation of a SCRAMclient-final-message
.- Specified by:
clientFinalMessage
in interfaceMessageFlow
- Returns:
- The
client-final-message
-
serverFinalMessage
public ServerFinalMessage serverFinalMessage(java.lang.String serverFinalMessage) throws ScramParseException, ScramServerErrorException, ScramInvalidServerSignatureException
Process and verify theserver-final-message
, from its String representation.- Specified by:
serverFinalMessage
in interfaceMessageFlow
- Parameters:
serverFinalMessage
- Theserver-final-message
- Throws:
ScramParseException
- If the message is not a validScramServerErrorException
- If the message is an errorScramInvalidServerSignatureException
- If the verification failsjava.lang.IllegalArgumentException
- If the message is null or empty
-
builder
public static ScramClient.MechanismsBuildStage builder()
Creates a builder forScramClient
instances.- Returns:
- Builder instance to contruct a
ScramClient
-
-