Implementation Manual

VeriCrypt is a single, statically-linked binary with zero runtime dependencies. Deployment requires no package manager, no database, no cloud connectivity, and no network egress during scan operations. This guide covers every step from download to regulator-ready .pqc report.

1. System Requirements

Production Scan Host

• Linux kernel 5.15+ (x86_64 or ARM64)
• 8+ cores, 32 GB RAM, 512 GB SSD
• Intel TDX or AMD SEV-SNP enabled (optional, for TEE attestation)
• Root access (required only for TEE device file access: /dev/tdx_guest or /dev/sev-guest)
• No network egress required during scan — air-gapped by design

Evaluation / Pilot Host

• Linux kernel 5.15+ (x86_64)
• 4 cores, 16 GB RAM, 100 GB free disk
• TEE optional — runs in simulation mode without hardware attestation

2. Binary Download & Verification

On an internet-connected machine, visit the Download Portal and enter your licence key. Select your platform and binary:

Binary	Purpose	Platforms
vericrypt	Compliance scanner — ingests certificates, executes pipeline, produces .pqc report	linux-x86_64, linux-arm64
vericrypt-verify	Offline verifier — independently validates .pqc reports (freely distributable to regulators)	linux-x86_64, linux-arm64

Verify integrity before use:

sha256sum vericrypt
sha256sum vericrypt-verify
# Compare against the published checksums on the download page

file vericrypt
# Expected: ELF 64-bit LSB executable, x86-64, statically linked, stripped
# Verify: no dynamic dependencies
ldd vericrypt
# Expected: not a dynamic executable

3. Transfer to Air-Gapped Host

Transfer both binaries to the scan host via approved media:

• USB drive (mounted read-only after transfer)
• Internal file share (temporary, disconnected before scan)
• SFTP to staging host (then disconnected before scan)

# On the air-gapped scan host
chmod +x vericrypt vericrypt-verify
./vericrypt --version
# Expected: vericrypt 0.1.0

4. Licence Activation

Activate your licence key on the air-gapped host. The binary validates the PASETO v4 token offline using its embedded public key — no network call is made.

./vericrypt activate --key $LICENSE_KEY

The activation process verifies:

• PASETO v4.public Ed25519 signature against embedded public key
• Token expiry date
• Binary hash scope — the licence is bound to the specific binary version
• Capability claims: tier, max_assets, features

Alternatively, set the licence key as an environment variable:

export VERICRYPT_LICENSE_KEY="v4.public.eyJ..."

5. Certificate Inventory Preparation

Gather all cryptographic assets into a directory tree accessible from the scan host. VeriCrypt performs recursive directory traversal — nested subdirectories are processed automatically.

Supported File Formats

Format	Extension	Description
PEM Certificate	.pem, .crt, .cer	PEM-encoded X.509 certificates
PEM Private Key	.key	PKCS#1, PKCS#8, SEC1 private keys
DER Certificate	.der	DER-encoded X.509 certificates
PKCS#12 Keystore	.p12, .pfx	Password-protected keystores
CSV Inventory	.csv	CMDB exports with columns: host, port, cert_path, algorithm, key_size, expiry, usage_context
JSON Inventory	.json	CMDB JSON export with "certificates" array containing algorithm, key_size, expiry, fingerprint

CSV Format Specification

host,port,cert_path,algorithm,key_size,expiry,usage_context
lb.example.com,443,/etc/ssl/certs/lb.pem,RSA-2048,2048,2027-03-15,external_tls
internal.db.example.com,5432,/etc/ssl/certs/db.pem,ECDSA-P256,256,2026-11-01,database_tls

JSON Format Specification

{
  "certificates": [
    {
      "host": "lb.example.com",
      "port": 443,
      "algorithm": "RSA-2048",
      "key_size": 2048,
      "expiry": "2027-03-15T00:00:00Z",
      "fingerprint": "a1b2c3...",
      "usage_context": "external_tls"
    }
  ]
}

6. Running Scans

6.1 First Scan — Unsigned (Evaluation)

./vericrypt scan \
  --cert-dir /data/certificates/ \
  --output ./vericrypt-report/

This executes the full 7-stage pipeline and produces an unsigned report. Use this to validate the pipeline, verify certificate parsing, and confirm inventory completeness before purchasing a licence.

6.2 Licensed Scan — Signed Report

./vericrypt scan \
  --cert-dir /data/certificates/ \
  --network 10.0.0.0/8 \
  --mode primary \
  --output ./report/

With an active licence, the .pqc report is signed with SLH-DSA (NIST FIPS 205). The signature binds the Merkle root of all findings, the scan timestamp, and the TEE attestation quote (if available).

6.3 Network Scanning

./vericrypt scan \
  --cert-dir /data/certificates/ \
  --network 10.0.0.0/8 \
  --output ./report/

Probes all hosts in the specified CIDR range for TLS endpoints. Each endpoint's certificate is parsed, fingerprinted, and added to the cryptographic asset inventory. Works with internal RFC 1918 addresses.

6.4 Deployment Modes

--mode shadow     # Phase 1: Reports generated but not submitted to regulators
--mode parallel   # Phase 2: Reports submitted alongside traditional documentation
--mode primary    # Phase 3: .pqc files are the primary compliance evidence

6.5 Custom Regulatory Axioms (Mode 2)

./vericrypt scan \
  --cert-dir /data/certificates/ \
  --load-bytecode /opt/vericrypt/custom-framework.aslb \
  --output ./report/

The --load-bytecode flag loads a custom-compiled ASL bytecode file. Use this when the bank's legal counsel or compliance team has edited the axiom source files to reflect jurisdiction-specific requirements. The resulting .pqc report is proved against the custom rules, with a full verifiable execution trace.

6.6 VeriChain Signed Tree Head Export

./vericrypt scan \
  --cert-dir /data/certificates/ \
  --publish-sth \
  --output ./report/

Exports an RFC 6962-compatible Signed Tree Head to sth.json for optional VeriChain anchoring. Provides cross-institutional consistency proofs and non-equivocation guarantees.

6.7 Full Command Reference

Flag	Argument	Description
--cert-dir	path	Directory containing certificates to scan (recursive)
--network	CIDR	Network range to probe for TLS endpoints
--output	path	Output directory for .pqc report and CBOM (default: ./report/)
--mode	shadow|parallel|primary	Deployment phase (default: shadow)
--load-bytecode	path	Custom ASL bytecode file for Mode 2/3 axioms
--publish-sth	—	Export Signed Tree Head for VeriChain anchoring

7. Output Files

File	Format	Description
report.pqc	JSON	Signed compliance artifact — Merkle-proofed, SLH-DSA signed. Contains: report metadata, CBOM Merkle root, compliance theorems with ASL VM execution trace, TEE attestation quote, PKI certificate chain, SLH-DSA signature. This is the primary regulatory submission artefact.
cbom.json	JSON	CycloneDX 1.7 Cryptographic Bill of Materials (ECMA-424). Every asset as a component with cryptoProperties: algorithm, keySize, mode, padding, curve, quantumSecurityLevel. PQC algorithm naming per CycloneDX Cryptography Registry.
roadmap.md	Markdown	Prioritized PQC migration roadmap — Phase 1 (0–12 months), Phase 2 (12–24 months), Phase 3 (24–36 months). Shapley-ranked by exposure contribution. EU 2026/2030/2035 milestone alignment.
violations.txt	Text	Specific compliance violations with asset IDs, regulatory references, and remediation recommendations. Only generated if ASL VM produces counterexamples.
verify.sh	Shell Script	Self-contained verification script for regulators. Bundles the verification procedure into a single executable script.
sth.json	JSON	RFC 6962 Signed Tree Head for VeriChain anchoring. Only generated when --publish-sth flag is used.

8. Scan Output Interpretation

During execution, VeriCrypt writes structured JSON logs to stderr. A summary is printed upon completion:

=== VERICRYPT SCAN COMPLETE ===
  Mode: PRIMARY (Phase 3)
  Assets discovered: 2,437
  Quantum-vulnerable: 1,182
  Compliance violations: 12
  Compliance confidence: 0.87 (proof=1.00 × inventory=0.87 × axiom=1.00)
  Inventory confidence: High (87%)
  Report: ./report/report.pqc

Understanding Compliance Confidence

The compliance confidence score is a multiplicative composite of three independent factors:

Factor	Range	Meaning
Proof Confidence (P)	0.0–1.0	1.0 = ASL VM execution successful, all frameworks proved. 0.7 = Some theorems unverified. 0.3 = Degraded mode.
Inventory Confidence (I)	0.0–1.0	Derived from visibility score: endpoint coverage, subnet coverage, cert transparency correlation, AD/LDAP reconciliation, HSM reconciliation, duplicate chain analysis, expected-vs-observed entropy, network topology consistency.
Regulatory Axiom Confidence (R)	0.0–1.0	1.0 = Axioms reviewed and signed by qualified regulatory expert. 0.8 = Reviewed by internal compliance team. 0.5 = Auto-generated without human review.

The composite score is compliance_confidence = P × I × R. Thresholds for deployment modes:

• Phase 3 (Primary): ≥ 0.90
• Phase 2 (Parallel): ≥ 0.70
• Phase 1 (Shadow): ≥ 0.50

Stage Timing Output

In verbose mode (VERICRYPT_LOG_LEVEL=DEBUG), per-stage timing is reported:

Stage	Complexity	Typical (10K certs)
Ingestion	O(n)	~30 seconds
Knowledge Graph Building	O(n log n)	~10 seconds
HNDL Exposure Analysis	O(n²) exact / O(n) Monte Carlo	~15 seconds
ASL VM Compliance Verification	VM execution	~3 seconds
Prioritization & Roadmap	O(n log n)	~2 seconds
CBOM Generation	O(n)	~2 seconds
Report Assembly & Signing	O(n) + O(1) signing	~3 seconds
Total		~60 seconds

9. Environment Variables

Variable	Values	Purpose
VERICRYPT_LICENSE_KEY	PASETO v4 token	Licence key for signed report generation. Alternative to --key flag on activate command.
VERICRYPT_DATA_DIR	path	Directory for algorithm database and cached certificates. Default: ~/.vericrypt/
VERICRYPT_LOG_LEVEL	ERROR, WARN, INFO, DEBUG, TRACE	Log verbosity. Default: INFO. DEBUG shows per-asset details. TRACE shows full parse output.
VERICRYPT_SCAN_TIMEOUT	seconds	Maximum duration per scan target. Prevents hung scans on unresponsive endpoints.
VERICRYPT_PROOF_TIMEOUT	seconds	Maximum duration per ASL VM framework execution. Prevents hung compliance verification.
VERICRYPT_TEE_ATTESTATION	1, 0, auto	Enable/disable TEE attestation. Default: auto-detect. Set to 0 to skip even if TEE is available.

10. TEE Attestation

VeriCrypt auto-detects Intel TDX or AMD SEV-SNP at scan time. When available, a hardware-signed attestation quote is collected and embedded in the .pqc report header. The quote binds the binary's measurement to the report, cryptographically proving the scan ran untampered.

Requirements

• Intel TDX: /dev/tdx_guest device file accessible
• AMD SEV-SNP: /dev/sev-guest device file accessible
• Root access (required only for TEE device file access)
• CPU vendor root of trust certificates embedded in vericrypt-verify

Attestation Quote Contents

• TDX: MRTD (measurement of the Trust Domain), RTMRs (runtime measurements)
• SNP: Launch measurement, guest policy
• Certificate chain back to CPU vendor root of trust (Intel PCS or AMD KDS)

When TEE is unavailable, the .pqc report is generated without hardware trust anchor and marked accordingly. The core cryptographic proof (Merkle root + SLH-DSA signature) remains valid without TEE.

# Check TEE status
./vericrypt scan --cert-dir /data/certs/ 2>&1 | grep -i tee
# Expected: TEE Attestation: Active (Intel TDX) or TEE Attestation: Unavailable (no TEE hardware)

11. Regulator Verification Procedure

The vericrypt-verify binary is freely distributable. Regulators use it to independently verify .pqc reports without access to the bank's systems, without trust in Verity, and without network connectivity.

Verification Steps

1. Bank submits report.pqc to regulator via email or portal
2. Regulator runs the offline verifier:

./vericrypt-verify ./report.pqc

What the Verifier Checks

1. SLH-DSA signature validity — verifies the signature over (Merkle root + metadata) using embedded Verity public key
2. Merkle root consistency — recomputes Merkle root from CBOM contents and compares against signed root
3. ASL VM execution trace — supports --replay flag for bit-identical re-execution of compliance bytecode against the inventory hash
4. TEE attestation quote (if present) — verifies attestation signature against Intel/AMD root certificates
5. Certificate chain — verifies PKI chain from signing key to Root Verity Authority Key
6. Revocation check — verifies signing certificate against offline revocation bundle

Verification Output

# Success:
VERIFIED — scan at 2026-06-05T14:30:00Z, 2,437 assets, 12 violations

# Failure modes:
VERIFICATION FAILED — signature does not verify. Report tampered.
VERIFICATION FAILED — CBOM contents do not match signed root.
VERIFICATION FAILED — TEE attestation quote invalid.

12. Troubleshooting

Common Issues

Symptom	Likely Cause	Resolution
"Licence validation failed"	Expired or invalid PASETO token	Verify token expiry date. Contact channel sales for renewal. Check binary hash matches licence scope.
"Permission denied" on cert files	Insufficient read permissions	Ensure scan user has read access to certificate directory tree. Use chmod -R +r if needed.
"Not a directory" error	--cert-dir path does not exist	Verify the path is correct and accessible. Use absolute paths.
"Network unreachable" on TLS probe	Target endpoint down or firewalled	Recorded as "unreachable" in inventory. Scan continues. Verify network connectivity from scan host.
"TLS handshake timeout"	Endpoint not responding to TLS	Recorded with timeout metadata. Adjust VERICRYPT_SCAN_TIMEOUT if needed.
"ASL VM execution failed"	Corrupt or invalid bytecode file	Recompile axiom source through seedc. Verify bytecode file integrity.
"Signing key unavailable"	Licence not activated or expired	Run ./vericrypt activate --key $LICENSE_KEY. Verify licence state with --version.
No TEE attestation in report	TEE hardware not available or not configured	Verify /dev/tdx_guest or /dev/sev-guest exists. Check root access. TEE is optional — report is valid without it.

Debug Mode

# Enable verbose logging for troubleshooting
export VERICRYPT_LOG_LEVEL=DEBUG
./vericrypt scan --cert-dir /data/certificates/ --output ./report/ 2> debug.log

# Trace mode shows full parse output (large files)
export VERICRYPT_LOG_LEVEL=TRACE
./vericrypt scan --cert-dir /data/certificates/ --output ./report/ 2> trace.log

Verifying Installation Integrity

# Confirm static linking
file vericrypt
# Expected: statically linked

ldd vericrypt
# Expected: not a dynamic executable

# Verify binary hash matches licence scope
sha256sum vericrypt
# Compare against the binary_hash claim in your PASETO token

13. Support

For deployment assistance, licence issues, or technical questions: