Skip to content

aes-interop-matrix.md

Latest commit

 

History

History
54 lines (37 loc) · 3.42 KB

aes-interop-matrix.md

File metadata and controls

54 lines (37 loc) · 3.42 KB
Raw

AES Cross-Implementation Interop Matrix

Generated by npm run interop. Source vectors: src/data/aes-interop-vectors.json.

Generated: 2026-07-14

CryptoToolkit is an educational AES implementation. This matrix is a parity check against production references (WebCrypto, Python cryptography, OpenSSL) on shared NIST/FIPS test vectors. Parity does not imply production safety. For production, use Web Crypto, libsodium, or Google Tink.

How each column is validated

Column Validation
Toolkit src/__tests__/aes-interop.test.ts runs every vector through aesECB / aesECBDecrypt / aesGCM and asserts byte-for-byte equality with the published ciphertext and tag. CI fails on divergence.
WebCrypto This generator drives crypto.subtle (Node webcrypto) over each vector at matrix-generation time and records PASS/FAIL live. The Vitest suite repeats the same check inside the browser-test runtime.
Python (cryptography) Run scripts/aes-interop/verify_python.py. It loads the same vector pack and asserts AESGCM/Cipher(AES, ECB) from cryptography.hazmat reproduces every ciphertext and tag.
OpenSSL CLI Run scripts/aes-interop/verify_openssl.sh. It verifies AES-ECB with openssl enc -aes-128-ecb -nopad. The OpenSSL enc CLI does not expose reliable AES-GCM AEAD tag verification, so GCM is documented as not applicable here and full AEAD coverage is carried by WebCrypto plus Python cryptography.

AES-ECB (FIPS 197)

Vector Source Toolkit WebCrypto Python cryptography OpenSSL CLI
fips197-appB FIPS 197 Appendix B PASS PASS PASS PASS
fips197-appC1 FIPS 197 Appendix C.1 PASS PASS PASS PASS

AES-GCM (NIST SP 800-38D)

Vector Source Toolkit WebCrypto Python cryptography OpenSSL CLI
sp800-38d-tc2 NIST SP 800-38D Test Case 2 PASS PASS PASS N/A (OpenSSL enc does not expose AEAD GCM tag verification)
sp800-38d-tc3 NIST SP 800-38D Test Case 3 PASS PASS PASS N/A (OpenSSL enc does not expose AEAD GCM tag verification)
sp800-38d-tc4 NIST SP 800-38D Test Case 4 PASS PASS PASS N/A (OpenSSL enc does not expose AEAD GCM tag verification)

Reproducing the Python column

python -m pip install cryptography
python scripts/aes-interop/verify_python.py

The helper exits non-zero on the first vector that fails parity.

Reproducing the OpenSSL column

bash scripts/aes-interop/verify_openssl.sh

Requires openssl, node, and xxd in the path. The helper verifies the ECB vectors with openssl enc -aes-128-ecb -nopad. It intentionally skips AES-GCM because OpenSSL enc does not support AEAD tag verification; use the Python helper for full GCM ciphertext and tag parity.

Refresh policy

  • Add a vector by editing src/data/aes-interop-vectors.json, then re-run npm test and npm run interop.
  • Treat a Vitest interop failure as a correctness regression in the toolkit, not a flaky test.
  • Treat a Python or OpenSSL helper failure as either a corrupted vector pack or a stale system library and investigate before merging.