@phala/dcap-qvl

v0.3.9

Published

2 months ago

Pure JavaScript implementation of DCAP Quote Verification Library

Downloads

5,152

0High
0Medium
0Low

phala

dcap sgx tdx attestation quote verification browser isomorphic universal

dcap-qvl-js

Pure JavaScript implementation of Intel SGX DCAP Quote Verification Library.

Description

dcap-qvl-js provides a pure JavaScript implementation for verifying Intel SGX DCAP (Data Center Attestation Primitives) quotes. It allows you to parse quotes, fetch collateral (PCK certificates, TCB info, QE identity), and verify the quote's validity and TCB status.

Features

Pure JavaScript: No native dependencies, runs in both Node.js and browser environments
Universal/Isomorphic: Works seamlessly in Node.js and browsers with bundler polyfills
Full TypeScript Support: Complete type declarations for type safety and IDE autocompletion
Quote Parsing: Parse and inspect SGX/TDX DCAP quotes
Collateral Retrieval: Helper functions to fetch necessary collateral from PCCS servers
Complete Verification: Full verification logic including signature checks, certificate chain validation, and TCB level comparison

Installation

npm install @phala/dcap-qvl

Quick Start

Basic Usage (Node.js)

import { getCollateralAndVerify } from '@phala/dcap-qvl';

async function verifyQuote(quoteBuffer) {
    // Fetch collateral and verify in one step (defaults to Phala PCCS)
    const result = await getCollateralAndVerify(quoteBuffer);
    console.log('TCB Status:', result.status);
}

Custom PCCS Server

import { verify, getCollateral, PHALA_PCCS_URL } from '@phala/dcap-qvl';

async function verifyQuote(quoteBuffer) {
    // Use default Phala PCCS, or specify your own
    const pccsUrl = process.env.PCCS_URL || PHALA_PCCS_URL;
    const collateral = await getCollateral(pccsUrl, quoteBuffer);

    const currentTimestamp = Date.now() / 1000;
    const result = verify(quoteBuffer, collateral, currentTimestamp);

    console.log('TCB Status:', result.status);
    console.log('Advisory IDs:', result.advisory_ids);
}

TypeScript Usage

The library includes full TypeScript type declarations for enhanced development experience:

import { verify, getCollateral, Quote, VerifiedReport } from '@phala/dcap-qvl';

async function verifyQuote(quoteBuffer: Buffer): Promise<VerifiedReport> {
    const pccsUrl = 'https://your-pccs-server.com/sgx/certification/v4/';
    const collateral = await getCollateral(pccsUrl, quoteBuffer);

    const currentTimestamp = Date.now() / 1000;
    const result = verify(quoteBuffer, collateral, currentTimestamp);

    // TypeScript knows the exact type of result
    console.log('TCB Status:', result.status);
    console.log('Advisory IDs:', result.advisory_ids);
    console.log('Report:', result.report);
    console.log('PPID:', result.ppid);

    return result;
}

// Parse quote structure
function parseQuote(quoteBuffer: Buffer): void {
    const quote = Quote.parse(quoteBuffer);
    console.log('Quote Version:', quote.header.version);
    console.log('TEE Type:', quote.header.teeType);
    console.log('Report Data:', quote.report);
}

Browser Usage

For browser environments, you need to configure Node.js polyfills for crypto, buffer, and stream modules.

Vite Configuration

npm install --save-dev vite-plugin-node-polyfills

// vite.config.js
import { defineConfig } from 'vite';
import { nodePolyfills } from 'vite-plugin-node-polyfills';

export default defineConfig({
  plugins: [
    nodePolyfills({
      include: ['crypto', 'stream', 'buffer', 'util'],
      globals: {
        Buffer: true,
        global: true,
        process: true,
      },
    }),
  ],
});

Webpack 5 Configuration

npm install --save-dev crypto-browserify stream-browserify buffer process

// webpack.config.js
module.exports = {
  resolve: {
    fallback: {
      crypto: require.resolve('crypto-browserify'),
      stream: require.resolve('stream-browserify'),
      buffer: require.resolve('buffer/'),
    },
  },
  plugins: [
    new webpack.ProvidePlugin({
      Buffer: ['buffer', 'Buffer'],
      process: 'process/browser',
    }),
  ],
};

Browser Example

<!DOCTYPE html>
<html>
<head>
    <title>DCAP Quote Verification</title>
</head>
<body>
    <h1>DCAP Quote Verification</h1>
    <button id="verifyBtn">Verify Quote</button>
    <pre id="result"></pre>

    <script type="module">
        import { verify, getCollateral, Quote } from '@phala/dcap-qvl';

        document.getElementById('verifyBtn').addEventListener('click', async () => {
            try {
                // Load your quote data (as Uint8Array or Buffer)
                const quoteBuffer = new Uint8Array([/* quote bytes */]);

                const pccsUrl = 'https://your-pccs-server.com/sgx/certification/v4/';
                const collateral = await getCollateral(pccsUrl, quoteBuffer);

                const currentTimestamp = Date.now() / 1000;
                const result = verify(quoteBuffer, collateral, currentTimestamp);

                document.getElementById('result').textContent = JSON.stringify(result, null, 2);
            } catch (error) {
                document.getElementById('result').textContent = 'Error: ' + error.message;
            }
        });
    </script>
</body>
</html>

API Reference

Main Functions

`verify(rawQuote, collateral, nowSecs)`

Verifies a DCAP quote with the provided collateral.

Parameters:

rawQuote (Buffer | Uint8Array): Raw quote bytes
collateral (Object): Quote collateral containing TCB info, certificates, and CRLs
nowSecs (number): Current timestamp in seconds (Unix time)

Returns: VerifiedReport object containing:

status (string): TCB status (e.g., "UpToDate", "OutOfDate", "ConfigurationNeeded")
advisory_ids (string[]): Array of advisory IDs
report (Object): Parsed quote report data
ppid (Buffer): Platform Provisioning ID

Example:

const result = verify(quoteBuffer, collateral, Date.now() / 1000);
console.log('TCB Status:', result.status);

`getCollateral(pccsUrl, rawQuote)`

Fetches collateral from a PCCS server for the given quote.

Parameters:

pccsUrl (string): PCCS server base URL (must end with /)
rawQuote (Buffer | Uint8Array): Raw quote bytes

Returns: Promise resolving to collateral object containing:

tcb_info (string): TCB information JSON
tcb_info_signature (string | Buffer): TCB info signature
tcb_info_issuer_chain (string | Buffer): TCB info certificate chain
pck_crl (string | Buffer): PCK Certificate Revocation List
root_ca_crl (string | Buffer): Root CA Certificate Revocation List

Example:

const collateral = await getCollateral('https://pccs.example.com/sgx/certification/v4/', quoteBuffer);

`getCollateralAndVerify(rawQuote, pccsUrl?)`

Convenience function that fetches collateral and verifies the quote in one step.

Parameters:

rawQuote (Buffer | Uint8Array): Raw quote bytes
pccsUrl (string, optional): PCCS server URL (defaults to PHALA_PCCS_URL)

Returns: Promise resolving to VerifiedReport object

Example:

const result = await getCollateralAndVerify(quoteBuffer);
console.log('TCB Status:', result.status);

`Quote.parse(rawQuote)`

Parses a raw quote buffer into a structured Quote object.

Parameters:

rawQuote (Buffer | Uint8Array): Raw quote bytes

Returns: Quote object containing:

header: Quote header information (version, attestation key type, TEE type)
report: Enclave or TD report data
authData: Authentication data including certificates and signatures

Example:

const quote = Quote.parse(quoteBuffer);
console.log('Version:', quote.header.version);
console.log('TEE Type:', quote.header.teeType);

Classes

`QuoteVerifier`

Advanced quote verification with custom root CA support.

Methods:

QuoteVerifier.newProd(): Create verifier with Intel's production root CA
QuoteVerifier.newWithRootCa(rootCaDer): Create verifier with custom root CA
verify(rawQuote, collateral, nowSecs): Verify a quote

Example:

import { QuoteVerifier } from '@phala/dcap-qvl';

// Use production Intel root CA
const verifier = QuoteVerifier.newProd();
const result = verifier.verify(quoteBuffer, collateral, Date.now() / 1000);

// Use custom root CA
const customRootCa = Buffer.from(/* custom root CA DER bytes */);
const customVerifier = QuoteVerifier.newWithRootCa(customRootCa);
const result2 = customVerifier.verify(quoteBuffer, collateral, Date.now() / 1000);

Constants

`PHALA_PCCS_URL`

Default PCCS URL pointing to Phala Network's PCCS server (https://pccs.phala.network).

`INTEL_PCS_URL`

Intel's official Provisioning Certification Service URL (https://api.trustedservices.intel.com).

Example:

import { getCollateral, PHALA_PCCS_URL, INTEL_PCS_URL } from '@phala/dcap-qvl';

// Use Phala PCCS (recommended)
const collateral = await getCollateral(PHALA_PCCS_URL, quoteBuffer);

// Or use Intel PCS directly
const collateral2 = await getCollateral(INTEL_PCS_URL, quoteBuffer);

Browser Compatibility Notes

When running in browser environments:

Polyfills Required: You must configure polyfills for Node.js built-in modules (crypto, stream, buffer)
Bundle Size: The library includes cryptographic operations which may increase bundle size (typically ~500KB minified)
CORS: Ensure your PCCS server supports CORS if fetching collateral from the browser
Performance: Browser crypto operations may be slower than Node.js native implementations

Supported Quote Types

SGX DCAP Quotes: Version 3, 4, 5
TDX Quotes: TD 1.0 and TD 1.5 reports
Attestation Key: ECDSA-256 with P-256 curve

Error Handling

The library throws descriptive errors for various failure scenarios:

try {
    const result = verify(quoteBuffer, collateral, Date.now() / 1000);
    console.log('Verification successful:', result.status);
} catch (error) {
    if (error.message.includes('expired')) {
        console.error('TCB information or certificate expired');
    } else if (error.message.includes('signature')) {
        console.error('Signature verification failed');
    } else if (error.message.includes('revoked')) {
        console.error('Certificate has been revoked');
    } else {
        console.error('Verification error:', error.message);
    }
}

Common TCB Status Values

"UpToDate": Platform is up-to-date, no known issues
"OutOfDate": Platform TCB is out of date, update recommended
"ConfigurationNeeded": Platform requires configuration changes
"ConfigurationAndSWHardeningNeeded": Platform needs both configuration and software updates
"SWHardeningNeeded": Software hardening updates needed
"OutOfDateConfigurationNeeded": Platform is out of date and needs configuration

License

Apache-2.0

Contributing

Contributions are welcome! Please ensure:

All tests pass (./run-tests.sh)
Code follows existing style conventions
TypeScript types are updated if adding new APIs

Support

For issues and questions:

GitHub Issues: https://github.com/Phala-Network/dcap-qvl
Documentation: See inline JSDoc comments and TypeScript definitions

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

dcap-qvl-js

Description

Features

Installation

Quick Start

Basic Usage (Node.js)

Custom PCCS Server

TypeScript Usage

Browser Usage

Vite Configuration

Webpack 5 Configuration

Browser Example

API Reference

Main Functions

verify(rawQuote, collateral, nowSecs)

getCollateral(pccsUrl, rawQuote)

getCollateralAndVerify(rawQuote, pccsUrl?)

Quote.parse(rawQuote)

Classes

QuoteVerifier

Constants

PHALA_PCCS_URL

INTEL_PCS_URL

Browser Compatibility Notes

Supported Quote Types

Error Handling

Common TCB Status Values

License

Contributing

Support

`verify(rawQuote, collateral, nowSecs)`

`getCollateral(pccsUrl, rawQuote)`

`getCollateralAndVerify(rawQuote, pccsUrl?)`

`Quote.parse(rawQuote)`

`QuoteVerifier`

`PHALA_PCCS_URL`

`INTEL_PCS_URL`