Algorithm Selection Guide

Choosing the right signing algorithm affects key size, signature size, verification speed, and compliance posture. This guide helps you pick the right one.

Supported Algorithms

RSA-PSS is kept only so JACS can load and verify older artifacts. New RSA key generation, signing, and rotation are disabled.

How to Choose

Do you need FIPS/NIST post-quantum compliance?
  ├── Yes → pq2025
  └── No
       ├── Need a compact classical algorithm for new keys? → ring-Ed25519
       └── Need to verify historical RSA artifacts? → Keep RSA-PSS verification enabled, but create new keys with ring-Ed25519 or pq2025

Default recommendation for new projects: pq2025

Ed25519 is well-understood and widely deployed, but it is not quantum-resistant. If you don't have a specific reason to stay classical, start with pq2025 so you don't have to migrate later.

When to Choose Post-Quantum

Choose pq2025 (ML-DSA-87, FIPS-204) when:

• Your compliance team asks about quantum readiness
• Government or defense contracts require FIPS-204
• You need long-lived signatures that must remain valid for 10+ years
• You want to avoid a future algorithm migration

JACS supports ML-DSA-87 (FIPS-204) for post-quantum digital signatures. When your compliance team asks about quantum readiness, JACS already has the answer.

The tradeoff is size: ML-DSA-87 public keys are 2,592 bytes and signatures are 4,627 bytes -- roughly 80x larger than Ed25519. For most applications this is negligible, but if you're signing millions of small messages and bandwidth matters, consider Ed25519.

Cross-Algorithm Verification

JACS verification works across algorithms. An agreement can contain signatures from legacy RSA, Ed25519, and ML-DSA agents and all verify correctly. This heterogeneous verification is important for cross-organization scenarios where different parties chose different algorithms over time.

Each agent uses one algorithm (chosen at creation time), but can verify signatures from all supported algorithms.

Configuration

Set the algorithm in your jacs.config.json:

{
  "jacs_agent_key_algorithm": "pq2025"
}

Or via environment variable:

export JACS_AGENT_KEY_ALGORITHM=pq2025

Valid values for new keys: ring-Ed25519, pq2025

Legacy compatibility note: RSA-PSS may still appear in stored configs and signed documents so older material can be verified, but it is not supported for creating or rotating new signing keys.

In Python and Node.js, pass the algorithm to quickstart(...):

from jacs.client import JacsClient
client = JacsClient.quickstart(
    name="algo-agent",
    domain="algo.example.com",
    algorithm="pq2025",
)

import { JacsClient } from "@hai.ai/jacs";
const client = await JacsClient.quickstart({
  name: "algo-agent",
  domain: "algo.example.com",
  algorithm: "pq2025",
});

Current Limitations

• Each agent uses one algorithm, chosen at creation time. You cannot change an agent's algorithm after creation.
• Algorithm negotiation between agents is planned but not yet implemented.
• pq-dilithium is deprecated in favor of pq2025 (ML-DSA-87). Use pq2025 for new agents and verification hints.