public interface SaslClient
A protocol library such as one for LDAP gets an instance of this
class in order to perform authentication defined by a specific SASL
mechanism. Invoking methods on the SaslClient
instance
process challenges and create responses according to the SASL
mechanism implemented by the SaslClient
.
As the authentication proceeds, the instance
encapsulates the state of a SASL client's authentication exchange.
Here's an example of how an LDAP library might use a SaslClient
.
It first gets an instance of a SaslClient
:
It can then proceed to use the client for authentication. For example, an LDAP library might use the client as follows:SaslClient sc = Sasl.createSaslClient(mechanisms, authorizationId, protocol, serverName, props, callbackHandler);
If the mechanism has an initial response, the library invokes// Get initial response and send to server byte[] response = (sc.hasInitialResponse() ? sc.evaluateChallenge(new byte[0]) : null); LdapResult res = ldap.sendBindRequest(dn, sc.getName(), response); while (!sc.isComplete() && (res.status == SASL_BIND_IN_PROGRESS || res.status == SUCCESS)) { response = sc.evaluateChallenge(res.getBytes()); if (res.status == SUCCESS) { // we're done; don't expect to send another BIND if (response != null) { throw new SaslException( "Protocol error: attempting to send response after completion"); } break; } res = ldap.sendBindRequest(dn, sc.getName(), response); } if (sc.isComplete() && res.status == SUCCESS) { String qop = (String) sc.getNegotiatedProperty(Sasl.QOP); if (qop != null && (qop.equalsIgnoreCase("auth-int") || qop.equalsIgnoreCase("auth-conf"))) { // Use SaslClient.wrap() and SaslClient.unwrap() for future // communication with server ldap.in = new SecureInputStream(sc, ldap.in); ldap.out = new SecureOutputStream(sc, ldap.out); } }
evaluateChallenge()
with an empty
challenge and to get initial response.
Protocols such as IMAP4, which do not include an initial response with
their first authentication command to the server, initiates the
authentication without first calling hasInitialResponse()
or evaluateChallenge()
.
When the server responds to the command, it sends an initial challenge.
For a SASL mechanism in which the client sends data first, the server should
have issued a challenge with no data. This will then result in a call
(on the client) to evaluateChallenge()
with an empty challenge.Sasl
,
SaslClientFactory
Modifier and Type | Method and Description |
---|---|
void |
dispose()
Disposes of any system resources or security-sensitive information
the SaslClient might be using.
|
byte[] |
evaluateChallenge(byte[] challenge)
Evaluates the challenge data and generates a response.
|
String |
getMechanismName()
Returns the IANA-registered mechanism name of this SASL client.
|
Object |
getNegotiatedProperty(String propName)
Retrieves the negotiated property.
|
boolean |
hasInitialResponse()
Determines whether this mechanism has an optional initial response.
|
boolean |
isComplete()
Determines whether the authentication exchange has completed.
|
byte[] |
unwrap(byte[] incoming,
int offset,
int len)
Unwraps a byte array received from the server.
|
byte[] |
wrap(byte[] outgoing,
int offset,
int len)
Wraps a byte array to be sent to the server.
|
String getMechanismName()
boolean hasInitialResponse()
evaluateChallenge()
with an
empty array to get the initial response.byte[] evaluateChallenge(byte[] challenge) throws SaslException
challenge
- The non-null challenge sent from the server.
The challenge array may have zero length.SaslException
- If an error occurred while processing
the challenge or generating a response.boolean isComplete()
byte[] unwrap(byte[] incoming, int offset, int len) throws SaslException
isComplete()
returns true) and only if
the authentication exchange has negotiated integrity and/or privacy
as the quality of protection; otherwise, an
IllegalStateException
is thrown.
incoming
is the contents of the SASL buffer as defined in RFC 2222
without the leading four octet field that represents the length.
offset
and len
specify the portion of incoming
to use.
incoming
- A non-null byte array containing the encoded bytes
from the server.offset
- The starting position at incoming
of the bytes to use.len
- The number of bytes from incoming
to use.SaslException
- if incoming
cannot be successfully
unwrapped.IllegalStateException
- if the authentication exchange has
not completed, or if the negotiated quality of protection
has neither integrity nor privacy.byte[] wrap(byte[] outgoing, int offset, int len) throws SaslException
isComplete()
returns true) and only if
the authentication exchange has negotiated integrity and/or privacy
as the quality of protection; otherwise, an
IllegalStateException
is thrown.
The result of this method will make up the contents of the SASL buffer
as defined in RFC 2222 without the leading four octet field that
represents the length.
offset
and len
specify the portion of outgoing
to use.
outgoing
- A non-null byte array containing the bytes to encode.offset
- The starting position at outgoing
of the bytes to use.len
- The number of bytes from outgoing
to use.SaslException
- if outgoing
cannot be successfully
wrapped.IllegalStateException
- if the authentication exchange has
not completed, or if the negotiated quality of protection
has neither integrity nor privacy.Object getNegotiatedProperty(String propName)
isComplete()
returns true); otherwise, an
IllegalStateException
is thrown.propName
- The non-null property name.IllegalStateException
- if this authentication exchange
has not completedvoid dispose() throws SaslException
SaslException
- If a problem was encountered while disposing
the resources. Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2021, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.