public interface SaslServer
Performs SASL authentication as a server.
A server such as an LDAP server gets an instance of this class in order to
perform authentication defined by a specific SASL mechanism. Invoking methods
on the SaslServer
instance generates challenges corresponding to
the SASL mechanism implemented by the SaslServer
instance. As
the authentication proceeds, the instance encapsulates the state of a SASL
server's authentication exchange.
Here's an example of how an LDAP server might use a SaslServer
instance. It first gets an instance of a SaslServer
for the SASL
mechanism requested by the client:
SaslServer ss = Sasl.createSaslServer(mechanism, "ldap", myFQDN, props, callbackHandler);
It can then proceed to use the server for authentication. For example, suppose the LDAP server received an LDAP BIND request containing the name of the SASL mechanism and an (optional) initial response. It then might use the server as follows:
while (!ss.isComplete()) { try { byte[] challenge = ss.evaluateResponse(response); if (ss.isComplete()) { status = ldap.sendBindResponse(mechanism, challenge, SUCCESS); } else { status = ldap.sendBindResponse(mechanism, challenge, SASL_BIND_IN_PROGRESS); response = ldap.readBindRequest(); } } catch (SaslException x) { status = ldap.sendErrorResponse(x); break; } } if (ss.isComplete() && (status == SUCCESS)) { String qop = (String) sc.getNegotiatedProperty(Sasl.QOP); if (qop != null && (qop.equalsIgnoreCase("auth-int") || qop.equalsIgnoreCase("auth-conf"))) { // Use SaslServer.wrap() and SaslServer.unwrap() for future // communication with client ldap.in = new SecureInputStream(ss, ldap.in); ldap.out = new SecureOutputStream(ss, ldap.out); } }
Sasl
,
SaslServerFactory
Modifier and Type | Method and Description |
---|---|
void |
dispose()
Disposes of any system resources or security-sensitive information the
SaslServer might be using. |
byte[] |
evaluateResponse(byte[] response)
Evaluates the response data and generates a challenge.
|
String |
getAuthorizationID()
Reports the authorization ID in effect for the client of this session This
method can only be called if
isComplete() returns true . |
String |
getMechanismName()
Returns the IANA-registered mechanism name of this SASL server (e.g.
|
Object |
getNegotiatedProperty(String propName)
Retrieves the negotiated property.
|
boolean |
isComplete()
Determines if the authentication exchange has completed.
|
byte[] |
unwrap(byte[] incoming,
int offset,
int len)
Unwraps a byte array received from the client.
|
byte[] |
wrap(byte[] outgoing,
int offset,
int len)
Wraps a byte array to be sent to the client.
|
String getMechanismName()
byte[] evaluateResponse(byte[] response) throws SaslException
null
if the authentication has succeeded and
no more challenge data is to be sent to the client. It is non-null if the
authentication must be continued by sending a challenge to the client, or
if the authentication has succeeded but challenge data needs to be
processed by the client. isComplete()
should be called after each
call to evaluateResponse()
,to determine if any further
response is needed from the client.response
- the non-null (but possibly empty) response sent by the
client.null
challenge to send to the client.
It is null
if the authentication has succeeded and there is
no more challenge data to be sent to the client.SaslException
- if an error occurred while processing the response
or generating a challenge.boolean isComplete()
evaluateResponse(byte[])
to determine whether the authentication has completed successfully or
should be continued.true
if the authentication exchange has completed;
false
otherwise.String getAuthorizationID()
isComplete()
returns true
.IllegalStateException
- if this authentication session has not
completed.byte[] unwrap(byte[] incoming, int offset, int len) throws SaslException
Unwraps a byte array received from the client. This method can be called
only after the authentication exchange has completed (i.e., when
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 client.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
Wraps a byte array to be sent to the client. This method can be called
only after the authentication exchange has completed (i.e., when
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.null
, the
property was not negotiated or is not applicable to this mechanism.IllegalStateException
- if this authentication exchange has not
completed.void dispose() throws SaslException
SaslServer
might be using. Invoking this method invalidates
the SaslServer
instance. This method is idempotent.SaslException
- if a problem was encountered while disposing of the
resources.