Privacy & Security

KryptoOS is built with privacy by design and enterprise-grade security. This guide covers advanced privacy features and security best practices.

Privacy by Design

Core Privacy Principles

Data Minimization: Only collect and share necessary information
Off-Chain PII: Personal data stays off the blockchain
Selective Disclosure: Share only what's needed
Unlinkability: Prevent correlation across services
User Control: Users decide what to share and with whom

What's On-Chain vs Off-Chain

On-Chain (Public):

DID identifiers
Hashes of DID Documents
Credential anchors (hashes)
Status list references
Timestamps and version numbers

Off-Chain (Private):

Personal identifiable information (PII)
Credential contents
Private keys
Full DID Documents
Service endpoint details

Zero-Knowledge Proofs

Zero-knowledge proofs (ZKPs) allow you to prove statements without revealing the underlying data.

Age Verification Example

Prove you're over 18 without revealing your birthdate:

import { ZKPClient } from '@empoorio/ssi-sdk';

const zkp = new ZKPClient();

// Create proof
const ageProof = await zkp.prove({
  circuit: 'age-verification',
  privateInputs: {
    birthDate: '1990-01-15'
  },
  publicInputs: {
    minimumAge: 18,
    currentDate: '2024-01-15'
  }
});

// Verifier checks proof without seeing birthdate
const verified = await zkp.verify(ageProof);
console.log('Is over 18:', verified); // true

Range Proofs

Prove a value is within a range without revealing the exact value:

// Prove income is between $50k-$100k without revealing exact amount
const incomeProof = await zkp.prove({
  circuit: 'range-proof',
  privateInputs: {
    income: 75000
  },
  publicInputs: {
    minRange: 50000,
    maxRange: 100000
  }
});

Membership Proofs

Prove membership in a set without revealing which member:

// Prove you're from EU without revealing specific country
const membershipProof = await zkp.prove({
  circuit: 'set-membership',
  privateInputs: {
    country: 'Spain'
  },
  publicInputs: {
    allowedSet: ['Germany', 'France', 'Spain', 'Italy', 'Netherlands']
  }
});

Selective Disclosure

Share only specific attributes from a credential.

Using SD-JWT

Selective Disclosure JWT allows fine-grained control:

// Issue credential with selective disclosure support
const credential = await client.vc.issue({
  type: ['VerifiableCredential', 'DriverLicense'],
  credentialSubject: {
    id: holderDid,
    licenseNumber: 'DL-123456',
    fullName: 'John Doe',
    dateOfBirth: '1990-01-15',
    address: '123 Main St',
    expirationDate: '2028-01-15',
    restrictions: 'None'
  },
  format: 'sd-jwt' // Enable selective disclosure
});

// Holder creates presentation disclosing only some fields
const presentation = await client.vc.createPresentation({
  credentials: [{
    credential: credential,
    disclose: ['hasValidLicense', 'expirationDate'],
    hide: ['licenseNumber', 'fullName', 'dateOfBirth', 'address']
  }],
  holder: holderDid,
  verifier: verifierDid
});

BBS+ Signatures

BBS+ signatures enable efficient selective disclosure:

// Issue with BBS+ signature
const credential = await client.vc.issue({
  type: ['VerifiableCredential', 'EmploymentCredential'],
  credentialSubject: {
    id: holderDid,
    employer: 'Tech Corp',
    position: 'Senior Engineer',
    salary: 120000,
    startDate: '2020-01-15',
    department: 'Engineering'
  },
  proofType: 'BbsBlsSignature2020'
});

// Derive credential with only selected attributes
const derivedCredential = await client.vc.deriveCredential({
  credential: credential,
  revealedAttributes: ['employer', 'position'],
  nonce: verifierNonce
});

Pairwise DIDs

Use different DIDs for different relationships to prevent correlation.

Creating Pairwise DIDs

// Create unique DID for each service
const employerDid = await client.did.createPairwise({
  peerDid: 'did:emp:employer-corp',
  purpose: 'employment'
});

const bankDid = await client.did.createPairwise({
  peerDid: 'did:emp:bank-01',
  purpose: 'financial-services'
});

const healthDid = await client.did.createPairwise({
  peerDid: 'did:emp:hospital-01',
  purpose: 'healthcare'
});

// Each service sees a different DID
console.log('Employer sees:', employerDid.id);
console.log('Bank sees:', bankDid.id);
console.log('Hospital sees:', healthDid.id);

Benefits

Privacy: Services cannot correlate your activities
Revocation: Revoke one relationship without affecting others
Compartmentalization: Different identities for different contexts

Cryptography

Signature Algorithms

KryptoOS supports multiple signature schemes:

Algorithm	Use Case	Key Size	Performance
Ed25519	General purpose, fast	256 bits	Excellent
ECDSA secp256k1	Ethereum compatibility	256 bits	Good
BLS12-381	Aggregated signatures, ZKPs	381 bits	Good
BBS+	Selective disclosure	381 bits	Moderate

Encryption

For encrypted communication and data storage:

// Encrypt data for specific DID
const encrypted = await client.crypto.encrypt({
  data: sensitiveData,
  recipientDid: 'did:emp:recipient-123',
  algorithm: 'X25519-XChaCha20-Poly1305'
});

// Decrypt
const decrypted = await client.crypto.decrypt({
  encryptedData: encrypted,
  senderDid: 'did:emp:sender-456'
});

Hash Functions

SHA-256: General purpose hashing
Blake2b: Optimized for blockchain
Poseidon: ZK-friendly hash function

Key Management

Secure Key Storage

// Use hardware wallet for production
const client = new SSIClient({
  nodeUrl: 'wss://ws.empooriochain.org',
  keyStorage: {
    type: 'hardware',
    device: 'ledger',
    path: "m/44'/60'/0'/0/0"
  }
});

Key Rotation

Regular key rotation is essential for security:

// Automated key rotation
await client.did.rotateKeys({
  did: 'did:emp:user-123',
  newKeyType: 'Ed25519VerificationKey2020',
  gracePeriod: 90, // days
  notifyRelying Parties: true
});

Backup and Recovery

// Set up social recovery
await client.recovery.setupSocial({
  did: 'did:emp:user-123',
  guardians: [
    'did:emp:friend-1',
    'did:emp:friend-2',
    'did:emp:family-1'
  ],
  threshold: 2, // Require 2 out of 3 guardians
  recoveryDelay: 7 // days
});

Multi-Party Computation (MPC)

// Set up MPC for key management
await client.recovery.setupMPC({
  did: 'did:emp:user-123',
  parties: 3,
  threshold: 2,
  backupLocations: ['cloud', 'device', 'hardware-wallet']
});

Privacy-Preserving Features

Anonymous Credentials

Issue credentials without revealing holder identity:

const anonymousCredential = await client.vc.issueAnonymous({
  type: ['VerifiableCredential', 'MembershipCredential'],
  claims: {
    memberSince: '2024-01-01',
    tier: 'gold',
    benefits: ['discount', 'priority-support']
  },
  blindSignature: true
});

Unlinkable Presentations

Create presentations that cannot be linked across verifications:

const presentation = await client.vc.createPresentation({
  credentials: [credential],
  holder: holderDid,
  verifier: verifierDid,
  unlinkable: true, // Use fresh randomness each time
  nonce: verifierNonce
});

Compliance and Regulations

KryptoOS is designed for GDPR compliance:

Right to Access: Users can export all their data
Right to Rectification: Credentials can be updated or reissued
Right to Erasure: DIDs can be deactivated, credentials revoked
Data Minimization: Only necessary data is collected
Privacy by Design: Privacy features built-in from the start

// Export user data (GDPR Article 15)
const userData = await client.gdpr.exportData({
  did: 'did:emp:user-123',
  includeCredentials: true,
  includePresentations: true
});

// Delete user data (GDPR Article 17)
await client.gdpr.deleteData({
  did: 'did:emp:user-123',
  deactivateDid: true,
  revokeCredentials: true
});

MiCA and AML

For financial services compliance:

// Issue AML-compliant credential
const amlCredential = await client.vc.issue({
  type: ['VerifiableCredential', 'AMLCredential'],
  credentialSubject: {
    id: userDid,
    amlCheck: 'passed',
    sanctionsCheck: 'clear',
    pepCheck: 'negative',
    riskScore: 'low',
    jurisdiction: 'EU',
    checkDate: new Date().toISOString()
  },
  compliance: {
    standard: 'MiCA',
    auditTrail: true
  }
});

Security Best Practices

For Developers

Use HTTPS/WSS: Always use encrypted connections
Validate Inputs: Sanitize all user inputs
Rate Limiting: Implement rate limiting on APIs
Audit Logging: Log all security-relevant events
Regular Updates: Keep SDKs and dependencies updated
Security Reviews: Regular security audits and penetration testing

For Users

Strong Keys: Use hardware wallets or secure enclaves
Backup: Maintain secure, encrypted backups
Verify Requests: Always verify who's requesting credentials
Monitor Activity: Regularly review credential presentations
Update Software: Keep wallets and apps updated

For Organizations

HSM: Use Hardware Security Modules for production keys
Access Control: Implement strict access controls
Incident Response: Have incident response plans
Compliance: Regular compliance audits
Training: Security training for all staff

Threat Model

Common Threats and Mitigations

Threat	Mitigation
Phishing	Verify verifier DIDs, use trusted registries
Key Compromise	Key rotation, multi-sig, HSM
Replay Attacks	Nonces, challenges, expiration
Correlation	Pairwise DIDs, selective disclosure
Man-in-the-Middle	TLS/SSL, DIDComm encryption
Issuer Fraud	Trust registries, reputation systems

Monitoring and Auditing

Security Monitoring

// Set up security monitoring
await client.monitoring.configure({
  alerts: {
    suspiciousActivity: true,
    keyRotation: true,
    credentialRevocation: true,
    failedVerifications: true
  },
  notifications: {
    email: 'security@example.com',
    webhook: 'https://api.example.com/security-alerts'
  }
});

Audit Trails

// Query audit logs
const auditLogs = await client.audit.query({
  did: 'did:emp:user-123',
  eventTypes: ['credential-issued', 'credential-presented', 'key-rotated'],
  startDate: '2024-01-01',
  endDate: '2024-12-31'
});

for (const log of auditLogs) {
  console.log(`${log.timestamp}: ${log.eventType} - ${log.details}`);
}

Next Steps

Integration: Integrate privacy features into your application
Architecture: Understand the security architecture
FAQ: Common security questions

Need help? Check our Security FAQ and use the official security contact published by the Empoorio/KryptoOS team for the current release.

Содержание