你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 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 或更高版本。 有关更多详细信息，请参阅 Azure SDK for Python 版本支持策略。

入门

安装包

使用 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-identity 文档。

创建客户端

将 DefaultAzureCredential 的环境配置为使用适当的身份验证方法后，可以执行以下操作来创建密钥客户端 (将 的值 VAULT_URL 替换为保管库的 URL) ：

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

注意： 对于异步客户端，请改为导入 azure.keyvault.keys.aio的 KeyClient 。

关键概念

键

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-core 文档 。

当不再需要异步客户端和凭据时，应将其关闭。 这些对象是异步上下文管理器并定义异步 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-core 中定义的异常。 例如，如果尝试获取保管库中不存在的密钥， 则 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 上启用详细的调试级别日志记录，包括请求/响应正文和未处理标头：

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 (异步版本) |创建/获取/更新/删除密钥 | |list_operations.py (异步版本) |密钥的基本列表操作 | |backup_restore_operations.py (异步版本) |备份和恢复密钥 | |recover_purge_operations.py (异步版本) |恢复和清除密钥 | |send_request.py |使用send_request客户端方法 |

其他文档

有关 Azure 密钥保管库的更多文档，请参阅 API 参考文档。

贡献

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 https://cla.microsoft.com 。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答；若有其他任何问题或意见，请联系 opencode@microsoft.com。