🔓 Tally decryption endpoints (#73)

* 🔓 Tally decryption endpoints

Adds the necessary endpoints to compute guardian shares and decrypt a tally *when all guardians are present*.

* Add guardian-only tag to share decryption endpoint

* Added tally decryption to Postman

* Added docstrings for tally decryption endpoints

* Fix some bugs introduced in tally decryption

Author: rkorsak

app/api/v1/endpoints/tally.py

@@ -1,19 +1,32 @@
 from electionguard.ballot import CiphertextAcceptedBallot
+from electionguard.decrypt_with_shares import decrypt_tally as decrypt
+from electionguard.decryption import compute_decryption_share
+from electionguard.decryption_share import TallyDecryptionShare
 from electionguard.election import (
     CiphertextElectionContext,
     ElectionDescription,
     InternalElectionDescription,
 )
+from electionguard.serializable import write_json_object
 from electionguard.tally import (
     publish_ciphertext_tally,
+    publish_plaintext_tally,
     CiphertextTally,
     PublishedCiphertextTally,
 )
 from fastapi import APIRouter, Body, HTTPException
 from typing import Any, List, Tuple
 
-
-from ..models import StartTallyRequest, AppendTallyRequest
+from app.utils.serialize import read_json_object
+from ..models import (
+    convert_guardian,
+    convert_tally,
+    AppendTallyRequest,
+    DecryptTallyRequest,
+    DecryptTallyShareRequest,
+    StartTallyRequest,
+)
+from ..tags import GUARDIAN_ONLY
 
 router = APIRouter()
 
@@ -24,10 +37,10 @@ def start_tally(request: StartTallyRequest = Body(...)) -> Any:
     Start a new tally of a collection of ballots
     """
 
-    ballots, description, context = parse_request(request)
+    ballots, description, context = _parse_tally_request(request)
     tally = CiphertextTally("election-results", description, context)
 
-    return tally_ballots(tally, ballots)
+    return _tally_ballots(tally, ballots)
 
 
 @router.post("/append")
@@ -36,16 +49,52 @@ def append_to_tally(request: AppendTallyRequest = Body(...)) -> Any:
     Append ballots into an existing tally
     """
 
-    ballots, description, context = parse_request(request)
+    ballots, description, context = _parse_tally_request(request)
+    tally = convert_tally(request.encrypted_tally, description, context)
+
+    return _tally_ballots(tally, ballots)
+
+
+@router.post("/decrypt")
+def decrypt_tally(request: DecryptTallyRequest = Body(...)) -> Any:
+    """
+    Decrypt a tally from a collection of decrypted guardian shares
+    """
+    description = InternalElectionDescription(
+        ElectionDescription.from_json_object(request.description)
+    )
+    context = CiphertextElectionContext.from_json_object(request.context)
+    tally = convert_tally(request.encrypted_tally, description, context)
+
+    shares = {
+        guardian_id: read_json_object(share, TallyDecryptionShare)
+        for guardian_id, share in request.shares.items()
+    }
 
-    published_tally = PublishedCiphertextTally.from_json_object(request.encrypted_tally)
-    tally = CiphertextTally(published_tally.object_id, description, context)
-    tally.cast = published_tally.cast
+    full_plaintext_tally = decrypt(tally, shares, context)
+    published_plaintext_tally = publish_plaintext_tally(full_plaintext_tally)
 
-    return tally_ballots(tally, ballots)
+    return published_plaintext_tally.to_json_object()
 
 
-def parse_request(
+@router.post("/decrypt-share", tags=[GUARDIAN_ONLY])
+def decrypt_share(request: DecryptTallyShareRequest = Body(...)) -> Any:
+    """
+    Decrypt a single guardian's share of a tally
+    """
+    description = InternalElectionDescription(
+        ElectionDescription.from_json_object(request.description)
+    )
+    context = CiphertextElectionContext.from_json_object(request.context)
+    guardian = convert_guardian(request.guardian)
+    tally = convert_tally(request.encrypted_tally, description, context)
+
+    share = compute_decryption_share(guardian, tally, context)
+
+    return write_json_object(share)
+
+
+def _parse_tally_request(
     request: StartTallyRequest,
 ) -> Tuple[
     List[CiphertextAcceptedBallot],
@@ -65,9 +114,12 @@ def parse_request(
     return (ballots, internal_description, context)
 
 
-def tally_ballots(
+def _tally_ballots(
     tally: CiphertextTally, ballots: List[CiphertextAcceptedBallot]
 ) -> PublishedCiphertextTally:
+    """
+    Append a series of ballots to a new or existing tally
+    """
     tally_succeeded = tally.batch_append(ballots)
 
     if tally_succeeded:

app/api/v1/models/__init__.py

@@ -1,5 +1,6 @@
 from .ballot import *
 from .base import *
+from .election import *
 from .guardian import *
 from .key import *
 from .tally import *

app/api/v1/models/ballot.py

@@ -1,9 +1,14 @@
 from typing import Any
 
 from .base import Base
+from .election import ElectionDecription, CiphertextElectionContext
+
+
+CiphertextAcceptedBallot = Any
+CiphertextBallot = Any
 
 
 class AcceptBallotRequest(Base):
-    ballot: Any
-    description: Any
-    context: Any
+    ballot: CiphertextBallot
+    description: ElectionDecription
+    context: CiphertextElectionContext

app/api/v1/models/election.py

@@ -0,0 +1,5 @@
+from typing import Any
+
+ElectionDecription = Any
+
+CiphertextElectionContext = Any

app/api/v1/models/guardian.py

@@ -1,5 +1,13 @@
 from typing import Any, List, Optional
 
+import electionguard.election_polynomial
+import electionguard.elgamal
+import electionguard.guardian
+import electionguard.key_ceremony
+import electionguard.schnorr
+
+from app.utils.serialize import read_json_object
+
 from .base import Base
 from .key import AuxiliaryKeyPair, AuxiliaryPublicKey, ElectionKeyPair
 
@@ -54,3 +62,34 @@ class BackupChallengeRequest(Base):
 class ChallengeVerificationRequest(Base):
     verifier_id: str
     election_partial_key_challenge: ElectionPartialKeyChallenge
+
+
+def convert_guardian(api_guardian: Guardian) -> electionguard.guardian.Guardian:
+    """
+    Convert an API Guardian model to a fully-hydrated SDK Guardian model.
+    """
+
+    guardian = electionguard.guardian.Guardian(
+        api_guardian.id,
+        api_guardian.sequence_order,
+        api_guardian.number_of_guardians,
+        api_guardian.quorum,
+    )
+    guardian._auxiliary_keys = electionguard.key_ceremony.AuxiliaryKeyPair(
+        api_guardian.auxiliary_key_pair.public_key,
+        api_guardian.auxiliary_key_pair.secret_key,
+    )
+    guardian._election_keys = electionguard.key_ceremony.ElectionKeyPair(
+        read_json_object(
+            guardian._election_keys.key_pair, electionguard.elgamal.ElGamalKeyPair
+        ),
+        read_json_object(
+            guardian._election_keys.proof, electionguard.schnorr.SchnorrProof
+        ),
+        read_json_object(
+            guardian._election_keys.polynomial,
+            electionguard.election_polynomial.ElectionPolynomial,
+        ),
+    )
+
+    return guardian

app/api/v1/models/tally.py

@@ -1,13 +1,58 @@
-from typing import Any, List
+from typing import Any, Dict, List
+import electionguard.election
+import electionguard.tally
 
+from app.utils.serialize import read_json_object
+
+from .ballot import CiphertextAcceptedBallot
 from .base import Base
+from .election import ElectionDecription, CiphertextElectionContext
+from .guardian import Guardian
+
+
+PublishedCiphertextTally = Any
+TallyDecryptionShare = Any
 
 
 class StartTallyRequest(Base):
-    ballots: List[Any]
-    description: Any
-    context: Any
+    ballots: List[CiphertextAcceptedBallot]
+    description: ElectionDecription
+    context: CiphertextElectionContext
 
 
 class AppendTallyRequest(StartTallyRequest):
-    encrypted_tally: Any
+    encrypted_tally: PublishedCiphertextTally
+
+
+class DecryptTallyRequest(Base):
+    encrypted_tally: PublishedCiphertextTally
+    shares: Dict[str, TallyDecryptionShare]
+    description: ElectionDecription
+    context: CiphertextElectionContext
+
+
+class DecryptTallyShareRequest(Base):
+    encrypted_tally: PublishedCiphertextTally
+    guardian: Guardian
+    description: ElectionDecription
+    context: CiphertextElectionContext
+
+
+def convert_tally(
+    encrypted_tally: PublishedCiphertextTally,
+    description: electionguard.election.InternalElectionDescription,
+    context: electionguard.election.CiphertextElectionContext,
+) -> electionguard.tally.CiphertextTally:
+    """
+    Convert to an SDK CiphertextTally model
+    """
+
+    published_tally = read_json_object(
+        encrypted_tally, electionguard.tally.PublishedCiphertextTally
+    )
+    tally = electionguard.tally.CiphertextTally(
+        published_tally.object_id, description, context
+    )
+    tally.cast = published_tally.cast
+
+    return tally