NFCcreate-web/linux64_release/API_USAGE_GUIDE.md

NTAG424 CMAC 驗證 API 使用說明

🚀 1. 啟動 API 服務器

# 啟動服務器（預設端口 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 呼叫

健康檢查

curl "http://localhost:8888/health"

回應：

{
  "success": true,
  "message": "CMAC Verification API is running",
  "timestamp": "2025-07-04T15:30:14Z"
}

CMAC 驗證

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. 成功回應

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

❌ 5. 失敗回應

驗證失敗

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

參數錯誤

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

缺少參數

{
  "success": false,
  "message": "Missing required parameters",
  "timestamp": "2025-07-04T15:30:14Z",
  "required": ["uid", "ctr", "cmac", "key"]
}

🌐 6. 完整 URL 範例

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

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

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
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. 快速測試

執行自動化測試：

./test_api.sh

或手動測試：

# 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 獲取完整技術文檔。