The Work References Standard

1. Protocol Overview

Work References 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 signed payload invalidates the signature; visible PDF edits are not checked.
• •Decentralised trust: verification relies on DNS, not a central certificate authority.
• •Browser tools: WorkReferences.org generates keys and signs in the browser. RefPassport has different setup and reset behavior.
• •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 Work References 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. Key custody depends on the implementation. The free signing tool uses keys in the browser; RefPassport setup and reset receive the password and generate the key on its server before encryption.

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 and a unique nonce. This is the exact data that gets signed.

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 Gold or Invalid.

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: 'invalid', reason: 'No DNS record found' };
    publicKeyBase64 = match.match(/p=([A-Za-z0-9+/=]+)/)?.[1];
    if (!publicKeyBase64) return { status: 'invalid', reason: 'Malformed DNS record' };
  } catch {
    return { status: 'invalid', 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

The stateless verifier returns Gold only when the payload signature verifies against a DNS key. Otherwise it returns Invalid. It does not check expiry or revocation.

8. PDF Proof Format

Work References generates a branded PDF document that serves as a self-contained, portable proof of the reference. The PDF embeds the full signed payload and signature in its metadata — everything a verifier needs to check authenticity using only DNS.

Visual Structure

Embedded Metadata

The following data is embedded in the PDF’s document properties. Together, these fields carry the signed payload. This website uploads the PDF for extraction and uses a live DNS lookup; it does not provide fully offline verification:

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 signed payload can be extracted without it; this verifier still requires a DNS lookup.

Tamper Detection

The verifier checks the signature of the embedded payload. It does not compare the visible PDF text or layout with that payload, and does not validate the returned payload-hash field. Compare the displayed verified payload with the document; changing the visible PDF while preserving its metadata is not detected by this tool.

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 return Invalid. This tool needs DNS and does not offer offline verification.

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 PDF with the candidate. The document is self-contained proof.

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 (signature valid against DNS), Invalid (missing DNS or failed signature). Revocation and expiry are not checked.

Best Practices

Recommended Libraries