Technical Overview of VeraId

This document provides a technical overview of VeraId for anyone looking to understand the protocol and its reference implementations. This includes protocol designers and (Sec)DevOps engineers seeking to integrate it into their existing systems, and prospective contributors to the project, for example.

Introduction

VeraId is a decentralised, user-friendly, offline-first authentication protocol that securely attributes content to domain names. It enables verification of content authenticity without requiring continuous Internet connectivity, making it ideal for offline or intermittently connected environments.

VeraId was created to address a critical need for customisable, user-friendly, universally-unique, offline-compatible identifiers that can withstand sophisticated attacks, particularly for users of Letro. After extensive research, we found no existing technology that could satisfy these requirements in a decentralised manner.

Organisations and members are key concepts in VeraId. Organisations are represented by domain names (e.g., example.com) and serve as the foundation of identity. Members are entities that act on behalf of organisations, including users who are identified by a username within an organisation (e.g., [email protected]) and bots that act on behalf of the organisation as a whole (identified simply as example.com).

VeraId leverages the domain name system as the basis for identity. Domain ownership, verified through DNSSEC, establishes the right to issue certificates and create signatures for that domain. The protocol uses X.509 certificates to establish a chain of trust where organisations create self-signed certificates, which then issue certificates to members. This certification path links members to their organisation. Members use their private keys to create digital signatures using the Cryptographic Message Syntax (CMS) SignedData format that cryptographically proves they authored specific content.

A key innovation of VeraId is its “verify anywhere” approach. All the information needed to verify a signature—including DNSSEC proofs, certificates, and the signature itself—is packaged into a self-contained VeraId Signature Bundle that can be verified entirely offline. For example, this is how we’d verify a bundle attributing Bazinga! to [email protected]:

DNSSEC Chain

.
edu.
caltech.edu.
_veraid.caltech.edu.
caltech.edu.

X.509 Certificate Chain

caltech.edu
sheldon
[email protected]

CMS SignedData

Bazinga!
"Bazinga!"
Play

VeraId Chain

VeraId’s security model is built on a chain of cryptographic proofs that establish trust from the DNS root all the way to individual signatures. This chain combines three distinct technologies—DNSSEC, X.509 certificates, and CMS SignedData—into a cohesive verification path that can be validated entirely offline. Each link in this chain serves a specific purpose: DNSSEC anchors identity in domain ownership, X.509 certificates establish organisational and member identities, and CMS SignedData provides the cryptographic binding between content and identity.

DNSSEC Chain

DNSSEC serves as the foundation of VeraId’s trust model, providing cryptographic authentication of DNS records without requiring centralised certificate authorities:

X.509 Certificate Chain

VeraId uses X.509 certificates to establish a domain-specific hierarchy of trust:

Unlike traditional PKI where any certificate authority can issue certificates for any domain, VeraId enforces a strict one-to-many relationship where an organisation can only issue certificates for its own domain, significantly reducing the attack surface.

CMS SignedData

The final link in the VeraId chain is the signature itself, which uses the Cryptographic Message Syntax (CMS) SignedData format. Depending on the signature type, this signed data is produced either directly by a member using their private key (for member signatures) or by the organisation (for organisation signatures).

Signature Types

VeraId supports two distinct types of signatures, each with different trust models and use cases:

  1. Member Signatures: The member uses their private key to sign content, creating a direct cryptographic link between the member and the content. The verification chain goes from DNSSEC to the organisation certificate to the member certificate to the signature.
  2. Organisation Signatures: The organisation signs the content and claims (but does not cryptographically prove) that a specific member created it. The verification chain goes directly from DNSSEC to the organisation certificate to the signature.

Organisation signatures should be used sparingly, and only when member certificate management is impractical or unnecessary. For example, organisation signatures were introduced to support workflow identities, such as GitHub Actions workflows or server-side applications, where it would be undesirable to use shared secrets for authentication.

Architecture

VeraId’s implementation architecture consists of core libraries and supporting services that enable organisations to integrate the protocol into their systems. The following diagram illustrates the key components and their relationships:

VeraId Architecture Diagram

Core Libraries

VeraId provides implementations in JavaScript (@relaycorp/veraid) and Kotlin (tech.relaycorp:veraid) to enable integration across different platforms.

Both libraries implement the same core protocol operations: MemberIdBundle and SignatureBundle creation and verification, as well as the building blocks to implement custom tooling.

VeraId Authority

VeraId Authority is a cloud-native, multi-tenant application that helps organisations manage their VeraId members and issue Member Bundles. Whilst not part of the protocol itself, it serves as a reference implementation and administration tool to facilitate the operation of the protocol.

VeraId Authority provides workflows for:

Letro Integration Case Study

Letro is an offline-compatible email alternative that uses VeraId for secure authentication. It serves as a practical demonstration of VeraId’s capabilities in a real-world application:

Note that Letro uses member signatures, rather than organisation signatures, so that users can sign messages offline.

Security Considerations

VeraId’s security model comes with several important considerations that operators and service designers should be aware of:

  1. DNSSEC Dependency and Trust Assumptions: VeraId inherits trust from the DNSSEC root zone, which means the security of the entire system depends on the integrity of this foundation. A compromise of the root DNSSEC zone would undermine the entire system. Additionally, a malicious TLD operator could theoretically issue fraudulent DNSSEC responses, potentially compromising domains under their control.
  2. Homographic Attacks and Character Encoding Issues: Different Unicode characters that appear visually similar can be used for spoofing attacks. Implementations should detect and warn about mixed-script identifiers to mitigate this risk. User interfaces should display domain names in Punycode when they contain non-ASCII characters to make potentially deceptive domains more apparent to users.
  3. Domain Ownership Changes: Organisations should delay implementing VeraId until at least the maximum TTL (30 days) after acquiring a domain to ensure previous owners cannot interfere with the setup. It’s important to note that signatures created before a domain transfer remain cryptographically valid, which could potentially lead to confusion or misattribution.
  4. Offline Verification Limitations: The offline verification capability comes with inherent constraints. Accurate verification requires a correct system time on the verifying device. Valid signatures can be replayed beyond their intended context if not properly constrained by the application. The protocol relies on short validity periods rather than revocation checking, which means compromised keys remain valid until their certificates expire.
  5. Organisation Signatures and Member Attribution: Whilst member signatures provide cryptographic proof of authorship, organisation signatures only provide a claim by the organisation about who created the content. Malicious or compromised organisations could falsely attribute content to members when using organisation signatures. Where relevant, user interfaces should clearly distinguish between these signature types to avoid confusion.
  6. TTL Considerations: The protocol favours short-lived certificates over complex revocation mechanisms for simplicity and offline compatibility. VeraId requires a minimum TTL of 8 hours and a maximum of 30 days to balance security and usability. Service designers should specify the shortest TTL that satisfies their requirements to minimise the window of vulnerability in case of key compromise.

Additional Resources