246 lines
5.5 KiB
Markdown
246 lines
5.5 KiB
Markdown
# NTAG424 CMAC 驗證 API 使用說明
|
||
|
||
## 🚀 1. 啟動 API 服務器
|
||
|
||
```bash
|
||
# 啟動服務器（預設端口 8080）
|
||
./cmac_api_server
|
||
|
||
# 或指定自訂端口
|
||
./cmac_api_server 8888
|
||
```
|
||
|
||
啟動成功會看到：
|
||
```
|
||
🚀 CMAC Verification API Server started on port 8888
|
||
📍 Available endpoints:
|
||
GET /verify?uid=...&ctr=...&cmac=...&key=...
|
||
GET /health
|
||
GET /
|
||
🌐 Open http://localhost:8888 in your browser
|
||
```
|
||
|
||
## 🔍 2. 基本 API 呼叫
|
||
|
||
### 健康檢查
|
||
```bash
|
||
curl "http://localhost:8888/health"
|
||
```
|
||
|
||
回應：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "CMAC Verification API is running",
|
||
"timestamp": "2025-07-04T15:30:14Z"
|
||
}
|
||
```
|
||
|
||
### CMAC 驗證
|
||
```bash
|
||
curl "http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=1"
|
||
```
|
||
|
||
## 📝 3. 參數說明
|
||
|
||
| 參數 | 說明 | 格式 | 範例 |
|
||
|--------|----------------------------|----------------|--------------------|
|
||
| `uid` | 卡片 UID | 14位十六進位 | `0456735AD51F90` |
|
||
| `ctr` | SDM 讀取計數器 | 6位十六進位 | `000028` |
|
||
| `cmac` | CMAC 值 | 16位十六進位 | `222ED1BA962F7F5C` |
|
||
| `key` | 金鑰索引（keys.txt中的行號）| 數字 1-10 | `1` |
|
||
|
||
## ✅ 4. 成功回應
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "CMAC verification successful",
|
||
"timestamp": "2025-07-04T15:30:14Z",
|
||
"details": {
|
||
"uid": "0456735AD51F90",
|
||
"counter": "000028",
|
||
"cmac": "222ED1BA962F7F5C",
|
||
"key_index": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
## ❌ 5. 失敗回應
|
||
|
||
### 驗證失敗
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "CMAC verification failed (status: 0x000000CA)",
|
||
"timestamp": "2025-07-04T15:30:14Z"
|
||
}
|
||
```
|
||
|
||
### 參數錯誤
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "Invalid UID format - must be 14 hex characters",
|
||
"timestamp": "2025-07-04T15:30:14Z"
|
||
}
|
||
```
|
||
|
||
### 缺少參數
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "Missing required parameters",
|
||
"timestamp": "2025-07-04T15:30:14Z",
|
||
"required": ["uid", "ctr", "cmac", "key"]
|
||
}
|
||
```
|
||
|
||
## 🌐 6. 完整 URL 範例
|
||
|
||
```bash
|
||
# 基本驗證
|
||
http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=1
|
||
|
||
# 使用不同金鑰
|
||
http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=2
|
||
|
||
# 健康檢查
|
||
http://localhost:8888/health
|
||
|
||
# 首頁說明
|
||
http://localhost:8888/
|
||
```
|
||
|
||
## 💻 7. 程式化呼叫範例
|
||
|
||
### JavaScript (網頁/Node.js)
|
||
```javascript
|
||
async function verifyCMAC(uid, ctr, cmac, keyIndex) {
|
||
const url = `http://localhost:8888/verify?uid=${uid}&ctr=${ctr}&cmac=${cmac}&key=${keyIndex}`;
|
||
|
||
try {
|
||
const response = await fetch(url);
|
||
const result = await response.json();
|
||
|
||
if (result.success) {
|
||
console.log('✅ 驗證成功');
|
||
return true;
|
||
} else {
|
||
console.log('❌ 驗證失敗:', result.message);
|
||
return false;
|
||
}
|
||
} catch (error) {
|
||
console.error('API 呼叫失敗:', error);
|
||
return false;
|
||
}
|
||
}
|
||
|
||
// 使用範例
|
||
verifyCMAC('0456735AD51F90', '000028', '222ED1BA962F7F5C', 1);
|
||
```
|
||
|
||
### Python
|
||
```python
|
||
import requests
|
||
|
||
def verify_cmac(uid, ctr, cmac, key_index):
|
||
url = "http://localhost:8888/verify"
|
||
params = {
|
||
'uid': uid,
|
||
'ctr': ctr,
|
||
'cmac': cmac,
|
||
'key': key_index
|
||
}
|
||
|
||
try:
|
||
response = requests.get(url, params=params, timeout=5)
|
||
result = response.json()
|
||
|
||
if result['success']:
|
||
print(f"✅ 驗證成功: {result['message']}")
|
||
return True
|
||
else:
|
||
print(f"❌ 驗證失敗: {result['message']}")
|
||
return False
|
||
except Exception as e:
|
||
print(f"API 呼叫失敗: {e}")
|
||
return False
|
||
|
||
# 使用範例
|
||
verify_cmac('0456735AD51F90', '000028', '222ED1BA962F7F5C', 1)
|
||
```
|
||
|
||
### PHP
|
||
```php
|
||
<?php
|
||
function verifyCMAC($uid, $ctr, $cmac, $keyIndex) {
|
||
$url = "http://localhost:8888/verify?" . http_build_query([
|
||
'uid' => $uid,
|
||
'ctr' => $ctr,
|
||
'cmac' => $cmac,
|
||
'key' => $keyIndex
|
||
]);
|
||
|
||
$response = file_get_contents($url);
|
||
$result = json_decode($response, true);
|
||
|
||
if ($result['success']) {
|
||
echo "✅ 驗證成功\n";
|
||
return true;
|
||
} else {
|
||
echo "❌ 驗證失敗: " . $result['message'] . "\n";
|
||
return false;
|
||
}
|
||
}
|
||
|
||
// 使用範例
|
||
verifyCMAC('0456735AD51F90', '000028', '222ED1BA962F7F5C', 1);
|
||
?>
|
||
```
|
||
|
||
## 🔧 8. 常見問題
|
||
|
||
### Q: 如何獲取 UID、計數器、CMAC？
|
||
**A**: 這些資料通常來自 NTAG424 卡片的 NDEF URL，格式如：
|
||
```
|
||
https://example.com/nfc?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C
|
||
```
|
||
|
||
### Q: 金鑰索引是什麼？
|
||
**A**: 指向 `keys.txt` 檔案中的第幾行金鑰（從 1 開始計算）
|
||
|
||
### Q: 為什麼驗證失敗？
|
||
**A**: 常見原因：
|
||
- UID、計數器、CMAC 格式不正確
|
||
- 使用了錯誤的金鑰索引
|
||
- 資料已過期或被篡改
|
||
|
||
### Q: 支援 HTTPS 嗎？
|
||
**A**: 目前僅支援 HTTP，生產環境建議使用 nginx 等反向代理提供 HTTPS
|
||
|
||
## 🧪 9. 快速測試
|
||
|
||
執行自動化測試：
|
||
```bash
|
||
./test_api.sh
|
||
```
|
||
|
||
或手動測試：
|
||
```bash
|
||
# 1. 啟動服務器
|
||
./cmac_api_server 8888 &
|
||
|
||
# 2. 測試健康檢查
|
||
curl "http://localhost:8888/health"
|
||
|
||
# 3. 測試 CMAC 驗證
|
||
curl "http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=1"
|
||
|
||
# 4. 停止服務器
|
||
pkill -f cmac_api_server
|
||
```
|
||
|
||
---
|
||
|
||
**需要更多資訊？** 查看 `API_DOCUMENTATION.md` 獲取完整技術文檔。 |