Skip to content

Encryption API Reference

Overview

The Encryption API provides endpoints for managing data encryption within AIDDDMAP, supporting multiple encryption modes including Fully Homomorphic Encryption (FHE), Zero-Knowledge Proofs (ZK), and Basic Encryption.

Authentication Requirements

All API requests require authentication using an API key:

Authorization: Bearer YOUR_API_KEY

API Base URL

https://api.aidddmap.com/v1

Encryption Endpoints

Data Encryption

POST /encryption/encrypt

Encrypt data using the specified encryption mode.

Encryption Request Body

{
  "data": "base64_encoded_data",
  "mode": "FHE",
  "parameters": {
    "scheme": "BFV",
    "securityLevel": 128,
    "precision": 16
  }
}

Encryption Response

{
  "encryptedData": "encrypted_data_base64",
  "metadata": {
    "mode": "FHE",
    "scheme": "BFV",
    "timestamp": "2024-01-14T12:00:00Z"
  }
}

Data Decryption

POST /encryption/decrypt

Decrypt previously encrypted data.

Decryption Request Body

{
  "encryptedData": "encrypted_data_base64",
  "metadata": {
    "mode": "FHE",
    "scheme": "BFV"
  }
}

Decryption Response

{
  "data": "decrypted_data_base64",
  "metadata": {
    "timestamp": "2024-01-14T12:05:00Z"
  }
}

Encryption Key Generation

POST /encryption/keys/generate

Generate encryption keys for a specific mode.

Key Generation Request Body

{
  "mode": "FHE",
  "parameters": {
    "scheme": "BFV",
    "securityLevel": 128
  }
}

Key Generation Response

{
  "publicKey": "public_key_base64",
  "privateKey": "private_key_base64",
  "metadata": {
    "keyId": "key-123",
    "createdAt": "2024-01-14T12:00:00Z",
    "expiresAt": "2024-02-14T12:00:00Z"
  }
}

Encryption Key Status

GET /encryption/keys/{keyId}/status

Get the status and metadata of a specific encryption key.

Key Status Response

{
  "keyId": "key-123",
  "status": "active",
  "metadata": {
    "mode": "FHE",
    "scheme": "BFV",
    "createdAt": "2024-01-14T12:00:00Z",
    "expiresAt": "2024-02-14T12:00:00Z"
  }
}

FHE Operations

FHE Computation

POST /encryption/fhe/compute

Perform computations on encrypted data without decryption.

FHE Computation Request Body

{
  "operation": "add",
  "operands": ["encrypted_data_1_base64", "encrypted_data_2_base64"],
  "parameters": {
    "scheme": "BFV",
    "precision": 16
  }
}

FHE Computation Response

{
  "result": "encrypted_result_base64",
  "metadata": {
    "operation": "add",
    "timestamp": "2024-01-14T12:10:00Z"
  }
}

Zero-Knowledge Proofs

ZK Proof Generation

POST /encryption/zk/prove

Generate a zero-knowledge proof for data verification.

ZK Proof Generation Request Body

{
  "data": "data_to_prove_base64",
  "circuit": "circuit_definition",
  "parameters": {
    "scheme": "Groth16"
  }
}

ZK Proof Generation Response

{
  "proof": "zk_proof_base64",
  "publicInputs": "public_inputs_base64",
  "metadata": {
    "scheme": "Groth16",
    "timestamp": "2024-01-14T12:15:00Z"
  }
}

ZK Proof Verification

POST /encryption/zk/verify

Verify a zero-knowledge proof.

ZK Proof Verification Request Body

{
  "proof": "zk_proof_base64",
  "publicInputs": "public_inputs_base64",
  "circuit": "circuit_definition"
}

ZK Proof Verification Response

{
  "verified": true,
  "metadata": {
    "timestamp": "2024-01-14T12:20:00Z"
  }
}

API Error Responses

The API uses standard HTTP response codes:

  • 200 - Success
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Internal Server Error

Error response format:

{
  "error": {
    "code": "INVALID_ENCRYPTION_PARAMETERS",
    "message": "Invalid encryption parameters provided",
    "details": {
      "parameter": "securityLevel",
      "reason": "Must be 128, 192, or 256"
    }
  }
}

API Rate Limiting

API requests are limited to:

  • 50 requests per minute for standard users
  • 500 requests per minute for enterprise users

Rate limit headers are included in responses:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1516131940

SDK Code Examples

TypeScript Implementation

import { AIDDDMAPClient } from "@aidddmap/sdk";

const client = new AIDDDMAPClient({
  apiKey: "YOUR_API_KEY",
});

// Encrypt data using FHE
const encryptedData = await client.encryption.encrypt({
  data: Buffer.from("sensitive data").toString("base64"),
  mode: "FHE",
  parameters: {
    scheme: "BFV",
    securityLevel: 128,
  },
});

// Perform homomorphic operation
const result = await client.encryption.fhe.compute({
  operation: "add",
  operands: [encryptedData1, encryptedData2],
  parameters: {
    scheme: "BFV",
  },
});

Python Implementation

from aidddmap import Client
import base64

client = Client(api_key='YOUR_API_KEY')

# Encrypt data using FHE
data = base64.b64encode(b'sensitive data').decode('utf-8')
encrypted_data = client.encryption.encrypt(
    data=data,
    mode='FHE',
    parameters={
        'scheme': 'BFV',
        'securityLevel': 128
    }
)

# Generate ZK proof
proof = client.encryption.zk.prove(
    data=data,
    circuit='circuit_definition',
    parameters={
        'scheme': 'Groth16'
    }
)

Encryption Methods

Security Implementation

Helper Methods

Security Guidelines

ZKHandler

The ZKHandler class provides methods for generating and verifying zero-knowledge proofs, with support for various proof types and post-quantum security.

Methods

initialize()

Initializes the ZK system with the specified configuration.

async initialize(config?: ZKConfig): Promise<void>

Parameters:

  • config (optional): Configuration options for the ZK system
  • scheme: Proof scheme ('groth16' | 'pghr13')
  • securityLevel: Security level (1 | 3 | 5)
  • useGPU: Enable GPU acceleration
  • optimizationLevel: Circuit optimization level ('basic' | 'aggressive')

generateKeys()

Generates proving and verification keys for a given circuit.

async generateKeys(circuit: ZKCircuit): Promise<{ pk: ProvingKey; vk: VerificationKey }>

Parameters:

  • circuit: The circuit description for which to generate keys

generateProof()

Generates a zero-knowledge proof for given inputs.

async generateProof(
  circuit: ZKCircuit,
  privateInputs: any[],
  publicInputs: any[]
): Promise<ZKProof>

Parameters:

  • circuit: The circuit description
  • privateInputs: Private witness inputs
  • publicInputs: Public inputs

verifyProof()

Verifies a zero-knowledge proof.

async verifyProof(proof: ZKProof): Promise<boolean>

Parameters:

  • proof: The proof to verify

generateRangeProof()

Generates a proof that a value lies within a specified range.

async generateRangeProof(
  value: number,
  range: { min: number; max: number }
): Promise<ZKProof>

Parameters:

  • value: The value to prove
  • range: The range constraints

generateEqualityProof()

Generates a proof that two values are equal.

async generateEqualityProof(value1: any, value2: any): Promise<ZKProof>

Parameters:

  • value1: First value
  • value2: Second value

generateMembershipProof()

Generates a proof that a value is a member of a set.

async generateMembershipProof(value: any, set: any[]): Promise<ZKProof>

Parameters:

  • value: The value to prove membership for
  • set: The set to prove membership in

cleanup()

Cleans up resources and resets the ZK system.

async cleanup(): Promise<void>

PostQuantumScheme

The PostQuantumScheme class provides methods for post-quantum cryptography operations.

Methods

initialize()

Initializes the post-quantum scheme with specified parameters.

async initialize(config: PostQuantumConfig): Promise<void>

Parameters:

  • config: Configuration for the post-quantum scheme
  • scheme: Post-quantum scheme ('kyber' | 'dilithium' | 'sphincs')
  • securityLevel: Security level (1 | 3 | 5)
  • params: Scheme-specific parameters

generateKeyPair()

Generates a post-quantum key pair.

async generateKeyPair(): Promise<{ publicKey: Uint8Array; privateKey: Uint8Array }>

encapsulate()

Performs key encapsulation (Kyber).

async encapsulate(publicKey: Uint8Array): Promise<{ ciphertext: Uint8Array; sharedSecret: Uint8Array }>

Parameters:

  • publicKey: The public key for encapsulation

decapsulate()

Performs key decapsulation (Kyber).

async decapsulate(ciphertext: Uint8Array, privateKey: Uint8Array): Promise<Uint8Array>

Parameters:

  • ciphertext: The encapsulated ciphertext
  • privateKey: The private key for decapsulation

sign()

Generates a post-quantum signature (Dilithium/SPHINCS+).

async sign(message: Uint8Array, privateKey: Uint8Array): Promise<Uint8Array>

Parameters:

  • message: The message to sign
  • privateKey: The private key for signing

verify()

Verifies a post-quantum signature (Dilithium/SPHINCS+).

async verify(
  message: Uint8Array,
  signature: Uint8Array,
  publicKey: Uint8Array
): Promise<boolean>

Parameters:

  • message: The original message
  • signature: The signature to verify
  • publicKey: The public key for verification

CircuitOptimizer

The CircuitOptimizer class provides methods for optimizing ZK circuits.

Methods

optimize()

Optimizes a circuit based on the specified configuration.

async optimize(circuit: ZKCircuit): Promise<ZKCircuit>

Parameters:

  • circuit: The circuit to optimize

initializeGPU()

Initializes GPU context for circuit optimization.

async initializeGPU(): Promise<void>

processConstraints()

Processes constraints using GPU acceleration.

async processConstraints(constraints: R1CSConstraint[]): Promise<R1CSConstraint[]>

Parameters:

  • constraints: The constraints to process

ZeroKnowledgeVM

The ZeroKnowledgeVM class provides a virtual machine for executing ZK proofs.

Methods

initialize()

Initializes the ZKVM with specified parameters.

async initialize(config: ZKVMConfig): Promise<void>

Parameters:

  • config: Configuration for the ZKVM
  • memoryLimit: Maximum memory usage
  • maxInstructions: Maximum number of instructions
  • optimizationLevel: Optimization level

executeCircuit()

Executes a circuit in the ZKVM.

async executeCircuit(circuit: ZKCircuit): Promise<ZKVMResult>

Parameters:

  • circuit: The circuit to execute

getMemoryState()

Returns the current state of the VM memory.

getMemoryState(): VMMemoryState

Error Handling

All methods may throw the following errors:

  • ZKError: Base class for all ZK-related errors
  • InitializationError: Error during initialization
  • ProofGenerationError: Error generating a proof
  • VerificationError: Error verifying a proof
  • OptimizationError: Error during circuit optimization
  • PostQuantumError: Error in post-quantum operations
  • VMError: Error in ZKVM execution