ipwxp fcccb1789b frist

2025-09-25 19:04:00 +08:00

7.5 KiB

Raw Permalink Blame History

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. 啟動服務器

# 使用預設端口 8080
./cmac_api_server

# 或指定自訂端口
./cmac_api_server 8888

2. 基本驗證請求

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)

{
  "success": true,
  "message": "CMAC verification successful",
  "timestamp": "2025-07-04T15:30:14Z",
  "details": {
    "uid": "0456735AD51F90",
    "counter": "000028",
    "cmac": "222ED1BA962F7F5C",
    "key_index": 1
  }
}

驗證失敗回應 (200 OK)

{
  "success": false,
  "message": "CMAC verification failed (status: 0x000000CA)",
  "timestamp": "2025-07-04T15:30:14Z"
}

錯誤回應 (400 Bad Request)

{
  "success": false,
  "message": "Invalid UID format - must be 14 hex characters",
  "timestamp": "2025-07-04T15:30:14Z"
}

2. `/health` - 健康檢查

方法: GET
用途: 檢查 API 服務狀態

回應 (200 OK)

{
  "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 範例

# 基本驗證
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 範例

// 驗證 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 範例

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)

部署說明

本地部署

編譯 API 服務器：
```
make api-server
```
準備配置檔案：
- 確保 keys.txt 檔案包含正確的 AES 金鑰
- 每行一個金鑰，32 位十六進位字元

啟動服務器：

cd linux64_release
./cmac_api_server 8888

ARM 部署

# 編譯 ARM64 版本
make api-server-arm64

# 編譯 ARM32 版本
make api-server-arm32

# 複製到 ARM 設備並啟動
./cmac_api_server 8888

服務化部署

創建 systemd 服務檔案 /etc/systemd/system/cmac-api.service：

[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

啟動服務：

sudo systemctl enable cmac-api
sudo systemctl start cmac-api

安全考量

金鑰保護：
- keys.txt 檔案包含敏感的 AES 金鑰
- 設定適當的檔案權限（例如 600）
- 避免在日誌中輸出完整金鑰
網路安全：
- 在生產環境中使用 HTTPS
- 考慮使用反向代理（如 nginx）
- 實施速率限制和 IP 白名單
輸入驗證：
- API 已實施基本的輸入格式驗證
- 建議在客戶端也進行額外驗證

效能資訊

記憶體使用：約 ~500KB
CPU 使用：每次驗證 ~1ms
並發支援：最多 10 個同時連接
吞吐量：約 1000+ 驗證/秒（取決於硬體）

故障排除

常見問題

端口已被使用：
```
bind failed: Address already in use
```
解決：使用不同端口或停止占用程序
找不到金鑰檔案：
```
無法開啟 keys.txt 檔案
```
解決：確保 keys.txt 在執行目錄中
連接被拒絕：
- 檢查服務器是否正在運行
- 檢查防火牆設定
- 驗證端口號

除錯模式

啟動時可以看到詳細的啟動訊息和請求日誌。

技術規格

語言：C
HTTP 服務器：自定義輕量級實作
JSON 處理：手動序列化
執行緒模型：每請求一執行緒
依賴：uFCoder 函式庫、pthread

版本歷史

v1.0 (2025-07-04)：初始版本
- 基本 CMAC 驗證功能
- HTTP API 介面
- 多金鑰支援
- 錯誤處理

授權

本軟體遵循與主專案相同的授權條款。

製作: 基於 NTAG424 管理工具開發
更新: 2025-07-04

7.5 KiB Raw Permalink Blame History Unescape Escape