The RefPassport Standard

1. Protocol Overview

RefPassport enables employers to issue cryptographically signed employment references that candidates can carry with them throughout their career. Any third party (a recruiter, HR team, or hiring manager) can verify the authenticity of a reference instantly, without contacting the issuing company or creating an account.

Actors

Protocol Flow

Design Goals

• •Portability: references travel with the candidate, not locked to any platform.
• •Tamper-evidence: any modification to the reference content invalidates the signature.
• •Decentralised trust: verification relies on DNS, not a central certificate authority.
• •Zero-knowledge: the server never has access to plaintext signing keys.
• •Simplicity: inspired by DKIM, the protocol uses well-understood standards (Ed25519, DNS TXT, JSON).

2. DNS Record Specification

The issuer’s Ed25519 public key is published as a DNS TXT record under a well-known subdomain. This is the anchor that allows anyone to independently verify a reference without trusting RefPassport itself.

Record Format

Name:  {SELECTOR}._workreferences.{DOMAIN}
Type:  TXT
Value: v=workreferences1; k=ed25519; p={BASE64_PUBLIC_KEY}

Field Definitions

Example

REF1._workreferences.acmecorp.com.  3600  IN  TXT  "v=workreferences1; k=ed25519; p=Ky2hL9xR4bT...44chars...="

Registrar Examples

3. Cryptographic Primitives

Ed25519 Digital Signatures

All references are signed using Ed25519 (Edwards-curve Digital Signature Algorithm on Curve25519). Ed25519 provides strong security guarantees with compact keys and fast operations.

import nacl from 'tweetnacl';
import { encodeBase64 } from 'tweetnacl-util';

const keyPair = nacl.sign.keyPair();
const publicKey  = encodeBase64(keyPair.publicKey);   // 44 chars
const privateKey = encodeBase64(keyPair.secretKey);   // 88 chars

AES-256-GCM (Private Key Encryption)

Private keys are encrypted at rest using AES-256-GCM with a key derived from the user’s password. The server stores only the ciphertext and can never decrypt the private key without the password (zero-knowledge architecture).

SHA-256 Hashing

SHA-256 is used for two purposes: (1) as the hash function within PBKDF2 key derivation, and (2) for computing integrity hashes of reference payloads and PDF documents. Hashes are represented as lowercase hexadecimal strings.

4. Payload Format

The reference payload is a JSON object containing the reference data, a unique nonce, and the issuer’s domain and key selector. This makes each reference self-contained — a verifier can extract the payload and know exactly where to look up the public key via DNS.

JSON Structure

{
  "name":     "James Holloway",
  "role":     "Baggage Handler",
  "dates":    "June 2021 – December 2024",
  "text":     "James was a reliable and hardworking member of our airside baggage team...",
  "nonce":    "550e8400-e29b-41d4-a716-446655440000",
  "domain":   "heathrow-gh.com",
  "selector": "REF1"
}

Field Specifications

Canonical Serialisation

To ensure that both the signer and verifier produce identical byte representations, the payload is serialised with alphabetically sorted keys:

function normalizeJson(obj) {
  return JSON.stringify(obj, Object.keys(obj).sort());
}

// Result (keys sorted alphabetically):
// {"dates":"June 2021...","domain":"heathrow-gh.com","name":"James Holloway","nonce":"550e8400...","role":"Baggage...","selector":"REF1","text":"James was..."}

5. Signing Process

Signing happens entirely on the client side. The private key is decrypted in the browser using the user’s password, used to sign, and then discarded from memory. The plaintext private key is never sent to or stored on the server.

Steps

Code Example

import nacl from 'tweetnacl';
import { encodeBase64, decodeBase64 } from 'tweetnacl-util';

function signReference(payload, privateKeyBase64) {
  // 1. Canonical serialisation (sorted keys)
  const canonical = JSON.stringify(payload, Object.keys(payload).sort());

  // 2. Encode to bytes
  const payloadBytes = new TextEncoder().encode(canonical);
  const privateKeyBytes = decodeBase64(privateKeyBase64);

  // 3. Sign (detached: signature does not contain the message)
  const signatureBytes = nacl.sign.detached(payloadBytes, privateKeyBytes);

  // 4. Return base64-encoded signature
  return encodeBase64(signatureBytes);  // 88 characters
}

6. Verification Process

Verification requires no central server or database. The reference document (PDF) contains everything needed: the signed payload, the signature, and the issuer’s domain and key selector. A verifier extracts this data, looks up the public key via DNS, and checks the signature. The result is one of three trust levels.

Algorithm

Full Verification (Decentralised)

import nacl from 'tweetnacl';
import { decodeBase64 } from 'tweetnacl-util';
import dns from 'dns/promises';

async function verifyReference(payload, signatureBase64) {
  // 1. Extract domain and selector from the payload itself
  const { domain, selector } = payload;

  // 2. Look up the public key via DNS
  const recordName = `${selector}._workreferences.${domain}`;
  let publicKeyBase64;
  try {
    const records = await dns.resolveTxt(recordName);
    const flat = records.map(r => r.join(''));
    const match = flat.find(r => r.startsWith('v=workreferences1;'));
    if (!match) return { status: 'silver', reason: 'No DNS record found' };
    publicKeyBase64 = match.match(/p=([A-Za-z0-9+/=]+)/)?.[1];
    if (!publicKeyBase64) return { status: 'silver', reason: 'Malformed DNS record' };
  } catch {
    return { status: 'silver', reason: 'DNS lookup failed' };
  }

  // 3. Verify the signature against the DNS public key
  const canonical = JSON.stringify(payload, Object.keys(payload).sort());
  const payloadBytes   = new TextEncoder().encode(canonical);
  const signatureBytes = decodeBase64(signatureBase64);
  const publicKeyBytes = decodeBase64(publicKeyBase64);

  const valid = nacl.sign.detached.verify(payloadBytes, signatureBytes, publicKeyBytes);
  return valid
    ? { status: 'gold', reason: 'Signature valid, DNS verified' }
    : { status: 'invalid', reason: 'Signature verification failed' };
}

7. Trust Levels

Verification produces one of three trust levels, determined by the combination of signature validity and DNS record presence.

8. PDF Proof Format

RefPassport generates a branded PDF document that serves as a portable proof of the reference. The PDF embeds all the data needed for verification in its metadata, and includes a QR code linking to the online verification page.

Visual Structure

Embedded Metadata

The following data is embedded in the PDF’s document properties. Together, these fields contain everything needed for fully offline verification — no server or database required:

QR Code

Implementations MAY include a QR code linking to an online verification page for convenience. However, the PDF metadata is the authoritative source — the QR code is optional and the reference is verifiable without it.

Tamper Detection

The SHA-256 hash of the canonical payload is embedded in the PDF metadata as a keyword. A verifier can recompute the hash from the extracted payload and compare it against the embedded value to detect any metadata corruption.

9. Security Properties

Guarantees

Threat Model

Non-Goals

• •Anonymity: references are explicitly linked to identifiable domains.
• •Confidentiality: reference content is not encrypted in transit. Once shared, it is readable by any recipient.
• •Guaranteed availability: DNS lookup failures degrade to Silver, not Gold. Offline signature verification is possible.

10. Implementation Notes

For Issuers

1. Generate an Ed25519 key pair on the client.
2. Encrypt the private key with a strong password (PBKDF2, 100k iterations, AES-256-GCM).
3. Publish the public key as a DNS TXT record at {SELECTOR}._workreferences.{DOMAIN}.
4. Wait for DNS propagation (typically 15 minutes to 48 hours).
5. Sign references client-side. Never send the plaintext private key to the server.
6. Generate a PDF with the payload, signature, domain, and selector embedded in metadata.
7. Share the verification link and/or PDF with the candidate.

For Verifiers

1. Receive a PDF from the candidate.
2. Extract the payload and signature from the PDF metadata.
3. Look up the public key via DNS using the domain and selector from the payload.
4. Verify the Ed25519 signature. Check the trust level: Gold (full trust), Silver (DNS not found), Invalid (signature failed).

Best Practices

Recommended Libraries