sgx-ra-tls-verify

Pure-JavaScript verifier for Intel SGX DCAP quotes and RA-TLS certificates.

Runs in Node.js (>=18) and in the browser. No native modules, no Intel DCAP Quote Verification Library (QVL) required — the whole verification pipeline (ECDSA signature chain, PCK cert verification against Intel SGX Root CA, TCB evaluation against the Intel PCS collateral, QE Identity check, enclave report verification) is implemented in JS on top of node-forge, elliptic, and cbor.

What this gives you

Three layers, use what you need:

1. verifyQuote(pemOrQuote, options) — low-level verifier that takes a raw DCAP quote (or an RA-TLS certificate that embeds one) and returns a structured result with the MRENCLAVE / MRSIGNER / ISV product id / ISV SVN / TCB status, plus a per-step breakdown of which checks passed.

2. CertificateVerifier — a higher-level wrapper that plugs into Node.js TLS (checkServerIdentity / createServerIdentityChecker). It detects whether a peer certificate contains an RA-TLS quote extension (TCG DICE OID 2.23.133.5.4.9 or the Intel legacy OID 1.2.840.113741.1.13.1), and if so runs verifyQuote against it.

3. generateRaTlsCertificate({ produceQuote, ... }) — framework-agnostic RA-TLS certificate generator. Builds a self-signed X.509 cert carrying both the legacy and TCG DICE attestation extensions. You supply a callback that turns a 32-byte report-data hash into an attestation quote (the library never touches /dev/attestation/*, DCAP, OE, or any other runtime-specific surface).

Quick start (Node.js, ESM)

import {
    verifyQuote,
    CertificateVerifier,
    generateRaTlsCertificate,
} from '@xnetx/sgx-ra-tls-verify';

// 1) Verify a raw RA-TLS certificate (PEM) or a DCAP quote
const result = await verifyQuote(certPem, {
    enclaveIdentities: [
        {
            mrenclave: 'abcd...64hex',
            mrsigner:  '1234...64hex',
            isvprodid: 1,
            isvsvn:    0,
        },
    ],
    allowOutdatedTcb:       false,
    allowDebugEnclave:      false,
    allowHwConfigNeeded:    false,
    allowSwHardeningNeeded: false,
});

if (result.verified) {
    console.log('OK, measurements:', result.measurements);
} else {
    console.error('Rejected:', result.error, result.verificationDetails);
}

// 2) Use it as a TLS server-identity checker (e.g. mysql2 SSL, HTTPS client)
const verifier = new CertificateVerifier({
    raTlsOptions: {
        enclaveIdentities: [{ mrenclave: '...', mrsigner: '...', isvprodid: 1, isvsvn: 0 }],
    },
});

const tlsOptions = {
    checkServerIdentity: verifier.createServerIdentityChecker(),
};

Quick start (CommonJS)

const { verifyQuote } = require('@xnetx/sgx-ra-tls-verify');

// CertificateVerifier is ESM-only; dynamic-import it from CJS:
const { CertificateVerifier } = await import('@xnetx/sgx-ra-tls-verify');

Options for verifyQuote / CertificateVerifier

| Option | Type | Default | Purpose | | -------------------------- | ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------- | | enclaveIdentities | Array<EnclaveIdentity> | — | Whitelist. Each entry is matched as a whole; empty / zero fields are skipped. | | allowOutdatedTcb | boolean | false | Accept OUT_OF_DATE / OUT_OF_DATE_CONFIG_NEEDED TCB status. | | allowDebugEnclave | boolean | false | Accept quotes where the enclave has the debug attribute set. Leave off in production. | | allowHwConfigNeeded | boolean | false | Accept CONFIG_NEEDED. | | allowSwHardeningNeeded | boolean | false | Accept SW_HARDENING_NEEDED. |

Where EnclaveIdentity is:

{
    mrenclave: string;   // 64-hex (32 bytes)
    mrsigner:  string;   // 64-hex (32 bytes)
    isvprodid: number;   // uint16
    isvsvn:    number;   // uint16 — minimum acceptable SVN
}

CertificateVerifier additionally accepts:

| Option | Type | Default | Purpose | | ---------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------- | | allowNonRaTls | boolean | false | When true, a peer cert with no SGX quote extension is accepted. Use only in direct / non-SGX dev. |

Generating an RA-TLS certificate

import fs from 'fs';
import { generateRaTlsCertificate } from '@xnetx/sgx-ra-tls-verify';

// The quote producer is YOUR responsibility — it is how you bridge this
// library to whatever SGX runtime you use. The library is runtime-agnostic.
//
// Example for Gramine: write report_data to the pseudo-file, read back the
// quote. SGX's user_report_data field is 64 bytes; we get 32 bytes (a SHA256
// digest) from the library and right-pad with zeros.
const gramineProduceQuote = async (reportDataBytes) => {
    const userReportData = Buffer.alloc(64);
    reportDataBytes.copy(userReportData, 0);
    fs.writeFileSync('/dev/attestation/user_report_data', userReportData);
    return fs.readFileSync('/dev/attestation/quote');
};

const { certPem, keyPem, hasQuote } = await generateRaTlsCertificate({
    produceQuote: gramineProduceQuote,
    subjectCommonName: 'my-service',
    validityDays: 365,
});

if (!hasQuote) {
    console.warn('No attestation quote was produced — cert has no RA-TLS extensions');
}

produceQuote is called twice per certificate. The two calls receive different 32-byte hashes, which correspond to the two attestation extensions (legacy OID and TCG DICE OID) written into the certificate. Each call must return a complete attestation quote whose user_report_data begins with the exact 32 bytes the library passed in.

The callback can:

• return a Buffer — used verbatim as the attestation quote for that extension;
• return null — that extension is skipped (use this for non-SGX dev / test);
• throw — propagates to the caller of generateRaTlsCertificate.

Browser

The sgx-quote-verify.js module is written as dual-mode: when loaded without Node globals it expects forge, cbor, and elliptic to be available on window. Bundle them via your tool of choice, or load dependencies.js alongside the script tag — see the source for the exact globals expected.

Collateral fetching

By default the verifier calls fetch() to pull PCK certificates, CRLs, TCB Info, and QE Identity from the Intel PCS. To point at a different endpoint or use a caching proxy, swap the fetch implementation:

import { setFetchFunction } from '@xnetx/sgx-ra-tls-verify';

setFetchFunction(async (url, init) => {
    // ... your proxied fetch
    return fetch(url, init);
});

Status

Originally developed in-house and extracted as a standalone library. Has been running in production as the RA-TLS verification layer between SGX enclave peers. Treat 0.x as "API may still be tightened".

License

• Non-commercial use (personal / academic / research / evaluation): free.
• Commercial use: requires a separate written commercial license obtained before such use begins. Open an issue to start that conversation.

See LICENSE for the full text and LICENSING.md for a plain-English summary.