# How It Works
The Vocdoni-node gateway provides the public APIs that enable voters and third-parties to explore information about processes and entities, generate census proofs, and cast votes.
# Manager Backend
The manager backend provides the private API for integrators and entities to manage their account and voting processes, respectively. The manager backend requires authentication keys to access private API methods.
The API backend is made of two components: a private database and a REST API.
The VaaS database holds information about integrators, organizations, elections, etc, in order to easily provide this information to the REST API.
A relational database is being used to store the necessary information. The following schema describes the involved relational entities:
The main entities are:
Integrator: A third-party integrator of the VaaS API, including a billing plan and a set of organizations (customers of theirs)
Organization: An organization identified by its entityID
Election: A voting process belonging to a specific organization
Census: A census for a voting process, containing a number of census items
CensusItem: An item containing a public key corresponding to an eligible voter
BillingPlan: A configuration item specifying the maximum census size and process count available to a given integrator's account
The database is designed as a relational DB, and is implemented in Postgres. Nevertheless, the DB calls are abastracted by an the interface
database/database.go, allowing for other implementations as well.
For the performing the with Postgres queries we use jmoiron/sqlx, which uses the lib/pq module for connection.
Database migrations ara handled with the rubenv/sql-migrate module.
# API Service
The API service, called
UrlAPI in the codebase, contains the logic and components for the VaaS API.
The API service wraps:
config: Configuration options for the API
router: Manages the incoming requests
api: Contains the authentication middleware
metrics agent: Graphana and Prometheus metrics system
db: The VaaS database
vocClient: A client to make requests to the Vocdoni-Node gateways (communication with the Vochain)
globalOrganizationKey: An optional private key to encrypt organization keys in the db
globalMetadataKey: An optional private key to encrypt election metadata keys in the db
# REST API
The REST API includes the following endpoints:
Admincalls for administrators (Vocdoni) to manage the set of Integrators and billing plans
Privatecalls for integrators to manage organizations & voting processes
Publicpublic calls for end-users to submit votes & query voting process information
Quota[not yet implemented] rate-limited public calls for end-users to submit votes & query voting process information
Available by default under
A detailed version of the API can be found here.
The VaaS API also requires interaction with the Credential Service Provider (opens new window) which provides an authentication API for voter authentication.
# Blind Signature API
This component provides access to a Credential Service Provider (CSP). Users can use this API to request and retrieve a blind signature for anonymous voting processes that use CSP. Details of CSP voting is found here.
# Confidential Metadata
The VaaS-API also offers a new feature in the form of confidential election data. This means all human-readable information like the description and voting options is only available to election administrators and eligible voters.
The confidential process metadata is still stored on ipfs, but it is first encrypted by the VaaS-API backend and uploaded in raw encrypted form. The encryption key is generated uniquely for each election stored in the database, salted with a separate private key specified in the server configuration.
There are two ways to get the data from confidential processes: the private (authenticated) endpoint and the public voter endpoint.
In the case of the private endpoint, the presence of a valid integrator bearer API token signifies that the user is an admin who has rights to view confidential processes. The server fetches the key from the database, salts it with the configured global metadata key, and decrypts the confidential process metadata from ipfs, returning this metadata via the api call.
In the case of the public endpoint, instead of a single admin token, the user must request a shared key from the authentication endpoint and submit this to get confidential election details endpoint. The handler derives a salted public key from the shared key, which is a salted signature of the election ID. The handler then salts this public key with the election ID, producing the CSP public key. If this public key is the same as the election's
censusRoot, meaning the voter has submitted a valid credential proof for that election, then the server fetches, decrypts, and uses the metadata key to provide the confidential metadata to the user.