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); }