com.netflix.msl.msg
Class MslControl

java.lang.Object
  com.netflix.msl.msg.MslControl

public class MslControl
extends Object

Message Security Layer control provides the base operational MSL logic of sending and receiving messages with an optional thread pool. An application should only use one instance of MslControl for all MSL communication. This class is thread-safe.

This class provides methods for sending and receiving messages for all types of entities in both trusted network and peer-to-peer network types. Refer to the documentation for each method to determine which methods should be used based on the entity's role and network type.

Error Handling

MslConstants.ResponseCode.FAIL

The caller is notified of the failure.

MslConstants.ResponseCode.TRANSIENT_FAILURE

The caller is notified of the failure. MSL will not automatically retry.

MslConstants.ResponseCode.ENTITY_REAUTH

MSL will attempt to resend the message using the entity authentication data. The previous master token and master token-bound service tokens will be discarded if successful.

MslConstants.ResponseCode.USER_REAUTH

MSL will attempt to resend the message using the user authentication data if made available by the message context. Otherwise request fails. The previous user ID token-bound service tokens will be discarded if successful.

MslConstants.ResponseCode.KEYX_REQUIRED

MSL will attempt to perform key exchange to establish session keys and then resend the message.

MslConstants.ResponseCode.ENTITYDATA_REAUTH

MSL will attempt to resend the message using new entity authentication data. The previous master token and master token-bound service tokens will be discarded if successful.

MslConstants.ResponseCode.USERDATA_REAUTH

MSL will attempt to resend the message using new user authentication data if made available by the message context. Otherwise request fails. The previous user ID token-bound service tokens will be discarded if successful.

MslConstants.ResponseCode.EXPIRED

MSL will attempt to resend the message with the renewable flag set or after receiving a new master token.

MslConstants.ResponseCode.REPLAYED

MSL will attempt to resend the message after renewing the master token or receiving a new master token.

MslConstants.ResponseCode.SSOTOKEN_REJECTED

Identical to MslConstants.ResponseCode.USERDATA_REAUTH.

Anti-Replay

Requests marked as non-replayable will include a non-replayable ID.

Responses must always reply with the message ID of the request incremented by 1. When the request message ID equals 2⁶³-1 the response message ID must be 0. If the response message ID does not equal the expected value it is rejected and the caller is notified.

Renewal Synchronization

For a given MSL context there will be at most one renewable request with a master token and key request data in process. This prevents excessive master token renewal and potential renewal race conditions.

Requests will be marked renewable if any of the following is true:

• The master token renewal window has been entered.
• The user ID token renewal window has been entered.
• The application requests or requires establishment of session keys.

MSL Handshake

Whenever requested or possible application data is encrypted and integrity-protected while in transit. If the MSL context entity authentication scheme does not support encryption or integrity protection when requested an initial handshake will be performed to establish session keys. This handshake occurs silently without the application's knowledge.

Nested Class Summary

static class	MslControl.ApplicationError Application level errors that may translate into MSL level errors.
static class	MslControl.MslChannel A MessageInputStream and MessageOutputStream pair representing a single MSL communication channel established between the local and remote entities.

Constructor Summary

MslControl(int numThreads)
Create a new instance of MSL control with the specified number of threads.

MslControl(int numThreads, ErrorMessageRegistry messageRegistry)
Create a new instance of MSL control with the specified number of threads and user error message registry.

Method Summary

protected static boolean	cancelled(Throwable t) Returns true if the current thread has been interrupted as indicated by the Thread#isInterrupted() method or the type of caught throwable.
Future<Boolean>	error(MslContext ctx, MessageContext msgCtx, MslControl.ApplicationError err, OutputStream out, MessageInputStream request) Send an error response over the provided output stream.
protected void	finalize()
Future<MessageInputStream>	receive(MslContext ctx, MessageContext msgCtx, InputStream in, OutputStream out, int timeout) Receive a request over the provided input stream.
Future<MslControl.MslChannel>	request(MslContext ctx, MessageContext msgCtx, InputStream in, OutputStream out, int timeout) Send a request to the remote entity over the provided output stream and receive a resposne over the provided input stream.
Future<MslControl.MslChannel>	request(MslContext ctx, MessageContext msgCtx, URL remoteEntity, int timeout) Send a request to the entity at the provided URL.
Future<MslControl.MslChannel>	respond(MslContext ctx, MessageContext msgCtx, InputStream in, OutputStream out, MessageInputStream request, int timeout) Send a response over the provided output stream.
void	setFilterFactory(FilterStreamFactory factory) Assigns a filter stream factory that will be used to filter any incoming or outgoing messages.
void	shutdown() Gracefully shutdown the MSL control instance.

Methods inherited from class java.lang.Object

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

Constructor Detail

MslControl

public MslControl(int numThreads)

Create a new instance of MSL control with the specified number of threads. A thread count of zero will cause all operations to execute on the calling thread.

Parameters:

numThreads - number of worker threads to create.

MslControl

public MslControl(int numThreads,
                  ErrorMessageRegistry messageRegistry)

Create a new instance of MSL control with the specified number of threads and user error message registry. A thread count of zero will cause all operations to execute on the calling thread.

Parameters:

numThreads - number of worker threads to create.

messageRegistry - error message registry.

Method Detail

cancelled

protected static boolean cancelled(Throwable t)

Returns true if the current thread has been interrupted as indicated by the Thread#isInterrupted() method or the type of caught throwable.

Parameters:

t - caught throwable. May be null.

Returns:

true if this thread was interrupted or the exception indicates an operation was interrupted.

setFilterFactory

public void setFilterFactory(FilterStreamFactory factory)

Assigns a filter stream factory that will be used to filter any incoming or outgoing messages. The filters will be placed between the MSL message and MSL control, meaning they will see the actual MSL message data as it is being read from or written to the remote entity.

Parameters:

factory - filter stream factory. May be null.

shutdown

public void shutdown()

Gracefully shutdown the MSL control instance. No additional messages may be processed. Any messages pending or in process will be completed.

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

receive

public Future<MessageInputStream> receive(MslContext ctx,
                                          MessageContext msgCtx,
                                          InputStream in,
                                          OutputStream out,
                                          int timeout)

Receive a request over the provided input stream.

If there is an error with the message an error response will be sent over the provided output stream.

This method should only be used by trusted network servers and peer- to-peer entities to receive a request initiated by the remote entity. The remote entity should have used request(MslContext, MessageContext, URL, int).

The returned Future will return the received MessageInputStream on completion or null if a reply was automatically sent (for example in response to a handshake request) or if the operation was cancelled or interrupted. The returned message may be an error message if the maximum number of messages is hit without successfully receiving the final message. It may throw a MslException, MslErrorResponseException, or IOException.

The remote entity input and output streams will not be closed in case the caller wishes to reuse them.

Parameters:

ctx - MSL context.

msgCtx - message context.

in - remote entity input stream.

out - remote entity output stream.

timeout - renewal acquisition lock timeout in milliseconds.

Returns:

a future for the message.

respond

public Future<MslControl.MslChannel> respond(MslContext ctx,
                                             MessageContext msgCtx,
                                             InputStream in,
                                             OutputStream out,
                                             MessageInputStream request,
                                             int timeout)

Send a response over the provided output stream.

This method should only be used by trusted network servers and peer- to-peer entities after receiving a request via receive(MslContext, MessageContext, InputStream, OutputStream, int). The remote entity should have used request(MslContext, MessageContext, URL, int).

The returned Future will return a MslChannel containing the final MessageOutputStream that should be used to send any additional application data not already sent via MessageContext.write(MessageOutputStream) to the remote entity, and in peer-to-peer mode may also contain a MessageInputStream as described below.

In peer-to-peer mode a new MessageInputStream may be returned which should be used in place of the previous MessageInputStream being responded to. This will only occur if the initial response sent could not include application data and was instead a handshake message. The new MessageInputStream will not include any application data already read off of the previous MessageInputStream; it will only contain new application data that is a continuation of the previous message's application data.

The returned Future will return null if cancelled, interrupted, if an error response was received (peer-to-peer only) resulting in a failure to establish the communication channel, if the response could not be sent with encryption or integrity protection when required (trusted network-mode only), if a user cannot be attached to the response due to lack of a master token, or if the maximum number of messages is hit without sending the message. In these cases the remote entity's next message can be received by another call to receive(MslContext, MessageContext, InputStream, OutputStream, int).

It may throw a MslException, MslErrorResponseException, or IOException.

The remote entity input and output streams will not be closed in case the caller wishes to reuse them.

Parameters:

ctx - MSL context.

msgCtx - message context.

in - remote entity input stream.

out - remote entity output stream.

request - message input stream to create the response for.

timeout - renewal lock acquisition timeout in milliseconds.

Returns:

a future for the communication channel.

Throws:

IllegalArgumentException - if the request message input stream is an error message.

error

public Future<Boolean> error(MslContext ctx,
                             MessageContext msgCtx,
                             MslControl.ApplicationError err,
                             OutputStream out,
                             MessageInputStream request)

Send an error response over the provided output stream. Any replies to the error response may be received by a subsequent call to receive(MslContext, MessageContext, InputStream, OutputStream, int).

This method should only be used by trusted network servers and peer- to-peer entities after receiving a request via receive(MslContext, MessageContext, InputStream, OutputStream, int). The remote entity should have used request(MslContext, MessageContext, URL, int).

The returned Future will return true on success or false if cancelled or interrupted. It may throw a MslException or IOException.

The remote entity input and output streams will not be closed in case the caller wishes to reuse them.

Parameters:

ctx - MSL context.

msgCtx - message context.

err - error type.

out - remote entity output stream.

request - request input srtream to create the response for.

Returns:

a future for the operation.

Throws:

IllegalArgumentException - if the request message input stream is an error message.

request

public Future<MslControl.MslChannel> request(MslContext ctx,
                                             MessageContext msgCtx,
                                             URL remoteEntity,
                                             int timeout)

Send a request to the entity at the provided URL.

This method should only be used by trusted network clients when initiating a new request. The remote entity should be using receive(MslContext, MessageContext, InputStream, OutputStream, int) and respond(MslContext, MessageContext, InputStream, OutputStream, MessageInputStream, int).

The returned Future will return a MslChannel containing the final MessageOutputStream that should be used to send any additional application data not already sent via MessageContext.write(MessageOutputStream) and the MessageInputStream of the established MSL communication channel. If an error message was received then the MSL channel's message output stream will be null.

The returned Future will return null if cancelled or interrupted. The returned message may be an error message if the maximum number of messages is hit without successfully sending the request and receiving the response. It may throw a MslException or IOException.

The caller must close the returned message input stream and message outut stream.

Parameters:

ctx - MSL context.

msgCtx - message context.

remoteEntity - remote entity URL.

timeout - connect, read, and renewal lock acquisition timeout in milliseconds.

Returns:

a future for the communication channel.

Throws:

IllegalStateException - if used in peer-to-peer mode.

request

public Future<MslControl.MslChannel> request(MslContext ctx,
                                             MessageContext msgCtx,
                                             InputStream in,
                                             OutputStream out,
                                             int timeout)

Send a request to the remote entity over the provided output stream and receive a resposne over the provided input stream.

This method should only be used by peer-to-peer entities when initiating a new request. The remote entity should be using receive(MslContext, MessageContext, InputStream, OutputStream, int) and respond(MslContext, MessageContext, InputStream, OutputStream, MessageInputStream, int).

The returned Future will return a MslChannel containing the final MessageOutputStream that should be used to send any additional application data not already sent via MessageContext.write(MessageOutputStream) and the MessageInputStream of the established MSL communication channel. If an error message was received then the MSL channel's message output stream will be null.

The returned Future will return null if cancelled or interrupted. The returned message may be an error message if the maximum number of messages is hit without successfully sending the request and receiving the response. It may throw a MslException or IOException.

The caller must close the returned message input stream and message outut stream. The remote entity input and output streams will not be closed when the message input and output streams are closed, in case the caller wishes to reuse them.

TODO once Java supports the WebSocket protocol we can remove this method in favor of the one accepting a URL parameter. (Or is it the other way around?)

Parameters:

ctx - MSL context.

msgCtx - message context.

in - remote entity input stream.

out - remote entity output stream.

timeout - renewal lock acquisition timeout in milliseconds.

Returns:

a future for the communication channel.

Throws:

IllegalStateException - if used in trusted network mode.