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