TERE

Attestation API Reference

Updated May 17, 2025•7 min read

The Attestation API provides the tools to verify that your code is running in a genuine Trusted Execution Environment with the expected security properties. Attestation is a critical security feature that provides cryptographic guarantees about the integrity and authenticity of the execution environment.

Getting Started

Prerequisites

To use the Attestation API, you need:

  • The TERE SDK installed (npm install @praecise/tere)
  • A deployed TERE application (see the Runtime API)

Attestation Workflow

  1. When you execute a function in a TEE, an attestation report is automatically generated
  2. The attestation report is included in the execution response
  3. You verify the attestation using the client's verifyAttestation method
  4. Based on the verification result, you can trust or reject the execution result

Core API Methods

client.verifyAttestation

Verifies an attestation report to ensure it came from a genuine TEE with the expected security properties.

Parameters

options: VerifyAttestationOptionsRequired

Options for attestation verification

Returns

Promise<VerificationResult>

Result of the attestation verification, including validity and security details

Examples

Basic verification

javascript
1// Verify the attestation from an execution result
2const result = await client.execute({
3  scriptId: 'script_abc123',
4  function: 'processData',
5  arguments: ['sensitive data']
6});
7 
8// Verify the attestation
9const verification = await client.verifyAttestation({
10  attestation: result.attestation
11});
12 
13if (verification.valid) {
14  console.log('Attestation verified successfully');
15  console.log('TEE Type:', verification.details.teeType);
16  console.log('Secure Boot Enabled:', verification.details.secureBoot);
17  console.log('Integrity Verified:', verification.details.integrityVerified);
18  
19  // Process the verified result
20  return result.result;
21} else {
22  console.error('Attestation verification failed:', verification.error);
23  throw new Error('Cannot trust result - attestation invalid');
24}

With nonce for freshness

javascript
1// Generate a random nonce
2const nonce = crypto.randomUUID();
3 
4// Include it in the execution request
5const result = await client.execute({
6  scriptId: 'script_abc123',
7  function: 'processData',
8  arguments: ['sensitive data'],
9  nonce: nonce
10});
11 
12// Verify with the expected nonce
13const verification = await client.verifyAttestation({
14  attestation: result.attestation,
15  expectedNonce: nonce
16});
17 
18// Check if the attestation has the expected nonce
19if (verification.valid && verification.details.nonce === nonce) {
20  console.log('Attestation verified with correct nonce');
21  // Process the verified result
22} else {
23  console.error('Attestation verification failed or nonce mismatch');
24}
client.getAttestationReport

Retrieves a fresh attestation report from a deployed TEE instance without executing a function.

Parameters

scriptId: stringRequired

ID of the script to get an attestation report for

options: GetAttestationOptions

Optional settings for attestation generation

Returns

Promise<AttestationResponse>

Response containing the attestation report and related metadata

Examples

Get an attestation report

javascript
1// Get an attestation report for a deployed script
2const attestationResponse = await client.getAttestationReport('script_abc123');
3 
4// Verify the attestation
5const verification = await client.verifyAttestation({
6  attestation: attestationResponse.attestation
7});
8 
9console.log('Attestation verified:', verification.valid);
10console.log('TEE Type:', verification.details.teeType);
11console.log('TEE Security Version:', verification.details.securityVersion);

With custom data

javascript
1// Get an attestation with custom data included
2const customData = JSON.stringify({
3  purpose: 'compliance-verification',
4  timestamp: new Date().toISOString()
5});
6 
7// Get the attestation with the custom data
8const attestationResponse = await client.getAttestationReport('script_abc123', {
9  customData: customData
10});
11 
12// Verify the attestation
13const verification = await client.verifyAttestation({
14  attestation: attestationResponse.attestation,
15  expectedCustomData: customData
16});
17 
18console.log('Attestation verified with custom data:', verification.valid);

Verification Options

When verifying an attestation, you can specify various requirements that the attestation must meet:

typescript
1interface VerifyAttestationOptions {
2  // The attestation report to verify
3  attestation: string;
4  
5  // Optional nonce that should be present in the attestation (for freshness)
6  expectedNonce?: string;
7  
8  // Optional custom data that should be present in the attestation
9  expectedCustomData?: string;
10  
11  // Required TEE type (e.g., 'SEV-SNP', 'TDX')
12  requiredTeeType?: string;
13  
14  // Whether secure boot must be enabled
15  requireSecureBoot?: boolean;
16  
17  // Whether integrity monitoring must be enabled
18  requireIntegrityMonitoring?: boolean;
19  
20  // Minimum required security version
21  minSecurityVersion?: string;
22  
23  // Custom verification function for additional checks
24  customVerifier?: (details: AttestationDetails) => boolean | Promise<boolean>;
25}

Attestation Details

When an attestation is verified, the verification result includes detailed information about the TEE:

typescript
1interface VerificationResult {
2  // Whether the attestation is valid
3  valid: boolean;
4  
5  // Error message if validation failed
6  error?: string;
7  
8  // Detailed attestation information (if valid)
9  details?: AttestationDetails;
10}
11 
12interface AttestationDetails {
13  // Type of TEE (e.g., 'SEV-SNP', 'TDX')
14  teeType: string;
15  
16  // TEE security version number
17  securityVersion: string;
18  
19  // Whether secure boot is enabled
20  secureBoot: boolean;
21  
22  // Whether integrity monitoring is enabled
23  integrityMonitoring: boolean;
24  
25  // Whether vTPM is enabled
26  vtpm: boolean;
27  
28  // The nonce used for freshness (if provided)
29  nonce?: string;
30  
31  // SHA-256 measurement of the code
32  measurement: string;
33  
34  // Timestamp when the attestation was generated
35  timestamp: string;
36  
37  // Custom data included in the attestation (if any)
38  customData?: string;
39  
40  // Additional TEE-specific properties
41  [key: string]: any;
42}

Advanced Usage

Custom Verification Logic

You can implement custom verification logic using the customVerifier option:

typescript
1// Custom verification function
2function customAttestationVerifier(details: AttestationDetails): boolean {
3  // Check for specific TEE version
4  if (details.teeType === 'SEV-SNP') {
5    // Require a minimum firmware version for SEV-SNP
6    const minVersion = '1.51';
7    return compareVersions(details.securityVersion, minVersion) >= 0;
8  }
9  
10  if (details.teeType === 'TDX') {
11    // Require a minimum firmware version for TDX
12    const minVersion = '1.5';
13    return compareVersions(details.securityVersion, minVersion) >= 0;
14  }
15  
16  // Reject other TEE types
17  return false;
18}
19 
20// Helper function to compare version strings
21function compareVersions(version1: string, version2: string): number {
22  const parts1 = version1.split('.').map(Number);
23  const parts2 = version2.split('.').map(Number);
24  
25  for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
26    const a = parts1[i] || 0;
27    const b = parts2[i] || 0;
28    if (a !== b) return a - b;
29  }
30  
31  return 0;
32}
33 
34// Use the custom verifier
35const verification = await client.verifyAttestation({
36  attestation: result.attestation,
37  customVerifier: customAttestationVerifier
38});

Verification with Full Requirements

For highly secure applications, you may want to enforce strict requirements:

typescript
1// Comprehensive verification with strict requirements
2const verification = await client.verifyAttestation({
3  attestation: result.attestation,
4  expectedNonce: nonce,
5  requiredTeeType: 'SEV-SNP',
6  requireSecureBoot: true,
7  requireIntegrityMonitoring: true,
8  minSecurityVersion: '1.52'
9});
10 
11if (verification.valid) {
12  console.log('Attestation passes all security requirements');
13  // Process the verified result
14} else {
15  console.error('Attestation failed to meet security requirements:', verification.error);
16  // Handle the security failure
17}

Best Practices

  • Always Verify Attestations

    Always verify attestations for any sensitive operations to ensure the code is running in a genuine TEE.

  • Use Nonces for Freshness

    Include a unique nonce in every execution to prevent replay attacks. A nonce ensures that the attestation was generated for this specific request and not reused from a previous one.

  • Specify Required Security Features

    For sensitive workloads, explicitly specify the required TEE type, whether secure boot must be enabled, and other security requirements.

  • Implement Error Handling

    Properly handle and log attestation verification failures. Treat unverified results as potentially compromised.

Related Documentation

Attestation Guide →

Learn more about how attestation works and why it's important

Runtime API →

Explore how attestation is integrated with function execution