Skip to content

Commit d02afe9

Browse files
systemslibrariansystemslibrarian
committed
feat: initial Format Ward FPE demo with FF1/FF3-1, accessibility, bug fixes
1 parent c866fb4 commit d02afe9

12 files changed

Lines changed: 1783 additions & 1 deletion

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: true
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
23+
- uses: actions/setup-node@v4
24+
with:
25+
node-version: 20
26+
cache: npm
27+
28+
- run: npm ci
29+
- run: npm run build
30+
31+
- uses: actions/upload-pages-artifact@v3
32+
with:
33+
path: dist
34+
35+
deploy:
36+
needs: build
37+
runs-on: ubuntu-latest
38+
environment:
39+
name: github-pages
40+
url: ${{ steps.deployment.outputs.page_url }}
41+
steps:
42+
- id: deployment
43+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 69 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,69 @@
1-
# crypto-lab-format-ward
1+
# crypto-lab-format-ward
2+
3+
`FF1 · FF3-1 · AES-256 · Feistel Network`
4+
5+
## Overview
6+
7+
Format Ward is a browser-based crypto lab demo for format-preserving encryption (FPE) using FF1 and FF3-1 from NIST SP 800-38G.
8+
9+
The demo shows how sensitive values (credit cards, SSNs, phone numbers, ZIP codes, and custom-alphabet strings) can be encrypted while preserving original format constraints so legacy schema assumptions do not break.
10+
11+
Primary standards references:
12+
13+
- NIST SP 800-38G: https://csrc.nist.gov/pubs/sp/800/38/g/final
14+
- NIST SP 800-38G Rev.1 (FF3-1): https://csrc.nist.gov/pubs/sp/800/38/g/r1/final
15+
16+
## What You Can Explore
17+
18+
1. Credit Card Tokenization panel
19+
2. SSN / Phone / Postal format masking panel
20+
3. FF1 vs FF3-1 side-by-side timing and output comparison
21+
4. Custom alphabet FF1 encryption and decryption
22+
23+
## Primitives Used
24+
25+
- FF1 (NIST SP 800-38G)
26+
- FF3-1 (NIST SP 800-38G Rev.1)
27+
- AES via WebCrypto (`AES-CBC`) as the underlying block primitive
28+
- Feistel round structure per standard mode definitions
29+
30+
## Running Locally
31+
32+
```bash
33+
npm install
34+
npm run dev
35+
```
36+
37+
Build and preview:
38+
39+
```bash
40+
npm run build
41+
npm run preview
42+
```
43+
44+
Run vector checks:
45+
46+
```bash
47+
npm run test
48+
```
49+
50+
## Security Notes
51+
52+
- FF1 is the preferred choice for new deployments in this demo.
53+
- FF3-1 has known differential-attack literature and reduced margin compared to FF1.
54+
- The FF3/FF3-1 line of analysis was highlighted by Durak & Vaudenay (2017); this demo surfaces that caveat directly in UI and documentation.
55+
- Always treat demo code as educational and validate operational choices against your threat model and compliance requirements.
56+
57+
## Why This Matters
58+
59+
Many production systems cannot change field lengths or character constraints without expensive schema and integration rewrites.
60+
61+
FPE allows encryption while preserving the visible format shape, which is useful for tokenization, safe analytics, and controlled data sharing in constrained legacy environments.
62+
63+
## Related Demos
64+
65+
- crypto-compare (Format-Preserving Encryption category): https://github.com/systemslibrarian/crypto-compare
66+
- crypto-lab landing page: https://github.com/systemslibrarian/crypto-lab
67+
- crypto-lab-iron-letter: https://github.com/systemslibrarian/crypto-lab-iron-letter
68+
69+
So whether you eat or drink or whatever you do, do it all for the glory of God. — 1 Corinthians 10:31

‎index.html‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
6+
<meta name="description" content="Format Ward — Interactive browser demo of Format-Preserving Encryption (FF1 and FF3-1) over real WebCrypto AES rounds, per NIST SP 800-38G." />
7+
<meta name="theme-color" content="#0a1216" media="(prefers-color-scheme: dark)" />
8+
<meta name="theme-color" content="#f8fbff" media="(prefers-color-scheme: light)" />
9+
<title>Format Ward | crypto-lab-format-ward</title>
10+
<link rel="stylesheet" href="./styles/main.css" />
11+
</head>
12+
<body>
13+
<div id="app"></div>
14+
<script type="module" src="./src/ui.ts"></script>
15+
</body>
16+
</html>

‎package.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"name": "crypto-lab-format-ward",
3+
"version": "0.1.0",
4+
"private": true,
5+
"type": "module",
6+
"scripts": {
7+
"dev": "vite",
8+
"build": "vite build",
9+
"preview": "vite preview",
10+
"test": "vitest run"
11+
},
12+
"devDependencies": {
13+
"typescript": "^5.6.3",
14+
"vite": "^5.4.10",
15+
"vitest": "^2.1.4"
16+
}
17+
}

0 commit comments

Comments
 (0)