The Open Agent Passport (OAP) security model ensures the integrity, authenticity, and confidentiality of agent credentials and policy decisions through cryptographic verification and secure key management.

Cryptographic Primitives

Ed25519 Signatures

All OAP objects use Ed25519 for digital signatures:

Algorithm: Edwards Curve Digital Signature Algorithm (EdDSA)
Curve: Curve25519
Key Size: 256 bits (32 bytes)
Signature Size: 512 bits (64 bytes)
Performance: Fast signing and verification, suitable for edge computing

SHA-256 Hashing

Passport digests use SHA-256:

Algorithm: SHA-256
Input: JCS-canonicalized passport view
Output: 256-bit (32-byte) hash
Format: sha256:

JCS Canonicalization

All objects are canonicalized using RFC 8785 JCS before signing:

Standard: RFC 8785 JSON Canonicalization Scheme
Purpose: Deterministic JSON representation for consistent hashing
Implementation: Must follow RFC 8785 exactly

Key Management

Key Types

Registry Keys

Registry keys are used by the OAP registry to sign decisions:

Format: oap:registry:
Location: https://api.yourdomain/.well-known/oap/jwks.json
Rotation: Regular rotation schedule (e.g., quarterly)
Backup: Multiple keys for high availability

Owner Keys

Owner keys are used by passport owners for additional verification:

Format: oap:owner::
Location: https:///.well-known/oap/jwks.json
Optional: Not required for basic OAP compliance
Use Case: Additional verification layers

Key Resolution

Keys are resolved using the following process:

Parse kid: Extract key type and identifier
Resolve URL: Construct key resolution URL
Fetch key: Retrieve public key from URL
Validate: Verify key format and expiration
Cache: Cache key for performance

Key Resolution URLs

Registry keys: https://api.yourdomain/.well-known/oap/jwks.json
Owner keys:    https://<domain>/.well-known/oap/jwks.json

Key Format

{
  "keys": [
    {
      "kid": "oap:registry:key-2025-01",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "base64url-encoded-public-key",
      "use": "sig",
      "alg": "EdDSA",
      "exp": 1735689600
    }
  ]
}

Signature Verification

Decision Verification

All decisions MUST be verified before acceptance:

Parse signature: Extract Ed25519 signature from signature field
Resolve key: Use kid to fetch public key
Canonicalize: Apply JCS canonicalization to decision payload
Verify signature: Use Ed25519 to verify signature
Check expiration: Ensure expires_at is in the future
Validate digest: Verify passport_digest matches evaluated passport

Passport Verification

Passport integrity is verified through digests:

Canonicalize passport: Apply JCS canonicalization
Compute digest: SHA-256 of canonicalized passport
Compare: Ensure computed digest matches passport_digest

Security Properties

Integrity

Passport integrity: SHA-256 digest ensures passport hasn't been tampered with
Decision integrity: Ed25519 signature ensures decision hasn't been modified
Canonicalization: JCS ensures consistent representation across implementations

Authenticity

Decision authenticity: Ed25519 signature proves decision came from registry
Key authenticity: HTTPS and certificate validation for key resolution
Passport authenticity: Registry signature on active passports

Non-repudiation

Decision non-repudiation: Ed25519 signature provides cryptographic proof
Audit trail: All decisions are logged with signatures
Key rotation: Old keys remain valid for historical verification

Threat Model

Threats Addressed

Passport tampering: Prevented by SHA-256 digests
Decision forgery: Prevented by Ed25519 signatures
Replay attacks: Prevented by expiration times and idempotency keys
Key compromise: Mitigated by key rotation and revocation
Man-in-the-middle: Prevented by HTTPS and certificate validation

Threats Not Addressed

Key theft: Physical security of private keys
Insider attacks: Malicious registry operators
Side-channel attacks: Implementation-specific vulnerabilities
Quantum attacks: Future quantum computing threats

Security Best Practices

For Implementers

Use secure random: Generate UUIDs and keys with cryptographically secure random
Validate inputs: Strictly validate all input data
Check expiration: Always verify decision expiration times
Cache securely: Store decisions securely with proper access controls
Rotate keys: Implement regular key rotation schedule
Monitor logs: Monitor for suspicious activity and key usage

For Deployers

HTTPS only: Use HTTPS for all key resolution and API calls
Certificate validation: Validate TLS certificates properly
Key storage: Store private keys securely (HSM recommended)
Access controls: Implement proper access controls for key management
Monitoring: Monitor key usage and decision patterns
Incident response: Have procedures for key compromise

Suspend Semantics

Global Invalidation

When a passport is suspended or revoked:

Immediate effect: Status change takes effect immediately
Cache invalidation: All caches MUST be purged within 30 seconds
Decision invalidation: All cached decisions become invalid
Notification: Relying parties SHOULD be notified via webhooks

Implementation Requirements

Registry: Must invalidate all cached decisions within 30 seconds
Relying parties: Must treat cached decisions as invalid after suspend
Monitoring: Must detect and alert on suspend/revoke events
Recovery: Must support passport reactivation with new decisions

Compliance

Security Standards

OAP implementations should comply with:

FIPS 140-2: For cryptographic modules (if applicable)
Common Criteria: For high-assurance implementations
SOC 2: For service providers
ISO 27001: For information security management

Audit Requirements

Key usage: Log all key usage and signature operations
Decision audit: Log all policy decisions with full context
Access audit: Log all administrative access to keys and passports
Retention: Retain audit logs for required period (e.g., 7 years)

Product Specifications

File Tree

Open Agent Passport Security Model

Overview