From 0fa5d4094add0f4fc20a53ce2d54979ddf8537b8 Mon Sep 17 00:00:00 2001 From: Hai Brenner Date: Sun, 13 Mar 2016 15:35:58 +0200 Subject: [PATCH] yet another take on the VB interfaces. Interfaces were now shortened even more. Many changes were made according to Arbel's instructions. Most important change is now that the controller passes ALL questions for UI to ask voter, instead of chunks of questions and back-and-forth messages between the controller and UI which were always quite redundant. --- .../meerkat/voting/BallotOutputDevice.java | 34 +++++--- .../java/meerkat/voting/StorageManager.java | 16 +++- .../main/java/meerkat/voting/VotingBooth.java | 37 ++++++--- .../meerkat/voting/VotingBoothEncryptor.java | 28 ++++++- .../meerkat/voting/VotingBoothResult.java | 17 ---- .../java/meerkat/voting/VotingBoothUI.java | 79 ++++++++++--------- 6 files changed, 131 insertions(+), 80 deletions(-) delete mode 100644 voting-booth/src/main/java/meerkat/voting/VotingBoothResult.java diff --git a/voting-booth/src/main/java/meerkat/voting/BallotOutputDevice.java b/voting-booth/src/main/java/meerkat/voting/BallotOutputDevice.java index 39eed6a..0199523 100644 --- a/voting-booth/src/main/java/meerkat/voting/BallotOutputDevice.java +++ b/voting-booth/src/main/java/meerkat/voting/BallotOutputDevice.java @@ -4,24 +4,36 @@ import com.google.common.util.concurrent.FutureCallback; import meerkat.protobuf.Voting.*; /** - * Created by hai on 15/02/16. + * An interface for the device in which we output the ballots. + * Probably going to be a printer or an ethernet connection, or both. */ public interface BallotOutputDevice { /** - * - * @param requestId - * @param encryptedBallot - * @param callback + * Output the encrypted ballot. This is a commitment before voter chooses casting or auditing + * @param encryptedBallot - the encrypted ballot to commit to + * @param callback - a callback object through which to return a success flag */ - void commitToBallot(int requestId, EncryptedBallot encryptedBallot, - FutureCallback> callback); + public void commitToBallot(EncryptedBallot encryptedBallot, FutureCallback callback); - void audit(int requestId, EncryptedBallot encryptedBallot, BallotSecrets ballotSecrets, - FutureCallback> callback); + /** + * Voter chose 'audit'. Output the ballot secrets to prove correctness of the encryption. + * @param encryptedBallot - the encrypted ballot + * @param ballotSecrets - the secrtes of the encryption + * @param callback - a callback object through which to return a success flag + */ + public void audit(EncryptedBallot encryptedBallot, BallotSecrets ballotSecrets, FutureCallback callback); - void castBallot(int requestId, FutureCallback> callback); + /** + * Voter chose 'cast'. Finalize the ballot for use in the polling station + * @param callback - a callback object through which to return a success flag + */ + public void castBallot(FutureCallback callback); - void cancelBallot(int requestId, FutureCallback> callback); + /** + * Cancelling the current ballot. This clears the state of the OutputDevice if the implementation has any such state. + * @param callback - a callback object through which to return a success flag + */ + public void cancelBallot(FutureCallback callback); } diff --git a/voting-booth/src/main/java/meerkat/voting/StorageManager.java b/voting-booth/src/main/java/meerkat/voting/StorageManager.java index c05f383..0fd18ca 100644 --- a/voting-booth/src/main/java/meerkat/voting/StorageManager.java +++ b/voting-booth/src/main/java/meerkat/voting/StorageManager.java @@ -1,13 +1,21 @@ package meerkat.voting; -import meerkat.protobuf.Voting; +import meerkat.protobuf.Voting.*; /** - * Created by hai on 23/02/16. + * An interface for the storage component of the voting booth */ public interface StorageManager { - boolean detectAdminHardwareKey(); + /** + * Detect whether an administration key is inserted to the machine. This determines if we gointo the set-up flow or the voting session flow. + * @return True is a hardware key is inserted. False if not. + */ + public boolean isAdminHardwareKeyInserted(); - Voting.ElectionParams readElectionParams (); + /** + * load the election params from a file. + * @return the current election params + */ + public ElectionParams readElectionParams (); } diff --git a/voting-booth/src/main/java/meerkat/voting/VotingBooth.java b/voting-booth/src/main/java/meerkat/voting/VotingBooth.java index 9182eca..a2b211b 100644 --- a/voting-booth/src/main/java/meerkat/voting/VotingBooth.java +++ b/voting-booth/src/main/java/meerkat/voting/VotingBooth.java @@ -3,25 +3,42 @@ package meerkat.voting; import meerkat.protobuf.Voting.*; /** - * Created by hai on 23/02/16. + * An interface for the controller component of the voting booth */ public interface VotingBooth { - void setComponenets (BallotOutputDevice outputDevice, + /** + * setting all the different components of the Voting Booth to be recognized by this controller + * @param outputDevice the ballot output device. Naturally a printer and/or ethernet connection + * @param vbEncryptor the encryption module + * @param vbUI User interface in which the voter chooses his answers + * @param vbStorageManager storage component for handling files and USB sticks + */ + public void setComponenets (BallotOutputDevice outputDevice, VotingBoothEncryptor vbEncryptor, VotingBoothUI vbUI, StorageManager vbStorageManager); - void initBoothParams (BoothParams boothParams); + /** + * initialize using the BoothParams protobuf + * @param boothParams + */ + public void initBoothParams (BoothParams boothParams); - void initElectionParams (ElectionParams electionParams); + /** + * set the voting questions + * @param questions + */ + public void setBallotQuestions (BallotQuestion[] questions); - // this function is synchronous - void start (); + /** + * a synchronous function. Starts running the controller component, and basically run the whole system for voting + */ + public void run (); - - // messages from Admin Console (If there is such one) - // this function is asynchronous - void shutDown(); + /** + * an asynchronous call from Admin Console (If there is such one implemented) to shut down the system + */ + public void shutDown(); } diff --git a/voting-booth/src/main/java/meerkat/voting/VotingBoothEncryptor.java b/voting-booth/src/main/java/meerkat/voting/VotingBoothEncryptor.java index 60384e9..cc9b7bc 100644 --- a/voting-booth/src/main/java/meerkat/voting/VotingBoothEncryptor.java +++ b/voting-booth/src/main/java/meerkat/voting/VotingBoothEncryptor.java @@ -1,13 +1,37 @@ package meerkat.voting; +import com.sun.org.apache.xml.internal.security.encryption.EncryptedType; import meerkat.protobuf.Voting.*; /** - * Created by hai on 23/02/16. + * An interface for the encryptor component of the voting booth */ public interface VotingBoothEncryptor { - void encrypt (PlaintextBallot plaintextBallot); + /** + * A simple class for pairing EncrypedBallot together with its matching BallotSecrets + */ + public class EncryptionAndSecrets { + private final EncryptedBallot encryptedBallot; + private final BallotSecrets secrets; + + public EncryptionAndSecrets (EncryptedBallot encryptedBallot, BallotSecrets secrets) { + this.encryptedBallot = encryptedBallot; + this.secrets = secrets; + } + + public EncryptedBallot getEncryptedBallot () { return encryptedBallot; } + public BallotSecrets getSecrets() { return secrets; } + } + + + /** + * This function encrypts the plaintext ballot using the booth's keys + * @param plaintextBallot - all plaintext ballot info of the voter + * @return an encryption of the ballot + */ + public EncryptionAndSecrets encrypt (PlaintextBallot plaintextBallot); + //TODO: probably needs some key generation methods as well } diff --git a/voting-booth/src/main/java/meerkat/voting/VotingBoothResult.java b/voting-booth/src/main/java/meerkat/voting/VotingBoothResult.java deleted file mode 100644 index 6702ce9..0000000 --- a/voting-booth/src/main/java/meerkat/voting/VotingBoothResult.java +++ /dev/null @@ -1,17 +0,0 @@ -package meerkat.voting; - -/** - * Created by hai on 02/03/16. - */ -public class VotingBoothResult { - private final int m_requestId; - private final T m_result; - - public int getRequestId () { return m_requestId; } - public T getResult () { return m_result; } - - public VotingBoothResult (int requestId, T result) { - m_requestId = requestId; - m_result = result; - } -} diff --git a/voting-booth/src/main/java/meerkat/voting/VotingBoothUI.java b/voting-booth/src/main/java/meerkat/voting/VotingBoothUI.java index 0726a09..78ccfef 100644 --- a/voting-booth/src/main/java/meerkat/voting/VotingBoothUI.java +++ b/voting-booth/src/main/java/meerkat/voting/VotingBoothUI.java @@ -4,61 +4,68 @@ import com.google.common.util.concurrent.FutureCallback; import meerkat.protobuf.Voting.*; /** - * Created by hai on 23/02/16. + * An interface for the user interface component of the voting booth */ public interface VotingBoothUI { - enum VoterQuestionChoice { - ANSWERED, - SKIP, - BACK, - CANCEL - } - - class VoterQuestionResponse { - private final VoterQuestionChoice m_choice; - private final String m_answer; - - public VoterQuestionResponse(VoterQuestionChoice choice, String answer) { - assert ((choice == VoterQuestionChoice.ANSWERED && answer != null) || - (choice != VoterQuestionChoice.ANSWERED && answer == null)); - m_choice = choice; - m_answer = answer; - } - - public VoterQuestionChoice getChoice () { return m_choice; } - public String getAnswer () { return m_answer; } - } - - enum FinalizeBallotChoice { CAST, AUDIT } - // Voter scenario methods - void newVoter (int requestId, FutureCallback> callback); + /** + * Starts a new session for a voter. Presents whatever initial info is decided to show at the beginning + * @param callback - a boolean future callback to return success when done + */ + public void startNewVoterSession (FutureCallback callback); - void chooseChannel (int requestId, BallotQuestion question, FutureCallback> callback); + /** + * Present a question to the voter to decide on his voting channel. + * @param question a question to determine the right voting channel for this voter + * @param callback that's where we store the channel for the current voter + */ + public void chooseChannel (BallotQuestion question, FutureCallback callback); - void askVoterQuestion (int requestId, int questionNumber, BallotQuestion question, - FutureCallback> callback); + /** + * Presents the set of questions to the voter. Collect all his responses. + * @param questions all ballot questions to present to the voter + * @param callback the responses to the questions collected by the UI, to send back to the controller. Responses are null if voter chose to cancel session + */ + public void askVoterQuestions (BallotQuestion[] questions, FutureCallback callback); - void castOrAudit (int requestId, FutureCallback> callback); + /** + * Get a response from the voter on how to finalize the ballot. + * @param callback the returned choice of how to finalize the ballot + */ + public void castOrAudit (FutureCallback callback); - void showWaitForFinishScreen (int requestId, FutureCallback> callback); // Admin scenario methods //TODO: the admin scenario still needs some more thinking + /** + * present a wait-for-finish screen to the voter + * @param message a message to show the user on the UI device while waiting + * @param callback a success return value of the wait (cancelling returns false) + */ + public void askVoterToWaitForFinish (String message, FutureCallback callback); - // bad thing happened scenario - void showErrorMessageAndHalt (int requestId, String errorMessage, - FutureCallback> callback); + /** + * show a fatal error message in the UI. Halts system. Waits for administrator interrupt or reset + * @param errorMessage message to show in UI device + * @param callback returns interrupt + */ + public void showErrorMessageAndHalt (String errorMessage, FutureCallback callback); - void showErrorMessageWithButtons (int requestId, String errorMessage, String[] buttonLabels, - FutureCallback> callback); + /** + * show an error message and let user press his chosen button for continuation + * @param errorMessage message to show in UI device + * @param buttonLabels labels for buttons to present to voter + * @param callback the number of the selected button + */ + public void showErrorMessageWithButtons (String errorMessage, String[] buttonLabels, + FutureCallback callback); }