你当前正在访问 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 可以在保管库中创建密钥、从保管库获取现有密钥、更新密钥元数据和删除密钥， 如以下示例所示 。
示例
本部分包含涵盖常见任务的代码片段：
创建密钥
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。
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈