EAP-TTLS sessions will always follow the path: * *
Created --+--> Handshake --+--> Tunnel (EAP) --+--> Final * *
Note: EAP-TTLS will only be allowed to run once. The inner EAP instance will not be able to * select EAP-TTLS. This is handled in the tunnel state when a new EAP session config is created. * * @see RFC 5281, Extensible Authentication Protocol * Tunneled Transport Layer Security Authenticated Protocol Version 0 (EAP-TTLSv0) */ public class EapTtlsMethodStateMachine extends EapMethodStateMachine { @VisibleForTesting public static TlsSessionFactory sTlsSessionFactory = new TlsSessionFactory(); private static final int DEFAULT_AVP_VENDOR_ID = 0; private final Context mContext; private final EapTtlsConfig mEapTtlsConfig; private final EapTtlsTypeDataDecoder mTypeDataDecoder; private final SecureRandom mSecureRandom; @VisibleForTesting final EapTtlsInboundFragmentationHelper mInboundFragmentationHelper; @VisibleForTesting final EapTtlsOutboundFragmentationHelper mOutboundFragmentationHelper; @VisibleForTesting TlsSession mTlsSession; public EapTtlsMethodStateMachine( Context context, EapTtlsConfig eapTtlsConfig, SecureRandom secureRandom) { this( context, eapTtlsConfig, secureRandom, new EapTtlsTypeDataDecoder(), new EapTtlsInboundFragmentationHelper(), new EapTtlsOutboundFragmentationHelper()); } @VisibleForTesting public EapTtlsMethodStateMachine( Context context, EapTtlsConfig eapTtlsConfig, SecureRandom secureRandom, EapTtlsTypeDataDecoder typeDataDecoder, EapTtlsInboundFragmentationHelper inboundFragmentationHelper, EapTtlsOutboundFragmentationHelper outboundFragmentationHelper) { mContext = context; mEapTtlsConfig = eapTtlsConfig; mTypeDataDecoder = typeDataDecoder; mSecureRandom = secureRandom; mInboundFragmentationHelper = inboundFragmentationHelper; mOutboundFragmentationHelper = outboundFragmentationHelper; transitionTo(new CreatedState()); } @Override @EapMethod int getEapMethod() { return EAP_TYPE_TTLS; } @Override EapResult handleEapNotification(String tag, EapMessage message) { return EapStateMachine.handleNotification(tag, message); } /** * The created state verifies the start request before transitioning to phase 1 of EAP-TTLS * (RFC5281#7.1) */ protected class CreatedState extends EapMethodState { private final String mTAG = this.getClass().getSimpleName(); @Override public EapResult process(EapMessage message) { // TODO(b/160781895): Support decoding AVP's pre-tunnel in EAP-TTLS EapResult result = handleEapSuccessFailureNotification(mTAG, message); if (result != null) { return result; } DecodeResult decodeResult = mTypeDataDecoder.decodeEapTtlsRequestPacket(message.eapData.eapTypeData); if (!decodeResult.isSuccessfulDecode()) { LOG.e(mTAG, "Error parsing EAP-TTLS packet type data", decodeResult.eapError.cause); return decodeResult.eapError; } else if (!decodeResult.eapTypeData.isStart) { return new EapError( new EapInvalidRequestException( "Unexpected request received in EAP-TTLS: Received first request" + " without start bit set.")); } return transitionAndProcess(new HandshakeState(), message); } } /** * The handshake (phase 1) state builds the tunnel for tunneled EAP authentication in phase 2 * *
As per RFC5281#9.2.1, version negotiation occurs during the first exchange between client * and server. In other words, this is an implicit negotiation and is not handled independently. * In this case, the version will always be zero because that is the only currently supported * version of EAP-TTLS at the time of writing. The initiation of the handshake (RFC5281#7.1) is * the first response sent by the client. */ protected class HandshakeState extends CloseableTtlsMethodState { private final String mTAG = this.getClass().getSimpleName(); private static final int DEFAULT_VENDOR_ID = 0; /** * Processes a message for the handshake state * *
Note that this uses the EAP-Identity in the session config nested within EapTtlsConfig * which may be different than the identity in the top-level EapSessionConfig * * @param eapIdentifier the eap identifier for the response * @throws EapSilentException if an error occurs creating the eap message */ @VisibleForTesting byte[] buildEapIdentityResponseAvp(int eapIdentifier) throws EapSilentException { EapData eapData = new EapData( EAP_IDENTITY, mEapTtlsConfig.getInnerEapSessionConfig().getEapIdentity()); EapMessage eapMessage = new EapMessage(EAP_CODE_RESPONSE, eapIdentifier, eapData); return EapTtlsAvp.getEapMessageAvp(DEFAULT_AVP_VENDOR_ID, eapMessage.encode()).encode(); } /** * Handles premature EAP-Success and EAP-Failure messages in the handshake state. * *
In the case of an EAP-Success or EAP-Failure, the TLS session will be closed but an * EapError or EAP-Failure will be returned. For an invalid type error, the TLS session will * be closed and the state will transition to AwaitingClosure. * * @param message the EapMessage to be checked for early Success/Failure/Notification * messages * @return the EapResult generated from handling the give EapMessage, or null if the message * Type matches that of the current EAP method */ @Nullable @Override public EapResult handleEapSuccessFailure(EapMessage message) { if (message.eapCode == EAP_CODE_SUCCESS) { // EAP-SUCCESS is required to be the last EAP message sent during the EAP protocol, // so receiving a premature SUCCESS message is an unrecoverable error. mTlsSession.closeConnection(); return new EapError( new EapInvalidRequestException( "Received an EAP-Success in the handshake state")); } else if (message.eapCode == EAP_CODE_FAILURE) { mTlsSession.closeConnection(); transitionTo(new FinalState()); return new EapFailure(); } return null; } } /** * The tunnel state (phase 2) tunnels data produced by an inner EAP instance * *
The tunnel state creates an inner EAP instance via a new EAP state machine and handles * decryption and encryption of data using the previously established TLS tunnel (RFC5281#7.2) */ protected class TunnelState extends CloseableTtlsMethodState { private final String mTAG = this.getClass().getSimpleName(); @VisibleForTesting EapStateMachine mInnerEapStateMachine; @VisibleForTesting EapTtlsAvpDecoder mEapTtlsAvpDecoder = new EapTtlsAvpDecoder(); public TunnelState() { mInnerEapStateMachine = new EapStateMachine( mContext, mEapTtlsConfig.getInnerEapSessionConfig(), mSecureRandom); } /** * Processes a message for the inner tunneled authentication method. * *
If the result is an error state, the tunnel will be closed and a response or EapError * will be returned. Otherwise, null is returned to indicate that processing can continue. * * @param result a TlsResult encapsulating the results of an encrypt or decrypt operation * @param eapIdentifier the eap identifier from the latest message * @return an eap response if an error occurs or null if processing can continue */ @Nullable EapResult handleTunnelTlsResult(TlsResult result, int eapIdentifier) { switch (result.status) { case TLS_STATUS_SUCCESS: return null; case TLS_STATUS_CLOSED: Exception closeException = new SSLException( "TLS Session failed to encrypt or decrypt data" + " and was closed."); // Because the TLS session is already closed, we only transition to // ErroredAndAwaitingClosureState as the tls result has data to return from the // closure transitionTo(new ErroredAndAwaitingClosureState(new EapError(closeException))); return buildEapMessageResponse(mTAG, eapIdentifier, result.data); case TLS_STATUS_FAILURE: transitionTo(new FinalState()); return new EapError( new SSLException( "Failed to encrypt or decrypt message. Tunnel could not be" + " closed properly")); default: Exception illegalStateException = new IllegalStateException( "Received an unexpected TLS result with code " + result.status); return transitionToErroredAndAwaitingClosureState( mTAG, eapIdentifier, new EapError(illegalStateException)); } } /** * Handles EAP-Success and EAP-Failure messages in the tunnel state * *
Both success/failure messages are passed into the inner state machine for processing. * *
If an EAP-Success is returned by the inner state machine, it is discarded and a new * EAP-Success that contains the keying material generated during the TLS negotiation is * sent instead. * * @param message the EapMessage to be checked for Success/Failure * @return the EapResult generated from handling the give EapMessage, or null if the message * Type matches that of the current EAP method */ @Nullable @Override EapResult handleEapSuccessFailure(EapMessage message) { if (message.eapCode == EAP_CODE_SUCCESS || message.eapCode == EAP_CODE_FAILURE) { EapResult innerResult = mInnerEapStateMachine.process(message.encode()); if (innerResult instanceof EapSuccess) { EapTtlsKeyingMaterial keyingMaterial = mTlsSession.generateKeyingMaterial(); mTlsSession.closeConnection(); transitionTo(new FinalState()); if (!keyingMaterial.isSuccessful()) { return keyingMaterial.eapError; } return new EapSuccess(keyingMaterial.msk, keyingMaterial.emsk); } transitionTo(new FinalState()); mTlsSession.closeConnection(); return innerResult; } return null; } } /** * The closure state handles closure of the TLS session in EAP-TTLS * *
Note that this state is only entered following an error. If EAP authentication completes * successfully or fails, the tunnel is assumed to have implicitly closed. */ protected class ErroredAndAwaitingClosureState extends EapMethodState { private final String mTAG = this.getClass().getSimpleName(); private final EapError mEapError; /** * Initializes the closure state * *
The errored and awaiting closure state is an error state. If a server responds to a * close-notify, the data is processed and the EAP error which encapsulates the initial * error that caused the closure is returned * * @param eapError an EAP error that contains the error that initially caused a close to * occur */ public ErroredAndAwaitingClosureState(EapError eapError) { mEapError = eapError; } @Override public EapResult process(EapMessage message) { EapResult result = handleEapSuccessFailureNotification(mTAG, message); if (result != null) { return result; } DecodeResult decodeResult = mTypeDataDecoder.decodeEapTtlsRequestPacket(message.eapData.eapTypeData); if (!decodeResult.isSuccessfulDecode()) { LOG.e(mTAG, "Error parsing EAP-TTLS packet type data", decodeResult.eapError.cause); return decodeResult.eapError; } // if the server sent data, we process it and return an EapError. // A response is not required and is additionally unlikely as we have already sent the // closure-notify mTlsSession.processIncomingData(decodeResult.eapTypeData.data); return mEapError; } } /** * Transitions to the ErroredAndAwaitingClosureState and attempts to close the TLS tunnel * * @param tag the tag of the calling class * @param eapIdentifier the EAP identifier from the most recent EAP request * @param eapError the EAP error to return if closure fails * @return a closure notify TLS message or an EAP error if one cannot be generated */ @VisibleForTesting EapResult transitionToErroredAndAwaitingClosureState( String tag, int eapIdentifier, EapError eapError) { TlsResult closureResult = mTlsSession.closeConnection(); if (closureResult.status != TLS_STATUS_CLOSED) { LOG.e(tag, "Failed to close the TLS session"); transitionTo(new FinalState()); return eapError; } transitionTo(new ErroredAndAwaitingClosureState(eapError)); return buildEapMessageResponse( tag, eapIdentifier, EapTtlsTypeData.getEapTtlsTypeData( false /* isFragmented */, false /* start */, 0 /* version 0 */, closureResult.data.length, closureResult.data)); } /** * Verifies whether outbound fragmentation is in progress and constructs the next fragment if * necessary * * @param tag the tag for the calling class * @param eapTtlsRequest the request received from the server * @param eapIdentifier the eap identifier from the latest message * @return an eap response if the next fragment exists, or null if no fragmentation is in * progress */ @Nullable private EapResult getNextOutboundFragment( String tag, EapTtlsTypeData eapTtlsRequest, int eapIdentifier) { if (eapTtlsRequest.isAcknowledgmentPacket()) { if (mOutboundFragmentationHelper.hasRemainingFragments()) { FragmentationResult result = mOutboundFragmentationHelper.getNextOutboundFragment(); return buildEapMessageResponse( tag, eapIdentifier, EapTtlsTypeData.getEapTtlsTypeData( result.hasRemainingFragments, false /* start */, 0 /* version 0 */, 0 /* messageLength */, result.fragmentedData)); } else { return transitionToErroredAndAwaitingClosureState( tag, eapIdentifier, new EapError( new EapInvalidRequestException( "Received an ack but no packet was in the process of" + " being fragmented."))); } } else if (mOutboundFragmentationHelper.hasRemainingFragments()) { return transitionToErroredAndAwaitingClosureState( tag, eapIdentifier, new EapError( new EapInvalidRequestException( "Received a standard EAP-Request but was expecting an ack to a" + " fragment."))); } return null; } /** * Processes incoming data, and if necessary, assembles fragments * * @param tag the tag for the calling class * @param eapTtlsRequest the request received from the server * @param eapIdentifier the eap identifier from the latest message * @return an acknowledgment if the received data is a fragment, null if data is ready to * process */ @Nullable private EapResult handleInboundFragmentation( String tag, EapTtlsTypeData eapTtlsRequest, int eapIdentifier) { int fragmentationStatus = mInboundFragmentationHelper.assembleInboundMessage(eapTtlsRequest); switch (fragmentationStatus) { case FRAGMENTATION_STATUS_ASSEMBLED: return null; case FRAGMENTATION_STATUS_ACK: LOG.d(tag, "Packet is fragmented. Generating an acknowledgement response."); return buildEapMessageResponse( tag, eapIdentifier, EapTtlsAcknowledgement.getEapTtlsAcknowledgement()); case FRAGMENTATION_STATUS_INVALID: return transitionToErroredAndAwaitingClosureState( tag, eapIdentifier, new EapError( new EapTtlsParsingException( "Fragmentation failure: There was an error decoding the" + " fragmented request."))); default: return transitionToErroredAndAwaitingClosureState( tag, eapIdentifier, new EapError( new IllegalStateException( "Received an unknown fragmentation status when assembling" + " an inbound fragment: " + fragmentationStatus))); } } /** * Takes outbound data and assembles an EAP-Response. * *
The data will be fragmented if necessary * * @param tag the tag of the calling class * @param eapIdentifier the EAP identifier from the most recent EAP request * @param data the data used to build the EAP-TTLS type data * @return an EAP result that is either an EAP response or an EAP error */ private EapResult buildEapMessageResponse(String tag, int eapIdentifier, byte[] data) { // TODO(b/165668196): Modify outbound fragmentation helper to be per-message in EAP-TTLS mOutboundFragmentationHelper.setupOutboundFragmentation(data); FragmentationResult result = mOutboundFragmentationHelper.getNextOutboundFragment(); // As per RFC5281#9.2.2, an unfragmented packet may have the length bit set return buildEapMessageResponse( tag, eapIdentifier, EapTtlsTypeData.getEapTtlsTypeData( result.hasRemainingFragments, false /* start */, 0 /* version 0 */, data.length, result.fragmentedData)); } /** * Takes an already constructed EapTtlsTypeData and builds an EAP-Response * * @param tag the tag of the calling class * @param eapIdentifier the EAP identifier from the most recent EAP request * @param eapTtlsTypeData the type data to use in the EAP Response * @return an EAP result that is either an EAP response or an EAP error */ private EapResult buildEapMessageResponse( String tag, int eapIdentifier, EapTtlsTypeData eapTtlsTypeData) { try { EapData eapData = new EapData(getEapMethod(), eapTtlsTypeData.encode()); EapMessage eapMessage = new EapMessage(EAP_CODE_RESPONSE, eapIdentifier, eapData); return EapResponse.getEapResponse(eapMessage); } catch (EapSilentException ex) { LOG.e(tag, "Error building response EapMessage", ex); return new EapError(ex); } } /** * CloseableTtlsMethodState defines specific behaviour for handling EAP-Messages in EAP-TTLS * *
EAP-TTLS requires specific handling compared to what is defined in {@link EapMethodState} * as the tunnel needs to be closed. Furthermore, EAP-Success/EAP-Failure handling differs in * the tunnel state as it needs to be processed by the inner authentication method. * *
*/ abstract class CloseableTtlsMethodState extends EapMethodState { abstract EapResult handleEapSuccessFailure(EapMessage message); @Override @Nullable EapResult handleEapSuccessFailureNotification(String tag, EapMessage message) { EapResult eapResult = handleEapSuccessFailure(message); if (eapResult != null) { return eapResult; } if (message.eapData.eapType == EAP_NOTIFICATION) { return handleEapNotification(tag, message); } else if (message.eapData.eapType != EAP_TYPE_TTLS) { EapError eapError = new EapError( new EapInvalidRequestException( "Expected EAP Type " + getEapMethod() + ", received " + message.eapData.eapType)); return transitionToErroredAndAwaitingClosureState( tag, message.eapIdentifier, eapError); } return null; } } }