Security Best Practices

This guide covers security best practices for using TrustWeave in production environments.

Overview

TrustWeave handles sensitive cryptographic operations and identity management. Following security best practices is essential for production deployments.

Key Management

Use Production-Grade KMS

❌ Don’t: Use in-memory KMS in production

1

val kms = InMemoryKeyManagementService()  // Only for testing!

✅ Do: Use production KMS providers

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// AWS KMS
val kms = AwsKeyManagementService(
    region = "us-east-1",
    credentials = awsCredentials
)

// Azure Key Vault
val kms = AzureKeyManagementService(
    vaultUrl = "https://your-vault.vault.azure.net/",
    credentials = azureCredentials
)

// Google Cloud KMS
val kms = GoogleKeyManagementService(
    projectId = "your-project",
    location = "us-east1",
    keyRing = "your-keyring",
    credentials = googleCredentials
)

Key Rotation

  • Regular Rotation: Rotate keys regularly (every 90 days recommended)
  • Key Versioning: Use key versioning for gradual rotation
  • Backup Keys: Maintain secure backups of key material
  • See Key Rotation Guide for details

Key Access Control

  • Principle of Least Privilege: Grant minimum required permissions
  • Separate Keys: Use different keys for different purposes (issuance, signing, etc.)
  • Audit Logging: Enable audit logging for all key operations

Credential Storage

Secure Storage

❌ Don’t: Store credentials in plain text

1
2
3
4

// BAD: No encryption
val wallet = TrustWeave.createWallet(holderDid) {
    storagePath = "/var/credentials"  // Unencrypted!
}

✅ Do: Use encrypted storage

1
2
3
4
5
6

// GOOD: Encrypted storage
val wallet = TrustWeave.createWallet(holderDid) {
    storagePath = "/var/credentials"
    encryptionKey = secureKey  // Use secure key management
    property("encryptionAlgorithm", "AES-256-GCM")
}

Access Control

  • File Permissions: Restrict file system permissions (600 for files, 700 for directories)
  • Network Security: Use encrypted connections (TLS) for network storage
  • Authentication: Implement proper authentication for credential access

DID Management

DID Method Selection

  • Security: Choose DID methods with strong security guarantees
  • Resolvability: Ensure DID resolution is reliable and secure
  • Privacy: Consider privacy implications of DID methods

DID Document Security

  • Key Management: Store verification keys securely
  • Service Endpoints: Use HTTPS for all service endpoints
  • Document Updates: Implement secure update mechanisms

Credential Issuance

Issuer Authentication

  • Verify Identity: Verify issuer identity before accepting credentials
  • Trust Registry: Use trust registries to validate issuers
  • Revocation: Implement revocation mechanisms

Credential Validation

  • Structure Validation: Always validate credential structure
  • Proof Verification: Verify cryptographic proofs
  • Expiration Checks: Check credential expiration
  • Revocation Checks: Verify credential is not revoked
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// Verify credential with sealed result
when (val verification = trustweave.verifyCredential(credential)) {
    is CredentialVerificationResult.Valid -> {
        // Additional trust check
        val issuerTrusted = trustweave.trust.isTrustedIssuer(
            issuer = IssuerIdentity(credential.issuer),
            credentialType = CredentialType(credential.type.first())
        )
        
        if (!issuerTrusted) {
            throw SecurityException("Issuer not trusted")
        }
        
        // Safe to use credential
    }
    is CredentialVerificationResult.Invalid.Expired -> {
        throw SecurityException("Credential expired at ${verification.expiredAt}")
    }
    is CredentialVerificationResult.Invalid.Revoked -> {
        throw SecurityException("Credential revoked at ${verification.revokedAt}")
    }
    is CredentialVerificationResult.Invalid.InvalidProof -> {
        throw SecurityException("Proof validation failed: ${verification.reason}")
    }
    else -> {
        throw SecurityException("Credential validation failed: ${verification.errors}")
    }
}

Blockchain Anchoring

Chain Selection

  • Security: Choose chains with strong security guarantees
  • Finality: Consider finality time for your use case
  • Cost: Balance security and cost

Transaction Security

  • Private Keys: Never expose private keys
  • Transaction Signing: Use secure signing mechanisms
  • Gas Management: Implement proper gas management

Network Security

TLS/HTTPS

  • Always Use TLS: Use HTTPS for all network communications
  • Certificate Validation: Validate TLS certificates
  • Cipher Suites: Use strong cipher suites

API Security

  • Authentication: Implement proper API authentication
  • Authorization: Use role-based access control (RBAC)
  • Rate Limiting: Implement rate limiting to prevent abuse
  • Input Validation: Validate all inputs

Error Handling

Secure Error Messages

❌ Don’t: Expose sensitive information in errors

1
2
3
4

catch (e: Exception) {
    println("Error: ${e.message}")  // May expose sensitive data
    println("Stack trace: ${e.stackTrace}")  // May expose internals
}

✅ Do: Sanitize error messages

1
2
3
4
5
6
7
8
9

catch (e: Exception) {
    logger.error("Operation failed", e)  // Log full details
    return Result.failure(
        TrustWeaveError.Unknown(
            message = "Operation failed. Please try again.",  // Generic message
            context = emptyMap()
        )
    )
}

Logging and Monitoring

Secure Logging

  • No Sensitive Data: Never log keys, passwords, or credentials
  • Structured Logging: Use structured logging for better analysis
  • Log Rotation: Implement log rotation and retention policies

Monitoring

  • Security Events: Monitor security-relevant events
  • Anomaly Detection: Implement anomaly detection
  • Alerting: Set up alerts for security incidents

Compliance

Data Protection

  • GDPR: Ensure GDPR compliance for EU users
  • CCPA: Ensure CCPA compliance for California users
  • Data Minimization: Collect only necessary data

Audit Trails

  • Comprehensive Logging: Log all security-relevant operations
  • Immutable Logs: Use immutable log storage
  • Retention: Maintain logs according to compliance requirements

Threat Modeling

Common Threats

  1. Key Theft: Protect keys with strong access controls
  2. Credential Forgery: Verify all credentials cryptographically
  3. Man-in-the-Middle: Use TLS for all communications
  4. Replay Attacks: Use nonces and timestamps
  5. Denial of Service: Implement rate limiting and resource limits

Mitigation Strategies

  • Defense in Depth: Use multiple security layers
  • Least Privilege: Grant minimum required permissions
  • Regular Updates: Keep dependencies updated
  • Security Audits: Conduct regular security audits

Best Practices Summary

  1. ✅ Use production-grade KMS (AWS, Azure, Google Cloud)
  2. ✅ Encrypt credential storage
  3. ✅ Validate all credentials before use
  4. ✅ Use TLS/HTTPS for all network communications
  5. ✅ Implement proper authentication and authorization
  6. ✅ Log security events (without sensitive data)
  7. ✅ Rotate keys regularly
  8. ✅ Keep dependencies updated
  9. ✅ Conduct security audits
  10. ✅ Follow principle of least privilege

Trust Boundaries

Understanding trust boundaries is crucial for secure deployments. See Trust Boundaries for detailed guidance on:

  • What to trust and what not to trust
  • Establishing secure trust relationships
  • Trust verification patterns
  • Security zones and boundaries

Additional Resources

Getting Help

For security concerns:

  1. Security Issues: Report to security@geoknoesis.com
  2. General Questions: See FAQ
  3. Support: Contact www.geoknoesis.com