# API 傳遞資料需要額外加密嗎？


在企業系統中，前後端之間的 API 呼叫除了要確保**資料完整性**，更應考慮**多層次的傳輸安全性**。
許多人可能會問：

> **「我們已經使用 HTTPS 了，為什麼還需要額外的 API Payload 加密？」**

確實，HTTPS（TLS）能保護傳輸通道的安全，但這層保護**僅止於傳輸階段**，以下是常見的潛在風險：

1. **伺服器端或中間節點被入侵**
HTTPS 保護的是傳輸過程，但若 API Server、WAF、代理伺服器或反向代理遭入侵，攻擊者仍有可能攔截明碼資料。
2. **API Key 或 Token 遭竊用**
即使受 HTTPS 保護，若密鑰在伺服器或用戶端端點洩漏，攻擊者可直接偽造合法請求。
3. **內部人員或第三方系統誤用**
即便透過 HTTPS，若內部人員能攔截封包，仍可能進行重放攻擊 (Replay Attack) 或竄改資料。
4. **企業內部非公開網段的風險**
ERP / HRM 系統多數部署於內網，但資料可能跨多個網段或 VPN 傳輸，若缺乏額外加密，仍存在資安漏洞。

👉 簡而言之：**HTTPS 是第一層防線，API Payload 加密則是第二層防護**。
當 HTTPS 被繞過或節點遭入侵時，資料本身依舊能保持安全。

📦 範例程式：[jsonrpc-sample](https://github.com/jeff377/jsonrpc-sample)

---

## 🔑 API 加密金鑰的產生與載入

### 1. 產生 API 加密金鑰（後端設定）

可透過 `BeeSettingsEditor` 工具的 **Generate API Encryption Key** 功能，產生一組新的 AES + HMAC 金鑰，並以 Master Key 加密後儲存在設定檔 (`SecurityKeySettings.ApiEncryptionKey`) 中

📘 詳細操作說明：[BeeSettingsEditor](https://github.com/jeff377/bee-library/tree/main/tools/BeeSettingsEditor)

---

### 2. 後端載入 API 加密金鑰

`JsonRpcServer` 啟動時，會自動解密設定檔內的 API 加密金鑰，並寫入 `BackendInfo.ApiEncryptionKey`，供後續 API 呼叫加密使用：

BackendInfo.ApiEncryptionKey = 
    EncryptionKeyProtector.DecryptEncryptedKey(masterKey, settings.ApiEncryptionKey);

---

## 🌐 前端取得 API 加密金鑰流程

1. 前端在登入前**產生一組 RSA 金鑰對**（公鑰 + 私鑰）。
2. 登入 (`Login`) 時，連同帳密一併傳送 RSA 公鑰至後端。
3. 後端收到後，使用前端 RSA 公鑰**加密 API 加密金鑰**並回傳。
4. 前端收到後，用 RSA 私鑰解密，存入 `FrontendInfo.ApiEncryptionKey`，後續 API 傳遞資料就可以 AES+HMAC 進行加密。

flowchart LR
    A[Frontend Client] --HTTPS--> B[API Server]
    B -- RSA Key Wrapping --> A
    A -- AES+HMAC Encrypted API Data --> B

> 此流程確保 **API 加密金鑰僅存在於前後端記憶體中**，不會以明碼傳輸。

簡化程式範例如下：

// 前端產生 RSA 金鑰
RsaCryptor.GenerateRsaKeyPair(out var publicKeyXml, out var privateKeyXml);

// Login 一併傳送 RSA 公鑰
var loginArgs = new LoginArgs 
{ 
    UserId = "jeff", 
    Password = "1234", 
    ClientPublicKey = publicKeyXml 
};
var result = await connector.ExecuteAsync<LoginResult>("Login", loginArgs, PayloadFormat.Encoded);

// 用 RSA 私鑰解密，取得 API 加密金鑰
FrontendInfo.ApiEncryptionKey = Convert.FromBase64String(
    RsaCryptor.DecryptWithPrivateKey(result.ApiEncryptionKey, privateKeyXml));

---

## 🔄 ApiConnector 呼叫流程範例

下表為 `ApiConnector` 呼叫 API 的流程示意，當完成 `Login` 並取得 API 加密金鑰後，後續 API 呼叫即可進行加密：

| API 方法 | 編碼 | 加密 | 說明 |
|-----------------|------|------|------|
| **Ping** | ❌ | ❌ | 僅檢查服務存活，不帶機敏資料 |
| **GetCommonConfiguration** | ❌ | ❌ | 取得系統共用參數，不含使用者資料 |
| **Login** | ✔️ | ❌ | 登入並取得 API 加密金鑰 |
| **Hello** | ✔️ | ✔️ | 登入後完整使用編碼與 AES + HMAC 加密 |

---

## 🎯 結語：多層次 API 防護架構

1. **HTTPS (TLS)** → 保護整個傳輸通道，防止攔截
2. **RSA Key Wrapping** → 確保靜態 AES 金鑰安全下發
3. **AES + HMAC** → 確保 API 資料完整且防竄改

> **HTTPS = 通道加密**：防止竊聽，但無法防止伺服器或節點遭入侵
> **API 加密 = 資料加密**：即使通道失守，資料依舊安全無法竄改

此多層次防護架構，特別適合 ERP / HRM / CRM 等企業級系統，能有效降低單一防線失守帶來的資安風險。

> 💡 延伸說明：本文所採用的金鑰分發屬於 **Key Wrapping**，
> 若要實作動態 Session Key，則屬於 **Key Exchange**，安全性更高但實作複雜度也會提升。

---
**📢 歡迎轉載，請註明出處**
**📬 歡迎追蹤我的技術筆記與實戰經驗分享**
[Facebook](https://www.facebook.com/profile.php?id=61574839666569) ｜ [HackMD](https://hackmd.io/@jeff377) ｜ [GitHub](https://github.com/jeff377) ｜ [NuGet](https://www.nuget.org/profiles/jeff377)