This document outlines the security policy for the physjitter crate, including vulnerability reporting, threat model, security considerations, and secure usage guidelines.

• Supported Versions
• Reporting a Vulnerability
• Threat Model
• Security Models
• Secure Usage Guidelines
• Known Limitations
• Dependency Security
• Cryptographic Implementations
• Secure Development Practices
• SLSA Compliance
• Security Audits
• Security Updates
• Security Hall of Fame

We support the latest minor version with security patches. Critical vulnerabilities may receive backports to earlier versions at maintainer discretion.

We take security vulnerabilities seriously. If you discover a security issue, please report it responsibly.

⚠️ Please do NOT report security vulnerabilities through public GitHub issues.

Report vulnerabilities via one of the following methods (in order of preference):

1. GitHub Security Advisories (Preferred)

   • Navigate to the Security tab
   • Click "Report a vulnerability"
   • This enables private discussion and coordinated disclosure

2. Email

   • Send details to: security@writerslogic.com
   • Use our PGP key for sensitive reports (key ID below)

For encrypted communications:

Key ID: [To be added]
Fingerprint: [To be added]

Key available at: https://writerslogic.com/.well-known/security.txt

Please provide as much of the following as possible:

• We will acknowledge receipt within 48 hours
• We will keep you informed throughout the process
• We will work with you to understand and validate the issue
• We will credit you in the security advisory (unless you prefer anonymity)
• We will not pursue legal action against good-faith researchers

For confirmed vulnerabilities:

• We request CVE IDs through GitHub Security Advisories
• CVEs are published after a fix is available
• Coordinated disclosure date is agreed upon with the reporter

physjitter is designed to provide proof-of-process through timing jitter. It is NOT:

• A replacement for traditional authentication
• A source of cryptographically secure random numbers
• A digital signature scheme
• Suitable for high-stakes security decisions without additional verification

Threat: Attacker captures and replays valid evidence chains.

Mitigations:

• Evidence chains include timestamps
• PhysJitter includes hardware-bound entropy
• Application should bind evidence to session context

Residual Risk: Pure jitter mode without timestamps could be replayed.

Threat: Secret extraction through timing analysis.

Mitigations:

• HMAC computation uses constant-time primitives from hmac crate
• Jitter delays are within human typing range (500-3000μs)
• Statistical model validates timing distribution

Residual Risk: Sophisticated attackers with many samples may extract partial information.

Threat: Session secret extracted from memory.

Mitigations:

• Secrets should use proper key derivation (HKDF, Argon2)
• Application should use memory-locking where available
• Session secrets should be rotated periodically

Residual Risk: Local privileged attacker can extract secrets from memory.

Threat: Attacker provides fake hardware entropy in VM.

Mitigations:

• HybridEngine detects low entropy and falls back to pure mode
• Evidence records include mode indicator (Phys vs Pure)
• Applications can require minimum phys_ratio() threshold

Residual Risk: Sophisticated VM can simulate hardware entropy.

Threat: Attacker crafts timing that passes human validation.

Mitigations:

• Model trained on 136M real keystrokes
• Multiple anomaly detection methods
• Configurable sensitivity thresholds

Residual Risk: Determined attacker may evade detection with sufficient effort.

Principle: Security relies on the economic cost of reproducing input sequences.

Appropriate for:

• Virtualized environments
• WebAssembly targets
• Low-stakes verification

Principle: Hardware entropy provides non-reproducible binding.

Appropriate for:

• Native desktop applications
• High-stakes verification
• When hardware is trusted

Principle: Use best available security, record which mode was used.

// ❌ BAD: Hardcoded secret
let secret = [0u8; 32];

// ✅ GOOD: Derive from secure source
use sha2::{Sha256, Digest};
let user_key = get_secure_key(); // From password KDF, HSM, etc.
let mut hasher = Sha256::new();
hasher.update(user_key);
hasher.update(b"physjitter-session-v1");
let secret: [u8; 32] = hasher.finalize().into();

use physjitter::{HybridEngine, Session};

// Production configuration
let engine = HybridEngine::builder()
    .min_entropy_bits(8)        // Require meaningful entropy
    .jitter_range(500, 3000)    // Human typing range
    .build();

let mut session = Session::with_engine(secret, engine);

// Always validate evidence before trusting
let result = session.validate();

// Check both human detection AND physics ratio
if result.is_human && session.evidence().phys_ratio() >= 0.8 {
    // High confidence: human + hardware bound
} else if result.is_human {
    // Medium confidence: human but economic security only
} else {
    // Reject: failed human detection
}

Evidence chains are automatically keyed with the session secret for tamper detection:

// Session automatically creates keyed evidence chain
let session = Session::new(secret);

// After collecting evidence, verify integrity
if !session.evidence().verify_integrity(&secret) {
    // Chain has been tampered with!
    panic!("Evidence chain integrity check failed");
}

Session secrets are automatically zeroized when the session is dropped:

use physjitter::Session;

{
    let session = Session::new(secret);
    // ... use session ...
} // Secret automatically cleared from memory here

// Manual zeroization is no longer needed for Session

Hardware entropy detection may be unreliable in:

• Nested virtualization
• Paravirtualized environments
• Some cloud instances (inconsistent TSC)

Mitigation: Always check phys_ratio() and set appropriate thresholds.

Timing measurements depend on:

• OS scheduler precision
• CPU frequency scaling
• System load

Mitigation: Model validation accounts for expected variance.

Jitter delays could theoretically leak information about:

• Secret values (through HMAC computation time)
• Input content (through correlation analysis)

Mitigation: Uses constant-time HMAC; jitter range masks exact values.

Evidence is not cryptographically bound to a specific device beyond hardware entropy.

Mitigation: Application should add device attestation if required.

physjitter
├── hmac 0.12 (RustCrypto)
├── sha2 0.10 (RustCrypto)
├── subtle 2.5 (RustCrypto) - constant-time operations
├── zeroize 1.7 (RustCrypto) - secure memory clearing
├── serde 1.0
├── serde_json 1.0
├── thiserror 2.0
├── getrandom 0.3
└── rand 0.8 (optional)

All cryptographic dependencies are from the RustCrypto project, which undergoes regular security audits.

All HMAC operations use context-specific prefixes to prevent key reuse vulnerabilities:

Evidence chains can be bound to session secrets via HMAC:

// Create keyed chain (tamper-evident)
let chain = EvidenceChain::with_secret(session_secret);

// Verify integrity
if !chain.verify_integrity(&session_secret) {
    // Chain has been tampered with
}

We do NOT implement custom cryptographic primitives.

• All changes require code review
• CI enforces formatting (rustfmt)
• CI enforces linting (clippy with -D warnings)
• No unsafe code in main crate (zero unsafe blocks)
• MSRV policy enforced

• Minimal permissions (read-only where possible)
• Dependabot for automated updates
• Signed commits encouraged
• Protected branches on main

This project follows SLSA (Supply-chain Levels for Software Artifacts) guidelines:

# Install slsa-verifier
go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@latest

# Download release artifact and provenance
curl -LO https://github.com/writerslogic/physjitter/releases/download/v0.1.0/physjitter-0.1.0.crate
curl -LO https://github.com/writerslogic/physjitter/releases/download/v0.1.0/multiple.intoto.jsonl

# Verify
slsa-verifier verify-artifact physjitter-0.1.0.crate \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/writerslogic/physjitter \
  --source-tag v0.1.0

We welcome security audits. If you're interested in auditing this crate, please contact us.

• Memory safety (safe Rust only)
• Dependency audit (no known vulnerabilities)
• Cryptographic review (uses audited RustCrypto crates)
• Threat model documented
• Formal verification (not applicable)
• Third-party audit (planned)

Security updates are released as:

1. Watch this repository with "Security alerts" enabled
2. Enable Dependabot alerts in your projects
3. Monitor RustSec advisories via cargo-audit

We gratefully acknowledge security researchers who have responsibly disclosed vulnerabilities:

Want to be listed here? Report a valid security issue!

• Security issues: security@writerslogic.com
• GitHub Security Advisories: Report here
• General questions: GitHub Discussions

Last updated: 2025-02