/*
* Copyright (C) 2009 Google Inc. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.polo.pairing;
import com.google.polo.encoding.HexadecimalEncoder;
import com.google.polo.encoding.SecretEncoder;
import com.google.polo.exception.BadSecretException;
import com.google.polo.exception.NoConfigurationException;
import com.google.polo.exception.PoloException;
import com.google.polo.exception.ProtocolErrorException;
import com.google.polo.pairing.PairingListener.LogLevel;
import com.google.polo.pairing.message.ConfigurationMessage;
import com.google.polo.pairing.message.EncodingOption;
import com.google.polo.pairing.message.OptionsMessage;
import com.google.polo.pairing.message.OptionsMessage.ProtocolRole;
import com.google.polo.pairing.message.PoloMessage;
import com.google.polo.pairing.message.PoloMessage.PoloMessageType;
import com.google.polo.pairing.message.SecretAckMessage;
import com.google.polo.pairing.message.SecretMessage;
import com.google.polo.wire.PoloWireInterface;
import java.io.IOException;
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;
import java.security.cert.Certificate;
import java.util.Arrays;
import java.util.concurrent.BlockingQueue;
import java.util.concurrent.LinkedBlockingQueue;
import java.util.concurrent.TimeUnit;
/**
* Implements the logic of and holds state for a single occurrence of the
* pairing protocol.
* <p>
* This abstract class implements the logic common to both client and server
* perspectives of the protocol. Notably, the 'pairing' phase of the
* protocol has the same logic regardless of client/server status
* ({link PairingSession#doPairingPhase()}). Other phases of the protocol are
* specific to client/server status; see {@link ServerPairingSession} and
* {@link ClientPairingSession}.
* <p>
* The protocol is initiated by called
* {@link PairingSession#doPair(PairingListener)}
* The listener implementation is responsible for showing the shared secret
* to the user
* ({@link PairingListener#onPerformOutputDeviceRole(PairingSession, byte[])}),
* or in accepting the user input
* ({@link PairingListener#onPerformInputDeviceRole(PairingSession)}),
* depending on the role negotiated during initialization.
* <p>
* When operating in the input role, the session will block execution after
* calling {@link PairingListener#onPerformInputDeviceRole(PairingSession)} to
* wait for the secret. The listener, or some activity resulting from it, must
* publish the input secret to the session via
* {@link PairingSession#setSecret(byte[])}.
*/
public abstract class PairingSession {
protected enum ProtocolState {
STATE_UNINITIALIZED,
STATE_INITIALIZING,
STATE_CONFIGURING,
STATE_PAIRING,
STATE_SUCCESS,
STATE_FAILURE,
}
/**
* Enable extra verbose debug logging.
*/
private static final boolean DEBUG_VERBOSE = false;
/**
* Controls whether to verify the secret portion of the SecretAck message.
* <p>
* NOTE(mikey): One implementation does not send the secret back in
* the SecretAck. This should be fixed, but in the meantime it is not
* essential that we verify it, since *any* acknowledgment from the
* sender is enough to indicate protocol success.
*/
private static final boolean VERIFY_SECRET_ACK = false;
/**
* Timeout, in milliseconds, for polling the secret queue for a response from
* the listener. This timeout is relevant only to periodically check the
* mAbort flag to terminate the protocol, which is set by calling teardown().
*/
private static final int SECRET_POLL_TIMEOUT_MS = 500;
/**
* Performs the initialization phase of the protocol.
*
* @throws PoloException if a protocol error occurred
* @throws IOException if an error occurred in input/output
*/
protected abstract void doInitializationPhase()
throws PoloException, IOException;
/**
* Performs the configuration phase of the protocol.
*
* @throws PoloException if a protocol error occurred
* @throws IOException if an error occurred in input/output
*/
protected abstract void doConfigurationPhase()
throws PoloException, IOException;
/**
* Internal representation of challenge-response.
*/
protected PoloChallengeResponse mChallenge;
/**
* Implementation of the transport layer.
*/
private final PoloWireInterface mProtocol;
/**
* Context for the pairing session.
*/
protected final PairingContext mPairingContext;
/**
* Local endpoint's supported options.
* <p>
* If this session is acting as a server, this message will be sent to the
* client in the Initialization phase. If acting as a client, this member is
* used to store local options and compute the Configuration message (but
* is never transmitted directly).
*/
protected OptionsMessage mLocalOptions;
/**
* Encoding scheme used for the session.
*/
protected SecretEncoder mEncoder;
/**
* Name of the service being paired.
*/
protected String mServiceName;
/**
* Name of the peer.
*/
protected String mPeerName;
/**
* Configuration message for current session.
* <p>
* This is computed by the client and sent to the server.
*/
protected ConfigurationMessage mSessionConfig;
/**
* Listener that will receive callbacks upon protocol events.
*/
protected PairingListener mListener;
/**
* Internal state of the pairing session.
*/
protected ProtocolState mState;
/**
* Threadsafe queue for receiving the messages sent by peer, user-given secret
* from the listener, or exceptions caught by async threads.
*/
protected BlockingQueue<QueueMessage> mMessageQueue;
/**
* Flag set when the session should be aborted.
*/
protected boolean mAbort;
/**
* Reader thread.
*/
private final Thread mThread;
/**
* Constructor.
*
* @param protocol the wire interface to operate against
* @param pairingContext a PairingContext for the session
*/
public PairingSession(PoloWireInterface protocol,
PairingContext pairingContext) {
mProtocol = protocol;
mPairingContext = pairingContext;
mState = ProtocolState.STATE_UNINITIALIZED;
mMessageQueue = new LinkedBlockingQueue<QueueMessage>();
Certificate clientCert = mPairingContext.getClientCertificate();
Certificate serverCert = mPairingContext.getServerCertificate();
mChallenge = new PoloChallengeResponse(clientCert, serverCert,
new PoloChallengeResponse.DebugLogger() {
public void debug(String message) {
logDebug(message);
}
public void verbose(String message) {
if (DEBUG_VERBOSE) {
logDebug(message);
}
}
});
mLocalOptions = new OptionsMessage();
if (mPairingContext.isServer()) {
mLocalOptions.setProtocolRolePreference(ProtocolRole.DISPLAY_DEVICE);
} else {
mLocalOptions.setProtocolRolePreference(ProtocolRole.INPUT_DEVICE);
}
mThread = new Thread(new Runnable() {
public void run() {
logDebug("Starting reader");
try {
while (!mAbort) {
try {
PoloMessage message = mProtocol.getNextMessage();
logDebug("Received: " + message.getClass());
mMessageQueue.put(new QueueMessage(message));
} catch (PoloException exception) {
logDebug("Exception while getting message: " + exception);
mMessageQueue.put(new QueueMessage(exception));
break;
} catch (IOException exception) {
logDebug("Exception while getting message: " + exception);
mMessageQueue.put(new QueueMessage(new PoloException(exception)));
break;
}
}
} catch (InterruptedException ie) {
logDebug("Interrupted: " + ie);
} finally {
logDebug("Reader is done");
}
}
});
mThread.start();
}
public void teardown() {
try {
// Send any error.
mProtocol.sendErrorMessage(new Exception());
mPairingContext.getPeerInputStream().close();
mPairingContext.getPeerOutputStream().close();
} catch (IOException e) {
// oh well.
}
// Unblock the blocking wait on the secret queue.
mAbort = true;
mThread.interrupt();
}
protected void log(LogLevel level, String message) {
if (mListener != null) {
mListener.onLogMessage(level, message);
}
}
/**
* Logs a debug message to the active listener.
*/
public void logDebug(String message) {
log(LogLevel.LOG_DEBUG, message);
}
/**
* Logs an informational message to the active listener.
*/
public void logInfo(String message) {
log(LogLevel.LOG_INFO, message);
}
/**
* Logs an error message to the active listener.
*/
public void logError(String message) {
log(LogLevel.LOG_ERROR, message);
}
/**
* Adds an encoding to the supported input role encodings. This method can
* only be called before the session has started.
* <p>
* If no input encodings have been added, then this endpoint cannot act as
* the input device protocol role.
*
* @param encoding the {@link EncodingOption} to add
*/
public void addInputEncoding(EncodingOption encoding) {
if (mState != ProtocolState.STATE_UNINITIALIZED) {
throw new IllegalStateException("Cannot add encodings once session " +
"has been started.");
}
// Legal values of GAMMALEN must be:
// - an even number of bytes
// - at least 2 bytes
if ((encoding.getSymbolLength() < 2) ||
((encoding.getSymbolLength() % 2) != 0)) {
throw new IllegalArgumentException("Bad symbol length: " +
encoding.getSymbolLength());
}
mLocalOptions.addInputEncoding(encoding);
}
/**
* Adds an encoding to the supported output role encodings. This method can
* only be called before the session has started.
* <p>
* If no output encodings have been added, then this endpoint cannot act as
* the output device protocol role.
*
* @param encoding the {@link EncodingOption} to add
*/
public void addOutputEncoding(EncodingOption encoding) {
if (mState != ProtocolState.STATE_UNINITIALIZED) {
throw new IllegalStateException("Cannot add encodings once session " +
"has been started.");
}
mLocalOptions.addOutputEncoding(encoding);
}
/**
* Changes the internal state.
*
* @param newState the new state
*/
private void setState(ProtocolState newState) {
logInfo("New state: " + newState);
mState = newState;
}
/**
* Runs the pairing protocol.
* <p>
* Supported input and output encodings must be specified
* first, using
* {@link PairingSession#addInputEncoding(EncodingOption)} and
* {@link PairingSession#addOutputEncoding(EncodingOption)},
* respectively.
*
* @param listener the {@link PairingListener} for the session
* @return {@code true} if pairing was successful
*/
public boolean doPair(PairingListener listener) {
mListener = listener;
mListener.onSessionCreated(this);
if (mPairingContext.isServer()) {
logDebug("Protocol started (SERVER mode)");
} else {
logDebug("Protocol started (CLIENT mode)");
}
logDebug("Local options: " + mLocalOptions.toString());
Certificate clientCert = mPairingContext.getClientCertificate();
if (DEBUG_VERBOSE) {
logDebug("Client certificate:");
logDebug(clientCert.toString());
}
Certificate serverCert = mPairingContext.getServerCertificate();
if (DEBUG_VERBOSE) {
logDebug("Server certificate:");
logDebug(serverCert.toString());
}
boolean success = false;
try {
setState(ProtocolState.STATE_INITIALIZING);
doInitializationPhase();
setState(ProtocolState.STATE_CONFIGURING);
doConfigurationPhase();
setState(ProtocolState.STATE_PAIRING);
doPairingPhase();
success = true;
} catch (ProtocolErrorException e) {
logDebug("Remote protocol failure: " + e);
} catch (PoloException e) {
try {
logDebug("Local protocol failure, attempting to send error: " + e);
mProtocol.sendErrorMessage(e);
} catch (IOException e1) {
logDebug("Error message send failed");
}
} catch (IOException e) {
logDebug("IOException: " + e);
}
if (success) {
setState(ProtocolState.STATE_SUCCESS);
} else {
setState(ProtocolState.STATE_FAILURE);
}
mListener.onSessionEnded(this);
return success;
}
/**
* Returns {@code true} if the session is in a terminal state (success or
* failure).
*/
public boolean hasCompleted() {
switch (mState) {
case STATE_SUCCESS:
case STATE_FAILURE:
return true;
default:
return false;
}
}
public boolean hasSucceeded() {
return mState == ProtocolState.STATE_SUCCESS;
}
public String getServiceName() {
return mServiceName;
}
/**
* Sets the secret, as received from a user. This method is only meaningful
* when the endpoint is acting as the input device role.
*
* @param secret the secret, as a byte sequence
* @return {@code true} if the secret was captured
*/
public boolean setSecret(byte[] secret) {
if (!isInputDevice()) {
throw new IllegalStateException("Secret can only be set for " +
"input role session.");
} else if (mState != ProtocolState.STATE_PAIRING) {
throw new IllegalStateException("Secret can only be set while " +
"in pairing state.");
}
return mMessageQueue.offer(new QueueMessage(secret));
}
/**
* Executes the pairing phase of the protocol.
*
* @throws PoloException if a protocol error occurred
* @throws IOException if an error in the input/output occurred
*/
protected void doPairingPhase() throws PoloException, IOException {
if (isInputDevice()) {
new Thread(new Runnable() {
public void run() {
logDebug("Calling listener for user input...");
try {
mListener.onPerformInputDeviceRole(PairingSession.this);
} catch (PoloException exception) {
logDebug("Sending exception: " + exception);
mMessageQueue.offer(new QueueMessage(exception));
} finally {
logDebug("Listener finished.");
}
}
}).start();
logDebug("Waiting for secret from Listener or ...");
QueueMessage message = waitForMessage();
if (message == null || !message.hasSecret()) {
throw new PoloException(
"Illegal state - no secret available: " + message);
}
byte[] userGamma = message.mSecret;
if (userGamma == null) {
throw new PoloException("Invalid secret.");
}
boolean match = mChallenge.checkGamma(userGamma);
if (match != true) {
throw new BadSecretException("Secret failed local check.");
}
byte[] userNonce = mChallenge.extractNonce(userGamma);
byte[] genAlpha = mChallenge.getAlpha(userNonce);
logDebug("Sending Secret reply...");
SecretMessage secretMessage = new SecretMessage(genAlpha);
mProtocol.sendMessage(secretMessage);
logDebug("Waiting for SecretAck...");
SecretAckMessage secretAck =
(SecretAckMessage) getNextMessage(PoloMessageType.SECRET_ACK);
if (VERIFY_SECRET_ACK) {
byte[] inbandAlpha = secretAck.getSecret();
if (!Arrays.equals(inbandAlpha, genAlpha)) {
throw new BadSecretException("Inband secret did not match. " +
"Expected [" + PoloUtil.bytesToHexString(genAlpha) +
"], got [" + PoloUtil.bytesToHexString(inbandAlpha) + "]");
}
}
} else {
int symbolLength = mSessionConfig.getEncoding().getSymbolLength();
int nonceLength = symbolLength / 2;
int bytesNeeded = nonceLength / mEncoder.symbolsPerByte();
byte[] nonce = new byte[bytesNeeded];
SecureRandom random;
try {
random = SecureRandom.getInstance("SHA1PRNG");
} catch (NoSuchAlgorithmException e) {
throw new PoloException(e);
}
random.nextBytes(nonce);
// Display gamma
logDebug("Calling listener to display output...");
byte[] gamma = mChallenge.getGamma(nonce);
mListener.onPerformOutputDeviceRole(this, gamma);
logDebug("Waiting for Secret...");
SecretMessage secretMessage =
(SecretMessage) getNextMessage(PoloMessageType.SECRET);
byte[] localAlpha = mChallenge.getAlpha(nonce);
byte[] inbandAlpha = secretMessage.getSecret();
boolean matched = Arrays.equals(localAlpha, inbandAlpha);
if (!matched) {
throw new BadSecretException("Inband secret did not match. " +
"Expected [" + PoloUtil.bytesToHexString(localAlpha) +
"], got [" + PoloUtil.bytesToHexString(inbandAlpha) + "]");
}
logDebug("Sending SecretAck...");
byte[] genAlpha = mChallenge.getAlpha(nonce);
SecretAckMessage secretAck = new SecretAckMessage(inbandAlpha);
mProtocol.sendMessage(secretAck);
}
}
public SecretEncoder getEncoder() {
return mEncoder;
}
/**
* Sets the current session's configuration from a
* {@link ConfigurationMessage}.
*
* @param message the session's config
* @throws PoloException if the config was not valid for some reason
*/
protected void setConfiguration(ConfigurationMessage message)
throws PoloException {
if (message == null || message.getEncoding() == null) {
throw new NoConfigurationException("No configuration is possible.");
}
if (message.getEncoding().getSymbolLength() % 2 != 0) {
throw new PoloException("Symbol length must be even.");
}
if (message.getEncoding().getSymbolLength() < 2) {
throw new PoloException("Symbol length must be >= 2 symbols.");
}
switch (message.getEncoding().getType()) {
case ENCODING_HEXADECIMAL:
mEncoder = new HexadecimalEncoder();
break;
default:
throw new PoloException("Unsupported encoding type.");
}
mSessionConfig = message;
}
/**
* Returns the role of this endpoint in the current session.
*/
protected ProtocolRole getLocalRole() {
assert (mSessionConfig != null);
if (!mPairingContext.isServer()) {
return mSessionConfig.getClientRole();
} else {
return (mSessionConfig.getClientRole() == ProtocolRole.DISPLAY_DEVICE) ?
ProtocolRole.INPUT_DEVICE : ProtocolRole.DISPLAY_DEVICE;
}
}
/**
* Returns {@code true} if this endpoint will act as the input device.
*/
protected boolean isInputDevice() {
return (getLocalRole() == ProtocolRole.INPUT_DEVICE);
}
/**
* Returns {@code true} if peer's name is set.
*/
public boolean hasPeerName() {
return mPeerName != null;
}
/**
* Returns peer's name if set, {@code null} otherwise.
*/
public String getPeerName() {
return mPeerName;
}
protected PoloMessage getNextMessage(PoloMessageType type)
throws PoloException {
QueueMessage message = waitForMessage();
if (message != null && message.hasPoloMessage()) {
if (!type.equals(message.mPoloMessage.getType())) {
throw new PoloException(
"Unexpected message type: " + message.mPoloMessage.getType());
}
return message.mPoloMessage;
}
throw new PoloException("Invalid state - expected polo message");
}
/**
* Returns next queued message. The method blocks until the secret or the
* polo message is available.
*
* @return the queued message, or null on error
* @throws PoloException if exception was queued
*/
private QueueMessage waitForMessage() throws PoloException {
while (!mAbort) {
try {
QueueMessage message = mMessageQueue.poll(SECRET_POLL_TIMEOUT_MS,
TimeUnit.MILLISECONDS);
if (message != null) {
if (message.hasPoloException()) {
throw new PoloException(message.mPoloException);
}
return message;
}
} catch (InterruptedException e) {
break;
}
}
// Aborted or interrupted.
return null;
}
/**
* Sends message to the peer.
*
* @param message the message
* @throws PoloException if a protocol error occurred
* @throws IOException if an error in the input/output occurred
*/
protected void sendMessage(PoloMessage message)
throws IOException, PoloException {
mProtocol.sendMessage(message);
}
/**
* Queued message, that can carry information about secret, next read message,
* or exception caught by reader or input threads.
*/
private static final class QueueMessage {
final PoloMessage mPoloMessage;
final PoloException mPoloException;
final byte[] mSecret;
private QueueMessage(
PoloMessage message, byte[] secret, PoloException exception) {
int nonNullCount = 0;
if (message != null) {
++nonNullCount;
}
mPoloMessage = message;
if (exception != null) {
assert(nonNullCount == 0);
++nonNullCount;
}
mPoloException = exception;
if (secret != null) {
assert(nonNullCount == 0);
++nonNullCount;
}
mSecret = secret;
assert(nonNullCount == 1);
}
public QueueMessage(PoloMessage message) {
this(message, null, null);
}
public QueueMessage(byte[] secret) {
this(null, secret, null);
}
public QueueMessage(PoloException exception) {
this(null, null, exception);
}
public boolean hasPoloMessage() {
return mPoloMessage != null;
}
public boolean hasPoloException() {
return mPoloException != null;
}
public boolean hasSecret() {
return mSecret != null;
}
@Override
public String toString() {
StringBuilder builder = new StringBuilder("QueueMessage(");
if (hasPoloMessage()) {
builder.append("poloMessage = " + mPoloMessage);
}
if (hasPoloException()) {
builder.append("poloException = " + mPoloException);
}
if (hasSecret()) {
builder.append("secret = " + Arrays.toString(mSecret));
}
return builder.append(")").toString();
}
}
}