1. 為什麼需要 API Key Certificate?
在 PAN-OS 11.1 及更早版本中，API Key 預設僅使用設備的主金鑰 (Master Key) 進行加密（稱為 Legacy API Key）。
PAN-OS 11.1 引入了一項新功能，允許使用 API Key Certificate 來加密 API Key，這提供了更強的安全性。
1.1. 為什麼 Master Key 比較不安全？
您可能會問：「Master Key 也是我產生的，API Certificate 也是我產生的，為什麼換個金鑰加密就比較安全？」這主要有三個原因：
-
爆炸半徑 (Scope)： Master Key 是防火牆的「萬能金鑰」，負責加密密碼、VPN 私鑰與設定檔中的機密資料。一旦 Master Key 外洩，攻擊者就有可能解密這些資料，風險範圍非常大。現在透過專屬的 Certificate 來獨立加密 API Key，即使這張 Certificate 的 Private Key 被外洩，也只會影響 API 存取，不會危及其他系統密碼。這就是資安上的「風險隔離」。
-
可預測性 (Predictability)： 在 PAN‑OS 8.1 及更早版本中，API Key 是基於「帳號＋密碼＋Master Key」生成的，如果多台防火牆使用相同的帳號密碼與 Master Key，產生的 API Key 會完全相同。從 PAN‑OS 9.0 開始，API Key 的生成機制已經改變，不再依賴 Master Key，因此這個風險已經大幅降低。
-
更換難度 (Lifecycle)： Master Key 的更換涉及 HA 同步暫停、重啟等高風險操作，因此多數單位在設定後很少更換，容易形成長期存在的「萬年金鑰」，增加安全風險。相對的，API Certificate 與 Key 的有效期可以輕鬆設定與輪替。
WARNING重要變更預告：
- PAN-OS 11.1：若未設定 API Key Certificate，系統會跳出警告訊息，但 Legacy API Key 仍可使用。
- PAN-OS 12.0/12.1：Legacy API Key 將被棄用 (Deprecated)。
- PAN-OS 13.0：Legacy API Key 將被完全禁用，必須使用憑證加密的 API Key。
如果您的防火牆或 Panorama 正在使用自動化腳本 (如 Terraform, Ansible, Python SDK) 進行管理，建議儘早轉換為 Certificate-based API Key，以避免未來升級時服務中斷。
2. 生成 API Key Certificate
首先，我們需要在防火牆上生成一個專門用於加密 API Key 的憑證。
-
登入防火牆 Web 介面。
-
前往 Device > Certificate Management > Certificates。
-
點擊 Generate。
-
在生成憑證的視窗中，設定以下參數：
- Certificate Name: 自訂名稱，例如
API-Key-Cert。 - Common Name: 可以任意輸入（此憑證不會提供給 Client 驗證，僅用於加密 API Key）。
- Certificate Authority: 必須勾選（必須是自簽署 CA 憑證）。
- Algorithm: 必須選擇 RSA。
- Number of Bits: 必須大於或等於 3072 bits（低於此數值將無法用於 API Key 加密）。
- Digest: 建議選擇 sha256 或更高。
- Expiration (days): 憑證到期會使 API Key 失效，請依據資安政策設定，例如 365 天。
- Certificate Name: 自訂名稱，例如
- 點擊 Generate 完成生成。
3. 設定 API Key 有效期與憑證
憑證建立後，接下來要設定 API Key 的生命週期並啟用憑證加密。
-
前往 Device > Setup > Management。
-
找到 Authentication Settings 區塊，點擊齒輪圖示進行編輯。
-
在 API Key Certificate 欄位，選擇剛剛建立的
API-Key-Cert。 -
設定 API Key Lifetime (min) (API Key 有效期)。
- 預設可能是無限期 (No Expiration)，建議依據資安政策設定。
- 設定有效期後，API Key 到期前必須重新生成，這能降低 Key 外洩後的長期風險。
WARNING啟用憑證加密的影響： 當您點擊 OK 並 Commit 設定後：
- 防火牆上 現有的所有 API Key 將立即失效。
- 所有自動化腳本必須使用新的流程重新獲取 API Key。
- 若防火牆由 Panorama 管理，Panorama 的 Key 也會失效，需重新授權。
-
完成設定後，執行 Commit。
4. 獲取新的 API Key
API Key Certificate 設定完成並 Commit 後，獲取 API Key 的方式完全相同，不需要修改任何指令或程式碼邏輯。
唯一的差別在於，防火牆回傳的 <key> 內容，現在是經過 Certificate 加密後的版本。
使用 curl 指令獲取 API Key：
curl -k -X POST 'https://<firewall-ip>/api/?type=keygen&user=<username>&password=<password>'成功回應範例：
<response status="success"> <result> <key>LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXBMOG00SDKJ......</key> </result></response>TIP這個
<key>字串雖然看起來跟以前差不多，但它現在是使用您指定的 3072-bit RSA 憑證進行加密的。請將此新 Key 更新到您的自動化工具或腳本中即可。
5. 對 API 用戶端 (Client) 的影響
這是開發人員最關心的部分：切換到 Certificate-based 加密後，我的 Python/Ansible 程式碼需要改寫嗎？
5.1. 呼叫方式不變 (No Code Logic Change)
不需要修改程式碼的連線邏輯，獲取 Key 的 API (type=keygen) 請求方式也完全相同。
即使用了 Certificate 加密，您仍然是：
- 發送相同的 POST 請求 (
type=keygen,user,password) 來獲取 Key。 - 將獲取得的新 Key 放在 HTTP Header (
X-PAN-KEY) 或 URL 參數 (key=...) 中傳送。 Client 端不需要在連線時出示這張憑證（除非您另外設定了 Client Certificate Authentication，那是另一回事）。
5.2. API Key 字串必須更新 (Value Change)
唯一的改變是 Key 的內容字串 (Value)。 因為加密金鑰變了（從 Master Key 變成了 Certificate），舊的 Key 字串在防火牆上已無法解密，視為無效。 您必須：
- 使用新設定重新呼叫
type=keygen。 - 取得新生成的 Key 字串。
- 更新所有自動化腳本、Terraform tfvars 或 .env 檔案中的 Key 值。
5.3. 一次性斷線風險
在您於防火牆上 Commit “API Key Certificate” 設定的那一瞬間，所有舊的 API Key 會立即失效。 請務必安排在維護視窗 (Maintenance Window) 執行此變更，並在變更後立即更新應用程式的 Key。
6. 驗證與排錯
6.1. 如何檢查 API Key 是否有過期?
您可以透過 CLI 指令檢查 API Key 的狀態與到期時間：
show api-key-expiration-ts若回傳空值，代表目前沒有活躍的 API Key。
6.2. 常見問題
6.2.1. API Key 何時會失效？
PAN-OS 會在以下情況自動使 API Key 失效：
| 情況 | 說明 |
|---|---|
| 使用者帳號被刪除 | 產生該 Key 的管理員帳號從系統中移除 |
| 使用者密碼變更 | 產生該 Key 的管理員密碼被修改（即使是本人修改） |
| Key Lifetime 到期 | 超過您在 Authentication Settings 中設定的有效天數 |
| API Key Certificate 被重新設定 | 管理員在設定中選擇了不同的憑證或修改了憑證設定 |
| API Key Certificate 過期 | 用於加密的憑證本身已過期（檢查憑證的 Expiration） |
| PAN-OS 無法解密 API Key | 可能是憑證損壞、遺失或被替換導致無法還原 Key |
TIP若您的自動化腳本突然無法連線，請依上表逐一檢查。最常見的原因是「密碼變更」與「憑證過期」。
透過以上步驟，您的 Palo Alto 防火牆 API 存取將更加安全，並符合未來的 PAN-OS 版本要求。