##############################################################################
##
##  CS642 Project E-Voting
##
##  Jichuan Chang   chang@cs.wisc.edu
##   Andy Herger    ajherger@wisc.edu
## 
##############################################################################

##############################################################################
## Demonstration Procedure:
##############################################################################

At the higher-level, 4 scripts are used to test the voting system:

(1) test_voting.sh              Normal voting, should have no complaint
(2) test_more.sh                CTF will report more vote, CLA complains
(3) test_less.sh                CTF will report less vote, one voter complains
(4) test_auth.sh                One voter has invalid certificate, whose vote 
                                won't be counted.

To test them, you need to do the following three things:
(1) first run './kill_all_threads.sh' to stop previously running threads for 
    E-voting system. 
(2) Then start one of the scripts, wait for a while, until "Voter XXXX done 
    voting" messages are printed.
(3) Type './check_result.sh' to check the result.


A detailed procedure to demonstrate the voting process is as follows:
(0) Edit the Client_List file,  which contains the IDs for possible voters
			(in real-world, this should be a database of registered voters).
(1) ./gen_keys.sh               Create certificates and trustStores 
                                (only need to run once)
(2) ./run_server.sh             Start CTF first, and then CLA server
(3) ./run_client.sh CID V       Start a voter with CID and will vote V
                                Each client will keep its voting result, 
                                and later verify the published result.

 ... (3) can be repeated for different voters ... 

(4) ./check_result.sh           Create a flag file, to stop the voting. 
                                If CTF sees this file, it will publish the 
                                voting result into file "voteResult.txt".
                                Then CLA and Voters will check result, and 
                                complain if sth. is wrong (into *.complaint. 
(5) ./kill_all_threads.sh       To stop all processes if any exists still.

##############################################################################
## Connection/authentication Relationship: 
##############################################################################

WHO      TRUST_LIST        ConnectServer/port(auth)    AcceptClient/port(auth)
===============================================================================
CLA      CTF, Voter        CTF/3347 (serverAuth)       Voter/3346 (clientAuth)
-------------------------------------------------------------------------------
CTF      CLA                                           CLA/3347   (clientAuth)
                                                    Voter/3348 (no clientAuth)
-------------------------------------------------------------------------------
Voter    CLA, CTF          CLA/3346 (serverAuth)
                           CTF/3348 (serverAuth)
===============================================================================

To authenticate a server (CLA, or CTF), the client will check the certificate
it received from the server. If the "CN" field in the certificate matches the
server's name, then authentication succeed.

To authenticate a voter, the CLA will check if the ID in the "ticket_request" 
matches the "CN" field in the voter's certificate.

##############################################################################
## XML DTD:
##############################################################################
(1) ticket_request.dtd        
                            V -> CLA
                            Message = (id)
    
(2) ticket_reply.dtd        CLA -> V
                            CLA -> CTF
                            Message = (ticket)

(3) vote.dtd                V -> CTF
                            Message = (ticket, token, vote)

##############################################################################
## Java Source Code:
##############################################################################
CTF_Server.java 
    -- implements the CTF_Server, collects tickets, votes and publishes result 
    -- authenticates the CLA_Server
    -- receives tickets from the CLA_Server
    -- receives votes from the voters (notifies the voter if ticket invalid)
    -- stops voting upon user-command, using a thread to monitor user-action
    -- publishes the result into a file, write a new flag file to tell others
        that the voting is finished.

CLA_Server.java
    -- implements the CLA_Server
    -- authenticates voters
    -- assigns tickets upon client request, use BigInteger to generate ticket
    -- after result is published, check if there is invalid votes

CLA_Client.java
    -- implements the CLA_Client, authenticates CTF and sends tickets to CTF
    -- send(ticket) called by CLA_Server.java 

Voter.java
    -- implements the voter, authenticates CLA and CTF
    -- requests from CLA its ticket
    -- sends his/her vote to the CTF (read its vote from command line)
    -- checks the voting result after result is published

Other Helper Java Files:
    DOMProcessor.java
    Parser.java
    WrappedInputStream.java
    WrappedOutputStream.java
    XML.java
    XMLSocketThread.java

##############################################################################
## Scripts: to manage keys and certificates, and start client and servers
##############################################################################
cla_cert.sh         Create CLA certificate, store to CTF & clients trust store
ctf_cert.sh         Create CTF certificate, store to CLA & clients trust store
client_cert.sh      Create certificate for client with given ID ($1), store to
                    CTF & CLA trust store
delete_certs.sh     Delete all certificates, keyStores and trustStores
gen_keys.sh         The main scripts to generate certificates, will read from
                    Client_List about the list of Client IDs
run_server.sh       Start CTF and CLA, both listening on hard-wired ports
run_client.sh       Start a client with given ID ($1), just for voting
kill_all_threads.sh Stop all Java classes related to E-Voting on localhost