Link Search Menu Expand Document

Vera Architecture (MVP)

This document describes the systems and software architecture of the various component that will make up the Minimum Viable Product (MVP) version of Vera.

Vera library

This library, available in JavaScript and JVM/Android, will implement all the cryptographic and data serialisation operations needed by the various components in Vera.

Its JS version will use PKI.js, ASN1.js and a new DNSSEC verification library to be implemented by Relaycorp. Its JVM/Android version will use Bouncy Castle and ideally dnsjava (if we can expose the DNSSEC verification interface – otherwise we’ll have to implement our own DNSSEC verification library).

Prototype implementation: vera-lib.

Vera Certificate Authority (CA) server

This multi-tenant server will allow one or more organisations to manage their Vera setup, and it’ll also allow organisation members to claim and renew their Vera Ids.

It will support the following API endpoints, which are to be consumed by the Vera CA Console (used by organisation admins) and Vera signature producers (used by organisation members):

  • POST /zones/: Create zone.
    • Auth: OAuth2 (admin).
    • Input:
      • Zone (e.g., acme.com).
      • Access type (invite-only or open).
      • Services (e.g., Letro).
      • Awala endpoint middleware URL (optional).
    • Output: TXT record.
  • DELETE /zones/{zone}/: Delete zone.
    • Auth: OAuth2 (zone admin).
  • POST /zones/{zone}/user-invites/: Create user invite, if access type is invite-only.
    • Auth: OAuth2 (zone admin).
    • Input: Username and service id.
    • Output: Single-use claim token.
  • POST /zones/{zone}/users/*: Claim invite and request Vera Id, if access type is invite-only.
    • Auth: Single-use claim token.
    • Input: Vera Id public key.
    • Output: Vera Id certificate.
  • POST /zones/{zone}/users/{user}/ids/*: Renew Vera Id.
    • Auth: Signed request with the asymmetric key in the Vera Id.
    • Input: None.
    • Output: New Vera Id certificate.
  • DELETE /zones/{zone}/users/{user}/: Delete user.
    • Auth: OAuth2 (zone admin).
  • POST /zones/{zone}/awala/: Awala endpoint middleware backend.
    • Auth: Awala Endpoint Middleware.
    • Awala service messages:
      • UserInviteClaim (if access type is invite-only).
        • Input: Single-use claim token.
        • Output: Vera Id certificate.
      • UserIdRequest (if access type is open).
        • Input: Vera Id public key and desired username.
        • Output: Vera Id certificate.
      • UserIdRenewal.
        • Input: Username, signed with asymmetric key in the Vera Id.
        • Output: New Vera Id certificate.

* We may skip this endpoint in v1 because the endpoint POST /zones/{zone}/awala/ already supports this functionality.

This server will have the following background processes:

Prototype implementation: vera-ca.

Vera CA Console

This will be the command-line interface (CLI) to the admin-only endpoints in the Vera CA Server.

The admin user will have to log in using device authorisation code, ideally.

Prototype implementation: vera-ca (tech.relaycorp.vera.ca.cli.Main).

Notable compromises

We’re taking the following shortcuts to keep the cost of the MVP down:

  • The Vera CA Console is to be implemented as a CLI.
  • No way for organisation users to claim their ids without admin intervention.
  • No support for bot accounts as organisation members.