適用于 Python 的 Azure 金鑰保存庫 金鑰用戶端程式庫 - 4.8.0 版

Azure Key Vault 可協助您解決下列問題：

• 密碼編譯金鑰管理 (此程式庫) - 建立、儲存和控制用來加密資料的金鑰存取
• 秘密管理 (azure-keyvault-secrets) - 安全地儲存和控制權杖、密碼、憑證、API 金鑰和其他秘密的存取
• 憑證管理 (azure-keyvault-certificates) - 建立、管理及部署公用和私人 SSL/TLS 憑證
• 保存庫管理 (azure-keyvault-administration) - 角色型存取控制 (RBAC) ，以及保存庫層級的備份和還原選項

| 原始程式碼套件 (PyPI) | 套件 (Conda) | API 參考檔 | 產品檔 | 樣品

免責聲明

Python 2.7 的 Azure SDK Python 套件支援已于 2022 年 1 月 1 日結束。 如需詳細資訊和問題，請參閱 https://github.com/Azure/azure-sdk-for-python/issues/20691 。

需要 Python 3.7 或更新版本才能使用此套件。 如需詳細資訊，請參閱 適用于 Python 的 Azure SDK 版本支援原則。

開始使用

安裝套件

使用pip安裝azure-keyvault-keys和azure-identity：

pip install azure-keyvault-keys azure-identity

azure-identity 用於 Azure Active Directory 驗證，如下所示。

必要條件

• Azure 訂用帳戶
• Python 3.7 或更新版本
• 現有的Azure 金鑰保存庫。 如果您需要建立一個，您可以依照 本檔中的步驟，使用 Azure CLI。
• 如果使用受控 HSM，則現有的金鑰保存庫受控 HSM。 如果您需要建立受控 HSM，您可以遵循 本檔中的步驟，使用 Azure CLI。

驗證用戶端

若要與 Azure 金鑰保存庫服務互動，您需要KeyClient的實例，以及保存庫 URL和認證物件。 本檔示範如何使用 DefaultAzureCredential，這適用于大部分案例，包括本機開發和生產環境。 建議您在生產環境中使用 受控識別 進行驗證。

如需其他驗證方法及其對應認證類型的詳細資訊，請參閱 azure 身分識別 檔。

建立用戶端

將環境設定為 DefaultAzureCredential 以使用適當的驗證方法之後，您可以執行下列動作來建立金鑰用戶端， (將 的值 VAULT_URL 取代為保存庫的 URL) ：

VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = KeyClient(vault_url=VAULT_URL, credential=credential)

注意： 針對非同步用戶端，請改為匯 azure.keyvault.keys.aioKeyClient 入 。

重要概念

索引鍵

Azure 金鑰保存庫可以建立及儲存 RSA 和橢圓曲線金鑰。 兩者都可以選擇性地受到硬體安全性模組的保護， (HSM) 。 Azure 金鑰保存庫也可以使用它們來執行密碼編譯作業。 如需金鑰和支援的作業和演算法的詳細資訊，請參閱金鑰保存庫檔。

KeyClient 可以在保存庫中建立金鑰、從保存庫取得現有的金鑰、更新金鑰中繼資料和刪除金鑰，如下列 範例 所示。

範例

本節包含涵蓋一般工作的程式碼片段：

• 建立金鑰
• 擷取金鑰
• 更新現有的金鑰
• 刪除金鑰
• 設定自動金鑰輪替
• 列出金鑰
• 執行密碼編譯作業
• 非同步 API
• 以非同步方式建立金鑰
• 以非同步方式列出金鑰

建立金鑰

create_rsa_key 和 create_ec_key 分別在保存庫中建立 RSA 和橢圓曲線金鑰。 如果具有相同名稱的索引鍵已經存在，就會建立該金鑰的新版本。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Create an RSA key
rsa_key = key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)

# Create an elliptic curve key
ec_key = key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)

擷取金鑰

get_key 擷取先前儲存在保存庫中的金鑰。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
key = key_client.get_key("key-name")
print(key.name)

更新現有的金鑰

update_key_properties更新先前儲存在金鑰保存庫中的金鑰屬性。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# we will now disable the key for further use
updated_key = key_client.update_key_properties("key-name", enabled=False)

print(updated_key.name)
print(updated_key.properties.enabled)

刪除金鑰

begin_delete_key要求金鑰保存庫刪除金鑰，傳回輪詢器，讓您等候刪除完成。 當保存庫已啟用 虛刪除 時，等候會很有説明，而且您想要儘快清除 (永久刪除) 金鑰。 停用 虛刪除 時， begin_delete_key 本身是永久的。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_key = key_client.begin_delete_key("key-name").result()

print(deleted_key.name)
print(deleted_key.deleted_date)

設定自動金鑰輪替

update_key_rotation_policy 可讓您藉由指定輪替原則來設定金鑰的自動金鑰輪替。 此外， rotate_key 可讓您藉由建立新版的指定金鑰來隨選輪替金鑰。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient, KeyRotationLifetimeAction, KeyRotationPolicyAction

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Set the key's automated rotation policy to rotate the key 30 days before the key expires
actions = [KeyRotationLifetimeAction(KeyRotationPolicyAction.ROTATE, time_before_expiry="P30D")]
# You may also specify the duration after which the newly rotated key will expire
# In this example, any new key versions will expire after 90 days
updated_policy = key_client.update_key_rotation_policy("key-name", expires_in="P90D", lifetime_actions=actions)

# You can get the current rotation policy for a key with get_key_rotation_policy
current_policy = key_client.get_key_rotation_policy("key-name")

# Finally, you can rotate a key on-demand by creating a new version of the key
rotated_key = key_client.rotate_key("key-name")

列出金鑰

list_properties_of_keys 列出用戶端保存庫中所有金鑰的屬性。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()

for key in keys:
    # the list doesn't include values or versions of the keys
    print(key.name)

密碼編譯作業

CryptographyClient 可讓密碼編譯作業 (加密/解密、包裝/解除包裝、簽署/驗證) 使用特定金鑰。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.keyvault.keys.crypto import CryptographyClient, EncryptionAlgorithm

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

key = key_client.get_key("key-name")
crypto_client = CryptographyClient(key, credential=credential)
plaintext = b"plaintext"

result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep, plaintext)
decrypted = crypto_client.decrypt(result.algorithm, result.ciphertext)

如需密碼編譯 API 的詳細資訊，請參閱 套件檔 。

非同步 API

此程式庫包含一組完整的非同步 API。 若要使用它們，您必須先安裝非同步傳輸，例如 aioHTTP。 如需詳細資訊 ，請參閱 azure 核心檔 。

不再需要非同步用戶端和認證時，應該關閉它們。 這些物件是非同步內容管理員，並定義非同步 close 方法。 例如：

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
...
await client.close()
await credential.close()

# alternatively, use them as async context managers (contextlib.AsyncExitStack can help)
client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

以非同步方式建立金鑰

create_rsa_key 和 create_ec_key 分別在保存庫中建立 RSA 和橢圓曲線金鑰。 如果具有相同名稱的金鑰已經存在，則會建立新版本的金鑰。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Create an RSA key
rsa_key = await key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)

# Create an elliptic curve key
ec_key = await key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)

以非同步方式列出金鑰

list_properties_of_keys 列出用戶端保存庫中所有金鑰的屬性。

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()

async for key in keys:
    print(key.name)

疑難排解

azure-keyvault-keys如需如何診斷各種失敗案例的詳細資訊，請參閱疑難排解指南。

一般

金鑰保存庫用戶端會引發azure 核心中定義的例外狀況。 例如，如果您嘗試取得保存庫中不存在的金鑰， KeyClient 會引發 ResourceNotFoundError：

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

try:
    key_client.get_key("which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

記錄

此程式庫會使用標準 記錄 程式庫進行記錄。 HTTP 會話的基本資訊 (URL、標頭等) 會記錄在 INFO 層級。

您可以在具有 引數的用戶端 logging_enable 上啟用詳細的 DEBUG 層級記錄，包括要求/回應主體和未處理的標頭：

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
import sys
import logging

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

credential = DefaultAzureCredential()

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential, logging_enable=True)

同樣地，logging_enable 可對單一作業啟用詳細記錄，即使未對用戶端啟用也可行：

client.get_key("my-key", logging_enable=True)

後續步驟

Azure SDK for Python GitHub 存放庫中提供數個範例。 這些提供其他金鑰保存庫案例的範例程式碼： |檔案 |描述 | |-------------|-------------| |hello_world.py (非同步版本) |create/get/update/delete keys |list_operations.py (非同步版本) |金鑰的基本欄表作業 | |backup_restore_operations.py (非同步版本) |備份和復原金鑰 | |recover_purge_operations.py (非同步版本) |復原和清除金鑰 | |send_request.py |send_request使用用戶端方法 |

其他文件

如需 Azure 金鑰保存庫的詳細資訊檔，請參閱API 參考檔。

參與

此專案歡迎參與和提供建議。 大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。 如需詳細資料，請前往 https://cla.microsoft.com 。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。 請遵循 bot 提供的指示。 您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用了 Microsoft 開放原始碼管理辦法。 如需詳細資訊，請參閱管理辦法常見問題集，如有其他問題或意見，請連絡 opencode@microsoft.com。