Package com.ongres.scram.client
Class ScramClient
java.lang.Object
com.ongres.scram.client.ScramClient
- All Implemented Interfaces:
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:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static final class
Builds instances of typeScramClient
.static interface
Builder stage for the optional atributes and the final build() call.static interface
Builder stage for the advertised mechanisms.static interface
Builder stage for the password (or a ClientKey/ServerKey, or SaltedPassword).static interface
Builder stage for the required username.Nested classes/interfaces inherited from interface com.ongres.scram.client.MessageFlow
MessageFlow.Stage
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final String
private final byte[]
private final String
private final Gs2CbindFlag
private ClientFinalProcessor
private ClientFirstMessage
private final byte[]
private MessageFlow.Stage
private final String
private final char[]
private final byte[]
private final ScramMechanism
private ServerFirstProcessor
private final byte[]
private final StringPreparation
private final String
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
ScramClient
(ScramClient.Builder builder) Constructs a SCRAM client, to perform an authentication for a given user. -
Method Summary
Modifier and TypeMethodDescriptionbuilder()
Creates a builder forScramClient
instances.Returns the text representation of a SCRAMclient-final-message
.Returns the text representation of a SCRAMclient-first-message
.Returns the scram mechanism negotiated by this SASL client.serverFinalMessage
(String serverFinalMessage) Process and verify theserver-final-message
, from its String representation.serverFirstMessage
(String serverFirstMessage) Process theserver-first-message
, from its String representation.
-
Field Details
-
scramMechanism
-
channelBinding
-
stringPreparation
-
username
-
password
private final char[] password -
saltedPassword
private final byte[] saltedPassword -
clientKey
private final byte[] clientKey -
serverKey
private final byte[] serverKey -
cbindType
-
cbindData
private final byte[] cbindData -
authzid
-
nonce
-
currentState
-
clientFirstMessage
-
serverFirstProcessor
-
clientFinalProcessor
-
-
Constructor Details
-
ScramClient
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 Details
-
getScramMechanism
Returns the scram mechanism negotiated by this SASL client.- Returns:
- the SCRAM mechanims selected during the negotiation
-
clientFirstMessage
Returns the text representation of a SCRAMclient-first-message
.- Specified by:
clientFirstMessage
in interfaceMessageFlow
- Returns:
- The
client-first-message
-
serverFirstMessage
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-messageIllegalArgumentException
- If the message is null or empty
-
clientFinalMessage
Returns the text representation of a SCRAMclient-final-message
.- Specified by:
clientFinalMessage
in interfaceMessageFlow
- Returns:
- The
client-final-message
-
serverFinalMessage
public ServerFinalMessage serverFinalMessage(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 failsIllegalArgumentException
- If the message is null or empty
-
builder
Creates a builder forScramClient
instances.- Returns:
- Builder instance to contruct a
ScramClient
-