← Technical documentation

Voter files

The two files a voter can keep: the vote receipt and the voting private key. What they contain, field by field, what they let you check, and what must stay secret.

Both are built in your browser and exist only if you download them: the platform never receives, stores or sends them. Both contain your secret key.

Protocol v1

Common format

Two JSON envelopes, the same rules.

The receipt and the private key follow the same conventions, read and written by the voting site's voter-artifacts library. The cryptographic validity of the values (checksum, curve membership) is CryptoVote's job, not the envelope reader's.

One UTF-8 JSON object. Each file is a single JSON object, written on one line with no whitespace. The examples on this page are indented for reading.
A version first. The version field names the envelope and its version. A reader must check it and reject any other value.
Prefixed values, never bare hex. Every cryptographic value is the canonical <tag>_<hex>_<checksum> string emitted by CryptoVote, carried verbatim. A hex value without its prefix is rejected.
A checksum against typos. 4 bytes of BLAKE3 (8 hex characters), with the tag folded in: a miscopied value, or a pk_ pasted where a ki_ was expected, is caught at once. It is not a security guarantee: authenticity comes from the ring signature alone.
Unknown fields ignored. A reader must ignore fields it does not know, to stay compatible with a future revision of the format; it does not write them back.

The tags

pk_ 32 bytes · 64 hex characters: Public key: the one listed in the ring.
sk_ 32 bytes · 64 hex characters: Secret key: the one that signs. Must never be disclosed.
ki_ 32 bytes · 64 hex characters: Key image: the public identifier of a ballot, specific to one election.
ring_ 32 bytes · 64 hex characters: Ring digest: the canonical fingerprint of a ring's set of keys, independent of their order.
blsag_ 32 × (1 + ring size) bytes: bLSAG ring signature: 38,464 hex characters for a 600-key ring.

Vote receipt · .condorcet_receipt

The receipt, issued once the ballot is accepted.

Your own copy of the ballot you cast, of the ring you signed it under and of the key that signed it: enough to find and check your ballot in the public register yourself.

When, and in whose hands

Only after acceptance. The receipt appears on the voting page only once the server has accepted your ballot. It is displayed once; downloading it is optional.
Built in your browser. The page assembles it from the secret key still held in memory since signing. It is never emailed (the confirmation email only attests your participation) and never stored by the platform.
Cannot be re-issued. The platform no longer holds your secret key, so it cannot rebuild the receipt. On the page, sensitive values sit behind "show" and "copy" buttons; "hide the details" clears them from the screen for good, and the secret key clears itself after a fixed delay. Copy or download the receipt first.

What it lets you do

Find your ballot. Enter ballot.key_image in the election's public register lookup, even before batch publication, then compare the published ballot with signed_payload, byte for byte.
Check your ring. Compare ring_digest with the digest the register publishes for the ring named in ring. A mismatch means you signed under a ring other than the published one.
Check your participation line. voter_id points to your line in the participation register: number of key distributions, voted flag.
Re-verify the signature offline. signed_payload, signature, the election identifier and the ring's public keys are enough to re-verify the signature, without the platform.
Produce a vote proof. The Vote proof tool reads the receipt and takes the secret key, the election and the key image from it.

version string: Always condorcet-receipt/1.
election UUID: The election identifier, a signing parameter. Accepted in upper case when read, always written back in lower case.
ring non-empty string: The identifier (UUID) of the ring the ballot was signed under, as published in the register.
ring_digest ring_…: The digest of that ring, computed by your browser from the keys it was served. The server never supplies one: a value sent with the ring could be tailored with it.
voter_id UUID: Your voter ID, the only published identifier that concerns you.
public_key pk_…: Your public key, a member of the ring.
secret_key sk_…: Your secret key, the one that signed the ballot.
ballot.signed_payload string (JSON): The signed payload, byte for byte: the very string that was signed and submitted to the server. Treat it as an opaque string; parsing and re-encoding it would break the comparison with the register.
ballot.signature blsag_…: The ballot's ring signature.
ballot.key_image ki_…: The ballot's key image, specific to this election: your ballot's public identifier in the register.

public/docs/voter-files.example_label · recu-vote-0c2e7e2a.condorcet_receipt

{
    "version": "condorcet-receipt/1",
    "election": "0c2e7e2a-5df3-4c0e-9d2b-3f6a8f0c9e21",
    "ring": "7b1d4f90-2c3a-4e8b-a6d5-91f0e2c47a38",
    "ring_digest": "ring_ffeeddccbbaa99887766554433221100ffeeddccbbaa99887766554433221100_8b7a6f5e",
    "voter_id": "3e9a5c71-8d24-4b6f-b0e3-5a7c19d2f846",
    "public_key": "pk_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef_a1b2c3d4",
    "secret_key": "sk_fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210_d4c3b2a1",
    "ballot": {
        "signed_payload": "{\"v\":1,\"election\":\"0c2e7e2a-5df3-4c0e-9d2b-3f6a8f0c9e21\",\"ballot\":\"Alice > Bob = Chloé\",\"weight\":1}",
        "signature": "blsag_0a1b2c3d4e5f6a7b0a1b2c3d4e5f6a7b0a1b2c3d4e5f6a7b0a1b2c3d4e5f6a7b0a1b2c3d4e5f6a7b0a1b2c3d4e5f6a7b0a1b2c3d4e5f6a7b0a1b2c3d4e5f6a7b_e5f6a7b8",
        "key_image": "ki_00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff_5e6f7a8b"
    }
}

Fictitious values: invalid checksums, signature cut to its minimum length. The downloaded file is named recu-vote- followed by the first 8 characters of the election identifier.

What signed_payload contains Open the Vote proof tool

Private key · .condorcet_private_key

The private key, downloaded when you deposit your key.

When you deposit your own key, the key pair is generated in your browser. This file is its backup: it is what will let you vote.

When, and in whose hands

When you deposit a generated key. During an election's key deposit period, or an election group's, if you choose to generate a key. CryptoVote produces the pair in your browser.
Only the public key leaves. public_key is sent to the platform, which will place it in a ring. The secret key is displayed once, copyable, and the file is built in your browser.
No election, no group. The file holds only the key pair: the same key may serve several independent elections, since the key image is made specific to each election at signing time. It is named after the key itself, condorcet-vote- followed by the checksum of public_key.

What it lets you do

Vote. On the voting page, paste the sk_… key or load the file: the page derives the public key and checks that it belongs to the ring you were assigned.
Deposit the same key elsewhere. On another deposit, load the file: the public key is extracted in the browser, and the secret key never leaves your device.
Find your ballot, prove your vote. With the secret key and an election identifier, the Vote proof tool recomputes your key image, even without a receipt.

version string: Always condorcet-private-key/1.
public_key pk_…: The public key, the one sent to the platform when you deposited it.
secret_key sk_…: The secret key, generated in your browser and never sent.

public/docs/voter-files.example_label · condorcet-vote-a1b2c3d4.condorcet_private_key

{
    "version": "condorcet-private-key/1",
    "public_key": "pk_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef_a1b2c3d4",
    "secret_key": "sk_fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210_d4c3b2a1"
}

Fictitious values, invalid checksums. No election or group field: an older file carrying an informational election field still reads, that field being ignored.

Open the Vote proof tool

Secrets

What must stay secret, and why.

Both files carry your secret key. Keep them like a password: out of others' reach, but without losing them.

The risks, plainly

The secret key reveals your vote. It recomputes your key image for any election, and so finds your published ballots, retroactively, in every election where it was used; it can also produce a vote proof in your name.
The secret key signs. It produces a valid signature in any ring that contains your public key. The platform accepts a ballot only through your voting link, and only one per voter.
The receipt reveals your vote to whoever reads it. It puts your voter ID next to your ballot. It is provable by design: the protocol favours individual verifiability and therefore offers no coercion resistance. Show it only to someone you choose to reveal your vote to.
A lost key is a lost vote. A deposited key has no server-side fallback: once the election is open, losing it means not voting. While the key deposit period is open, you can deposit a new key instead, for the elections whose rings are not built yet.
A lost receipt is not re-issued. Your ballot still counts. If you kept your secret key, it is enough to recompute your key image and find your ballot.

What the platform never sees

Your files. The receipt and the private key are written and downloaded in your browser; they never pass through our servers.
A secret key you generated. Generated in your browser, it is never sent. Loading a key file on a deposit sends only its public key.
A distributed key, after you vote. In the default mode, the platform generates the key and keeps it encrypted; it erases it from its database when handing it to you, then from its temporary cache when you vote. It can therefore no longer rebuild your receipt.
The link between your key and your ballot. Your public key appears in the published ring and your ballot in the public register; only the secret key links the two.

What a vote proof reveals

Voter files

Two JSON envelopes, the same rules.

The tags

The receipt, issued once the ballot is accepted.

When, and in whose hands

What it lets you do

The private key, downloaded when you deposit your key.

When, and in whose hands

What it lets you do

What must stay secret, and why.

The risks, plainly

What the platform never sees

See also