328 lines
7.5 KiB
Markdown
328 lines
7.5 KiB
Markdown
# NTAG424 CMAC 驗證 API 文檔
|
||
|
||
## 概述
|
||
|
||
NTAG424 CMAC 驗證 API 是一個 HTTP 服務，提供 NTAG424 卡片的 CMAC（Cipher-based Message Authentication Code）驗證功能。這個 API 允許遠端驗證 NTAG424 卡片的真實性，無需直接存取讀卡機硬體。
|
||
|
||
## 功能特點
|
||
|
||
- ✅ **純軟體驗證**：無需讀卡機硬體，僅需 UID、計數器、CMAC 和金鑰索引
|
||
- ✅ **HTTP RESTful API**：標準 HTTP GET 請求，易於整合
|
||
- ✅ **JSON 回應格式**：結構化資料回應，易於程式處理
|
||
- ✅ **多金鑰支援**：支援 1-10 個不同的 AES 金鑰
|
||
- ✅ **CORS 支援**：跨域請求支援，適合 Web 應用程式
|
||
- ✅ **詳細錯誤處理**：提供清晰的錯誤訊息和狀態碼
|
||
- ✅ **多執行緒支援**：同時處理多個請求
|
||
|
||
## 快速開始
|
||
|
||
### 1. 啟動服務器
|
||
|
||
```bash
|
||
# 使用預設端口 8080
|
||
./cmac_api_server
|
||
|
||
# 或指定自訂端口
|
||
./cmac_api_server 8888
|
||
```
|
||
|
||
### 2. 基本驗證請求
|
||
|
||
```bash
|
||
curl "http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=1"
|
||
```
|
||
|
||
## API 端點
|
||
|
||
### 1. `/verify` - CMAC 驗證
|
||
|
||
**方法**: `GET`
|
||
**用途**: 驗證 NTAG424 卡片的 CMAC
|
||
|
||
#### 查詢參數
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
|--------|--------|------|----------------------------------------------|--------------------|
|
||
| `uid` | string | ✅ | 卡片 UID (14 位十六進位字元) | `0456735AD51F90` |
|
||
| `ctr` | string | ✅ | SDM 讀取計數器 (6 位十六進位字元) | `000028` |
|
||
| `cmac` | string | ✅ | CMAC 值 (16 位十六進位字元) | `222ED1BA962F7F5C` |
|
||
| `key` | int | ✅ | 金鑰索引 (1-10) | `1` |
|
||
|
||
#### 成功回應 (200 OK)
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "CMAC verification successful",
|
||
"timestamp": "2025-07-04T15:30:14Z",
|
||
"details": {
|
||
"uid": "0456735AD51F90",
|
||
"counter": "000028",
|
||
"cmac": "222ED1BA962F7F5C",
|
||
"key_index": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 驗證失敗回應 (200 OK)
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "CMAC verification failed (status: 0x000000CA)",
|
||
"timestamp": "2025-07-04T15:30:14Z"
|
||
}
|
||
```
|
||
|
||
#### 錯誤回應 (400 Bad Request)
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "Invalid UID format - must be 14 hex characters",
|
||
"timestamp": "2025-07-04T15:30:14Z"
|
||
}
|
||
```
|
||
|
||
### 2. `/health` - 健康檢查
|
||
|
||
**方法**: `GET`
|
||
**用途**: 檢查 API 服務狀態
|
||
|
||
#### 回應 (200 OK)
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "CMAC Verification API is running",
|
||
"timestamp": "2025-07-04T15:30:14Z",
|
||
"version": "1.0",
|
||
"endpoints": ["/verify", "/health"]
|
||
}
|
||
```
|
||
|
||
### 3. `/` - 首頁
|
||
|
||
**方法**: `GET`
|
||
**用途**: 顯示 API 說明頁面
|
||
|
||
回應 HTML 格式的說明頁面，包含可用端點和使用範例。
|
||
|
||
## 錯誤碼
|
||
|
||
| HTTP 狀態碼 | 說明 |
|
||
|-------------|---------------------|
|
||
| 200 | 請求成功（包含驗證失敗） |
|
||
| 400 | 請求參數錯誤 |
|
||
| 405 | 不允許的 HTTP 方法 |
|
||
| 500 | 內部服務器錯誤 |
|
||
|
||
## 使用範例
|
||
|
||
### cURL 範例
|
||
|
||
```bash
|
||
# 基本驗證
|
||
curl "http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=1"
|
||
|
||
# 使用不同金鑰
|
||
curl "http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=2"
|
||
|
||
# 健康檢查
|
||
curl "http://localhost:8888/health"
|
||
```
|
||
|
||
### JavaScript 範例
|
||
|
||
```javascript
|
||
// 驗證 CMAC
|
||
async function verifyCMAC(uid, ctr, cmac, key) {
|
||
const url = `http://localhost:8888/verify?uid=${uid}&ctr=${ctr}&cmac=${cmac}&key=${key}`;
|
||
|
||
try {
|
||
const response = await fetch(url);
|
||
const result = await response.json();
|
||
|
||
if (result.success) {
|
||
console.log('✅ CMAC 驗證成功');
|
||
return true;
|
||
} else {
|
||
console.log('❌ CMAC 驗證失敗:', result.message);
|
||
return false;
|
||
}
|
||
} catch (error) {
|
||
console.error('請求失敗:', error);
|
||
return false;
|
||
}
|
||
}
|
||
|
||
// 使用範例
|
||
verifyCMAC('0456735AD51F90', '000028', '222ED1BA962F7F5C', 1);
|
||
```
|
||
|
||
### Python 範例
|
||
|
||
```python
|
||
import requests
|
||
import json
|
||
|
||
def verify_cmac(uid, ctr, cmac, key, host='localhost', port=8888):
|
||
"""驗證 NTAG424 CMAC"""
|
||
url = f"http://{host}:{port}/verify"
|
||
params = {
|
||
'uid': uid,
|
||
'ctr': ctr,
|
||
'cmac': cmac,
|
||
'key': key
|
||
}
|
||
|
||
try:
|
||
response = requests.get(url, params=params, timeout=5)
|
||
result = response.json()
|
||
|
||
if result['success']:
|
||
print(f"✅ CMAC 驗證成功: {result['message']}")
|
||
return True
|
||
else:
|
||
print(f"❌ CMAC 驗證失敗: {result['message']}")
|
||
return False
|
||
|
||
except requests.RequestException as e:
|
||
print(f"請求錯誤: {e}")
|
||
return False
|
||
|
||
# 使用範例
|
||
verify_cmac('0456735AD51F90', '000028', '222ED1BA962F7F5C', 1)
|
||
```
|
||
|
||
## 部署說明
|
||
|
||
### 本地部署
|
||
|
||
1. **編譯 API 服務器**：
|
||
```bash
|
||
make api-server
|
||
```
|
||
|
||
2. **準備配置檔案**：
|
||
- 確保 `keys.txt` 檔案包含正確的 AES 金鑰
|
||
- 每行一個金鑰，32 位十六進位字元
|
||
|
||
3. **啟動服務器**：
|
||
```bash
|
||
cd linux64_release
|
||
./cmac_api_server 8888
|
||
```
|
||
|
||
### ARM 部署
|
||
|
||
```bash
|
||
# 編譯 ARM64 版本
|
||
make api-server-arm64
|
||
|
||
# 編譯 ARM32 版本
|
||
make api-server-arm32
|
||
|
||
# 複製到 ARM 設備並啟動
|
||
./cmac_api_server 8888
|
||
```
|
||
|
||
### 服務化部署
|
||
|
||
創建 systemd 服務檔案 `/etc/systemd/system/cmac-api.service`：
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=NTAG424 CMAC Verification API
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=your-user
|
||
WorkingDirectory=/path/to/linux64_release
|
||
ExecStart=/path/to/linux64_release/cmac_api_server 8888
|
||
Restart=always
|
||
RestartSec=10
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
啟動服務：
|
||
```bash
|
||
sudo systemctl enable cmac-api
|
||
sudo systemctl start cmac-api
|
||
```
|
||
|
||
## 安全考量
|
||
|
||
1. **金鑰保護**：
|
||
- `keys.txt` 檔案包含敏感的 AES 金鑰
|
||
- 設定適當的檔案權限（例如 600）
|
||
- 避免在日誌中輸出完整金鑰
|
||
|
||
2. **網路安全**：
|
||
- 在生產環境中使用 HTTPS
|
||
- 考慮使用反向代理（如 nginx）
|
||
- 實施速率限制和 IP 白名單
|
||
|
||
3. **輸入驗證**：
|
||
- API 已實施基本的輸入格式驗證
|
||
- 建議在客戶端也進行額外驗證
|
||
|
||
## 效能資訊
|
||
|
||
- **記憶體使用**：約 ~500KB
|
||
- **CPU 使用**：每次驗證 ~1ms
|
||
- **並發支援**：最多 10 個同時連接
|
||
- **吞吐量**：約 1000+ 驗證/秒（取決於硬體）
|
||
|
||
## 故障排除
|
||
|
||
### 常見問題
|
||
|
||
1. **端口已被使用**：
|
||
```
|
||
bind failed: Address already in use
|
||
```
|
||
解決：使用不同端口或停止占用程序
|
||
|
||
2. **找不到金鑰檔案**：
|
||
```
|
||
無法開啟 keys.txt 檔案
|
||
```
|
||
解決：確保 `keys.txt` 在執行目錄中
|
||
|
||
3. **連接被拒絕**：
|
||
- 檢查服務器是否正在運行
|
||
- 檢查防火牆設定
|
||
- 驗證端口號
|
||
|
||
### 除錯模式
|
||
|
||
啟動時可以看到詳細的啟動訊息和請求日誌。
|
||
|
||
## 技術規格
|
||
|
||
- **語言**：C
|
||
- **HTTP 服務器**：自定義輕量級實作
|
||
- **JSON 處理**：手動序列化
|
||
- **執行緒模型**：每請求一執行緒
|
||
- **依賴**：uFCoder 函式庫、pthread
|
||
|
||
## 版本歷史
|
||
|
||
- **v1.0** (2025-07-04)：初始版本
|
||
- 基本 CMAC 驗證功能
|
||
- HTTP API 介面
|
||
- 多金鑰支援
|
||
- 錯誤處理
|
||
|
||
## 授權
|
||
|
||
本軟體遵循與主專案相同的授權條款。
|
||
|
||
---
|
||
|
||
**製作**: 基於 NTAG424 管理工具開發
|
||
**更新**: 2025-07-04 |