Run the CALI reference service

Prerequisites

Git 2.40 or later;
Python 3.12 or later;
curl for the quickstart; and
a local port, default 8080.

The service is a development reference. It stores keys in memory, loses them on restart and is not a production key-management system.

Clone and install

git clone https://github.com/ganeshmallaya/cali-crypto-interface.git
cd cali-crypto-interface
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'

Validate before running

.venv/bin/python -m unittest discover -s apiValidation -v
.venv/bin/python implementation/conformance/run_conformance.py

Expected result: every contract and reference-service test reports ok, followed by an OK summary. A missing jsonschema module means the virtual environment was not activated or the editable install did not complete.

Start the service

CALI_PORT=8080 .venv/bin/python -m cali_reference

Expected startup output:

CALI research server listening on http://127.0.0.1:8080

Execute the quickstart

In a second terminal:

CALI_API_URL=http://127.0.0.1:8080 sh implementation/examples/quickstart.sh

The script creates a key, signs a message, verifies the signature and prints a final verification result of true. It uses only public test data and an opaque key reference.

Run the Apache migration example

The Apache flow starts its own CALI service and local HTTPS application:

sh implementation/examples/apache-login-pqc/run_demo.sh

The case starts with a local RSA-2048 certificate, selects an already available ML-DSA-65 certificate under strict policy, validates the Apache configuration, gracefully reloads and verifies that a new local TLS handshake presents ML-DSA-65. It also verifies the signed selection evidence independently.

Expected output:

PASS: Apache started with RSA-2048.
PASS: Strict CALI policy selected ML-DSA-65 and Apache reloaded.
PASS: A new TLS handshake presented ML-DSA-65 and the evidence signature verified.

macOS includes Apache at /usr/sbin/httpd. OpenSSL 3.5 or later is required to create the ML DSA test certificate. The test uses loopback ports 18085 and 18443. Override them with CALI_APACHE_API_PORT and CALI_APACHE_HTTPS_PORT.

The result is evidence for the named local environment. It does not establish public-PKI, browser or cross-implementation interoperability.

Enable development authentication

CALI_AUTH_TOKEN='local-development-only' .venv/bin/python -m cali_reference

Then provide Authorization: Bearer local-development-only. Never commit a real token or put it in examples, logs, screenshots or shell history used for documentation.

Troubleshooting

Symptom	Likely cause	Corrective action
`ModuleNotFoundError`	dependencies installed outside active venv	use `.venv/bin/python` or activate `.venv`
address already in use	port collision	set `CALI_PORT` to another local port
`AUTHENTICATION_FAILED`	token required or incorrect	send the configured development bearer token
`CAPABILITY_MISMATCH`	requested profile unavailable	inspect scoped capabilities; do not force fallback
key not found after restart	in-memory provider reset	create a new development key

Production boundary

Before production use, an implementation needs durable encrypted storage, real workload identity, authorization, protected evidence, rate and size limits, provider hardening, recovery, monitoring and an independent security review.