Azure Key Vault Keys客户端库，用于Python

Azure Key Vault有助于解决以下问题

• 加密密钥管理（本库）- 创建、存储和管理用于加密数据的密钥的访问权限
• 密钥管理（azure-keyvault-secrets）- 安全存储和管理访问令牌、密码、证书、API密钥和其他机密
• 证书管理（azure-keyvault-certificates）- 创建、管理和部署公钥和私钥SSL/TLS证书
• 保险库管理（azure-keyvault-administration）- 基于角色的访问控制（RBAC），以及保险库级别的备份和还原选项

源代码 | 包（PyPI） | 包（Conda） | API 参考文档 | 产品文档 | 示例

免责声明

Azure SDK Python 包对 Python 2.7 的支持已于 2022 年 1 月 1 日结束。有关更多信息及疑问，请参阅 https://github.com/Azure/azure-sdk-for-python/issues/20691.

使用此包需要 Python 3.8 或更高版本。有关更多详细信息，请参阅 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.8 或更高版本
• 现有的 Azure Key Vault。如果您需要创建一个，可以通过 Azure CLI 按照以下文档中的步骤进行：[此文档](https://docs.microsoft.com/azure/key-vault/general/quick-create-cli)。
• 如果您使用的是托管 HSM，则现有 Key Vault Managed HSM。如果您需要创建一个托管 HSM，可以通过 Azure CLI 按照以下文档中的步骤进行：[此文档](https://docs.microsoft.com/azure/key-vault/managed-hsm/quick-create-cli)。

认证客户端

为了与 Azure Key Vault 服务交互，您需要一个 KeyClient 实例、一个 密钥库 URL 和一个凭证对象。本文档演示了使用 DefaultAzureCredential，它适用于大多数场景。我们建议在生产环境中使用 托管标识 进行认证。

有关其他认证方法和相应凭证类型的更多信息，请参阅 azure-identity 文档。

创建客户端

配置好环境以使用 DefaultAzureCredential 并选择合适的认证方法后，您可以执行以下操作来创建密钥客户端（将 VAULT_URL 的值替换为您的密钥库 URL）

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

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

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

关键概念

密钥

Azure Key Vault 可以创建和存储 RSA 和椭圆曲线密钥。两者都可以选择由硬件安全模块（HSM）保护。Azure Key Vault 还可以与他们执行加密操作。有关密钥和受支持的运算和算法的更多信息，请参阅 [密钥库文档](https://docs.microsoft.com/azure/key-vault/keys/about-keys)。

KeyClient 可以在密钥库中创建密钥、从密钥库获取现有密钥、更新密钥元数据以及删除密钥，如下面的 [示例](#examples) 所示。

示例

本节包含常见任务的代码片段

• 创建密钥
• 检索密钥
• 更新现有密钥
• 删除密钥
• 配置自动密钥轮换
• 列出密钥
• 执行加密操作
• 异步 API
• 异步创建密钥
• 异步列出密钥

创建密钥

可以使用 create_key 方法由 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 可以通过指定旋转策略由 KeyClient 配置密钥的自动旋转。

from azure.keyvault.keys import KeyRotationLifetimeAction, KeyRotationPolicy, KeyRotationPolicyAction

# Here we set the key's automated rotation policy to rotate the key two months after the key was created.
# If you pass an empty KeyRotationPolicy() as the `policy` parameter, the rotation policy will be set to the
# default policy. Any keyword arguments will update specified properties of the policy.
actions = [KeyRotationLifetimeAction(KeyRotationPolicyAction.rotate, time_after_create="P2M")]
updated_policy = client.update_key_rotation_policy(
    "rotation-sample-key", policy=KeyRotationPolicy(), expires_in="P90D", lifetime_actions=actions
)
assert updated_policy.expires_in == "P90D"

此外，rotate_key 允许您通过创建给定密钥的新版本来按需旋转密钥。

rotated_key = client.rotate_key("rotation-sample-key")
print(f"Rotated the key on-demand; new version is {rotated_key.properties.version}")

列出密钥

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)

日志记录

此库使用标准的 logging 库进行日志记录。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 仓库中有几个示例。这些示例提供了其他 Key Vault 场景的示例代码。

• 创建/获取/更新/删除密钥 (异步版本)
• 密钥的基本列表操作 (异步版本)
• 备份和恢复密钥 (异步版本)
• 恢复和清除密钥 (异步版本)
• 创建/更新密钥轮换策略和按需轮换密钥 (异步版本)
• 使用 send_request 客户端方法

其他文档

有关 Azure Key Vault 的更多详细文档，请参阅 API 参考文档。

贡献

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

当您提交拉取请求时，CLA-bot 将自动确定您是否需要提供 CLA，并相应地装饰 PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您在整个使用我们 CLA 的所有存储库中只需这样做一次。

本项目已采用 Microsoft 开源行为准则。有关更多信息，请参阅 行为准则常见问题解答 或联系 opencode@microsoft.com 了解任何其他问题或意见。

发行历史

4.9.0 (2024-02-22)

新增功能

• 添加了对服务 API 版本 7.5 的支持
• (从 4.9.0b2) 现在由 KeyVaultRSAPrivateKey 和 KeyVaultRSAPublicKey 类实现 cryptography 库的 RSAPrivateKey 和 RSAPublicKey 接口，这些类可以使用 Key Vault 管理的密钥
• (从 4.9.0b2) CryptographyClient 有 create_rsa_private_key 和 create_rsa_public_key 方法，分别返回 KeyVaultRSAPrivateKey 和 KeyVaultRSAPublicKey
• (从 4.9.0b3) 添加了 KeyProperties.hsm_platform 以获取底层 HSM 平台

错误修复

• (从 4.9.0b1) 在 AD FS 认证期间发出的令牌请求不再指定错误的 "adfs" 租户 ID (#29888)

其他更改

• 不再支持 Python 3.7。请使用 Python 版本 3.8 或更高版本。
• asyncio 不再直接由库引用 (#33819)
• 将最小 azure-core 版本更新到 1.29.5
• 删除了对 azure-common 的要求

4.9.0b3 (2023-11-03)

新增功能

• 添加了对服务 API 版本 7.5-preview.1 的支持
• 添加了 KeyProperties.hsm_platform 以获取底层 HSM 平台

其他更改

• Key Vault API 版本 7.5-preview.1 现在是默认版本

4.9.0b2 (2023-10-12)

新增功能

• cryptography 库的 RSAPrivateKey 和 RSAPublicKey 接口现在由 KeyVaultRSAPrivateKey 和 KeyVaultRSAPublicKey 类实现，这些类可以使用 Key Vault 管理的密钥
• CryptographyClient 包含 create_rsa_private_key 和 create_rsa_public_key 方法，分别返回 KeyVaultRSAPrivateKey 和 KeyVaultRSAPublicKey 对象。

4.9.0b1 (2023-05-16)

错误修复

• 在 AD FS 身份验证过程中发出的令牌请求不再指定错误的 "adfs" 租户 ID（《https://github.com/Azure/azure-sdk-for-python/issues/29888》#29888）

4.8.0 (2023-03-16)

新增功能

• 增加了对服务 API 版本 7.4 的支持
• 每个客户端都有一个 send_request 方法，可以用来发送使用客户端现有管道的自定义请求（《https://github.com/Azure/azure-sdk-for-python/issues/25172》#25172）
• （自 4.8.0b1 版起）如果未提供 IV，将尝试生成本地加密所需的 IV（《https://github.com/Azure/azure-sdk-for-python/pull/25380》#25380）

重大变更

这些更改不会影响稳定版本（如 4.7.0）的 API。只有针对 beta 版本（如 4.8.0b2）编写的代码可能会受到影响。

• 移除了对八位字节密钥对（OKP）键和操作的支持

其他更改

• 密钥保管库 API 版本 7.4 现在是默认版本
• （自 4.8.0b1 版起）不再支持 Python 3.6。请使用 Python 3.7 或更高版本。
• （自 4.8.0b1 版起）将 azure-core 的最低版本更新到 1.24.0
• （自 4.8.0b1 版起）将 msrest 的最低版本更新到 0.7.1
• （自 4.8.0b2 版起）删除了对 msrest 的依赖
• （自 4.8.0b2 版起）删除了对 six 的依赖
• （自 4.8.0b2 版起）添加了对 isodate>=0.6.1 的依赖（isodate 由 msrest 需要）
• （自 4.8.0b2 版起）添加了对 typing-extensions>=4.0.1 的依赖

4.8.0b2 (2022-11-15)

新增功能

• 增加了对服务 API 版本 7.4-preview.1 的支持
• KeyClient 有一个 create_okp_key 方法，可以在托管 HSM 上创建八位字节密钥对（OKP）
• 向 SignatureAlgorithm 枚举中添加了 eddsa，以支持在托管 HSM 上使用 Edwards 曲线数字签名算法（EdDSA）进行签名和验证
• 向 KeyType 枚举中添加了 okp 和 okp_hsm 以支持八位字节密钥对
• 向 KeyCurveName 枚举中添加了 ed25519 以支持使用 Ed25519 Edwards 曲线

其他更改

• 密钥保管库 API 版本 7.4-preview.1 现在是默认版本
• 删除了对 msrest 的依赖
• 删除了对 six 的依赖
• 添加了对 isodate>=0.6.1 的依赖（isodate 由 msrest 需要）
• 添加了对 typing-extensions>=4.0.1 的依赖

4.8.0b1 (2022-09-22)

新增功能

• 如果未提供 IV，将尝试生成本地加密所需的 IV（《https://github.com/Azure/azure-sdk-for-python/pull/25380》#25380）

其他更改

• 不再支持 Python 3.6。请使用 Python 3.7 或更高版本。
• 将 azure-core 的最低版本更新到 1.24.0
• 将 msrest 的最低版本更新到 0.7.1

4.7.0 (2022-09-19)

重大变更

• 客户端会验证挑战资源与保管库域匹配。这应该会影响很少数客户，这些客户可以在客户端构造函数中提供 verify_challenge_resource=False 以禁用此功能。更多信息请参阅《https://aka.ms/azsdk/blog/vault-uri》

其他更改

• 已撤销自 4.7.0b1 版本以来的更改，并将包含在 4.8.0b1 版本中

4.7.0b1 (2022-08-12)

新增功能

• 如果未提供 IV，将尝试生成本地加密所需的 IV（《https://github.com/Azure/azure-sdk-for-python/pull/25380》#25380）

其他更改

• 最新发布的版本是 4.6.1，而不是预期的版本 4.5.2。下一个稳定版本计划为 4.7.0。
• 不再支持 Python 3.6。请使用 Python 3.7 或更高版本。
• 将 azure-core 的最低版本更新到 1.24.0

4.6.1 (2022-08-11)

其他更改

• 文档改进（《https://github.com/Azure/azure-sdk-for-python/issues/25039》#25039）

4.6.0b1 (2022-06-07)

错误修复

• 如果一个密钥的 ID 包含端口号，现在这个端口号将被保存在从该密钥创建的 CryptographyClient 实例的保管库 URL 中（《https://github.com/Azure/azure-sdk-for-python/issues/24446》#24446）
  • 现在在 KeyVaultKeyIdentifier 的 vault_url 属性中保存端口号

4.5.1 (2022-04-18)

错误修复

• 修复了在检索没有定义 lifetime_actions 的密钥轮换策略时可能出现的错误。

4.5.0 (2022-03-28)

新增功能

• 密钥保管库 API 版本 7.3 现在是默认版本
• 当使用1.8.0或更高版本的azure-identity时，增加了对多租户身份验证的支持（#20698）
• （从4.5.0b1开始）KeyClient提供了一个get_random_bytes方法，可以从托管HSM中获取请求数量的随机字节
• （从4.5.0b2开始）增加了从托管HSM安全释放密钥的支持（#19588）
  • 向KeyClient添加了release_key方法以释放密钥的私用部分
  • 在密钥创建和导入方法中添加了仅关键字参数exportable和release_policy
  • 添加了KeyExportEncryptionAlgorithm枚举，用于指定密钥释放中使用的加密算法
• （从4.5.0b4开始）添加了KeyClient.get_cryptography_client，它提供了一个简单的方式来创建具有其名称和可选版本的CryptographyClient（#20621）
• （从4.5.0b4开始）增加了在Azure Key Vault中进行自动和按需密钥轮换的支持（#19840）
  • 添加了KeyClient.rotate_key以按需轮换密钥
  • 添加了KeyClient.update_key_rotation_policy以更新密钥的自动轮换策略
• （从4.5.0b6开始）向KeyReleasePolicy添加了仅关键字参数和属性immutable，以支持不可变释放策略。一旦释放策略被标记为不可变，就无法再修改。

重大变更

这些更改不会影响如4.4.0等稳定版本的API。只有针对如4.5.0b1等测试版本的代码可能会受到影响。

• KeyClient.update_key_rotation_policy接受一个必需的policy参数（#22981）
• KeyClient.release_key中的可选version参数现在是一个仅关键字参数（#22981）
• 将KeyClient.get_key_rotation_policy和KeyClient.update_key_rotation_policy中的name参数重命名为key_name（#22981）
• 在azure-keyvault-keys中的枚举值现在是统一的小写（#22981）

错误修复

• KeyType现在在声明时忽略大小写，这解决了使用非标准大小写创建的密钥无法通过SDK检索的场景（#22797）

其他更改

• （从4.5.0b6开始）不再支持Python 2.7。请使用Python 3.6或更高版本。
• （从4.5.0b6开始）已更新最小azure-core版本到1.20.0
• （从4.5.0b3开始）更新了类型提示以修复mypy错误（#19158）
• （从4.5.0b4开始）CryptographyClient在向其构造函数提供密钥ID时不再需要密钥版本（尽管提供版本仍然建议）
• （从4.5.0b5开始）为了支持多租户身份验证，在挑战身份验证请求期间，get_token调用现在传递一个tenant_id关键字参数（#20698）。有关如何在自定义凭据实现get_token时集成此参数的更多详细信息，请参阅https://aka.ms/azsdk/python/identity/tokencredential。
• （从4.5.0b6开始）更新了KeyProperties模型中managed、exportable和release_policy属性的类型提示（#22368）

4.5.0b6（2022-02-08）

新增功能

• 向KeyReleasePolicy添加了仅关键字参数和属性immutable，以支持不可变释放策略。一旦释放策略被标记为不可变，就无法再修改。

重大变更

这些更改不会影响如4.4.0等稳定版本的API。只有针对如4.5.0b1等测试版本的代码可能会受到影响。

• 将KeyReleasePolicy构造函数中必需的参数data重命名为encoded_policy

其他更改

• 不再支持Python 2.7。请使用Python 3.6或更高版本。
• 已更新最低 azure-core 版本到 1.20.0
• 更新了 KeyProperties 模型的 managed、exportable 和 release_policy 属性的类型提示（#22368）
• （从 4.5.0b5）为了支持多租户身份验证，在挑战身份验证请求期间的 get_token 调用现在传递一个 tenant_id 关键字参数（#20698）

4.5.0b5（2021-11-11）

新增功能

• 当使用 azure-identity 1.7.1 或更高版本时，添加了对多租户身份验证的支持（#20698）

重大变更

这些更改不会影响如4.4.0等稳定版本的API。只有针对如4.5.0b1等测试版本的代码可能会受到影响。

• KeyClient.get_random_bytes 现在返回字节数组而不是 RandomBytes。已移除 RandomBytes 类
• 将 KeyClient.get_cryptography_client 中的 version 关键字参数重命名为 key_version
• 将 KeyReleasePolicy.data 重命名为 KeyReleasePolicy.encoded_policy
• 将 KeyClient.release_key 中的 target 参数重命名为 target_attestation_token

其他更改

• 已更新最低 azure-core 版本到 1.15.0

4.5.0b4（2021-10-07）

新增功能

• 添加了 KeyClient.get_cryptography_client，该功能提供了一种简单的方法来创建一个指定名称和可选版本的 CryptographyClient（#20621）
• 在 Azure Key Vault 中添加了对自动化和按需密钥轮换的支持（#19840）
  • 添加了KeyClient.rotate_key以按需轮换密钥
  • 添加了KeyClient.update_key_rotation_policy以更新密钥的自动轮换策略

其他更改

• CryptographyClient 在向其构造函数提供密钥 ID 时不再需要密钥版本（尽管提供版本仍然推荐）

4.5.0b3（2021-09-09）

其他更改

• 更新类型提示以修复 mypy 错误（#19158）

4.5.0b2（2021-08-10）

新增功能

• 添加了对从托管 HSM 安全发布密钥的支持（#19588）
  • 向KeyClient添加了release_key方法以释放密钥的私用部分
  • 在密钥创建和导入方法中添加了仅关键字参数exportable和release_policy
  • 添加了KeyExportEncryptionAlgorithm枚举，用于指定密钥释放中使用的加密算法

重大变更

这些更改不会影响如4.4.0等稳定版本的API。只有针对如4.5.0b1等测试版本的代码可能会受到影响。

• KeyClient.get_random_bytes 现在返回一个包含字节数组的 RandomBytes 模型，而不是直接返回字节数组（#19895）

4.5.0b1（2021-07-08）

从本版本开始，此库需要 Python 2.7 或 3.6+。

新增功能

• 密钥保管库 API 版本 7.3-preview 现为默认版本
• KeyClient 具有一个 get_random_bytes 方法，可以从托管 HSM 获取请求数量的随机字节

4.4.0 (2021-06-22)

这是最后一个支持 Python 3.5 的版本。下一个版本将需要 Python 2.7 或 3.6+。

更改

• 密钥保管库 API 版本 7.2 现为默认版本
• （从 4.4.0b1）已更新最低 msrest 版本到 0.6.21

添加

• KeyClient 具有一个 create_oct_key 方法用于创建对称密钥
• KeyClient 的 create_key 和 create_rsa_key 方法现在接受一个 public_exponent 关键字参数（#18016）
• （从 4.4.0b1）添加了对密钥保管库 API 版本 7.2 的支持（#16566）
  • 将 oct_hsm 添加到 KeyType
  • 将 128 位、192 位和 256 位 AES-GCM、AES-CBC 和 AES-CBCPAD 加密算法添加到 EncryptionAlgorithm
  • 将 128 位和 192 位 AES-KW 密钥包装算法添加到 KeyWrapAlgorithm
  • CryptographyClient 的 encrypt 方法接受 iv 和 additional_authenticated_data 关键字参数
  • CryptographyClient 的 decrypt 方法接受 iv、additional_authenticated_data 和 authentication_tag 关键字参数
  • 将 iv、aad 和 tag 属性添加到 EncryptResult
• （从 4.4.0b3）如果使用 .from_jwk 工厂方法初始化，则 CryptographyClient 将在本地执行所有操作（#16565）
• （从 4.4.0b3）添加了对 six>=1.12.0 的要求
• (从4.4.0b4开始) CryptographyClient 可在本地执行 AES-CBCPAD 加密和解密操作 (#17762)

重大变更

这些更改不会影响如4.3.1之类的稳定版本API。只有针对4.4.0b1之类的beta版本编写的代码可能会受到影响。

• parse_key_vault_key_id 和 KeyVaultResourceId 已被 KeyVaultKeyIdentifier 类取代，它可以使用密钥ID进行初始化。

4.4.0b4 (2021-04-06)

添加

• CryptographyClient 可在本地执行 AES-CBCPAD 加密和解密操作 (#17762)

4.4.0b3 (2021-03-11)

添加

• CryptographyClient 如果使用 .from_jwk 工厂方法初始化，将本地执行所有操作 (#16565)
• 增加了对 six>=1.12.0 的依赖要求

4.4.0b2 (2021-02-10)

修复

• API版本低于7.2-preview的版本在执行异步操作时不再抛出 ImportError (#16680)

4.4.0b1 (2021-02-10)

更改

• Key Vault API版本7.2-preview现在是默认版本
• 更新msrest要求为>=0.6.21

添加

• 支持Key Vault API版本7.2-preview (#16566)
  • 将 oct_hsm 添加到 KeyType
  • 将 128 位、192 位和 256 位 AES-GCM、AES-CBC 和 AES-CBCPAD 加密算法添加到 EncryptionAlgorithm
  • 将 128 位和 192 位 AES-KW 密钥包装算法添加到 KeyWrapAlgorithm
  • CryptographyClient 的 encrypt 方法接受 iv 和 additional_authenticated_data 关键字参数
  • CryptographyClient 的 decrypt 方法接受 iv、additional_authenticated_data 和 authentication_tag 关键字参数
  • 将 iv、aad 和 tag 属性添加到 EncryptResult
• 添加了 parse_key_vault_key_id 方法，可以解析出Key Vault返回的完整ID，因此用户可以轻松访问密钥的 name、vault_url 和 version。

4.3.1 (2020-12-03)

修复

• CryptographyClient 操作不再在客户端使用密钥ID构造时抛出 AttributeError (#15608)

4.3.0 (2020-10-06)

更改

• CryptographyClient 可在本地执行解密和签名操作 (#9754)

修复

• 正确地为异步分页方法指定了类型

4.2.0 (2020-08-11)

修复

• 日志输出中不再隐藏 x-ms-keyvault-region 和 x-ms-keyvault-service-version 头部的值
• CryptographyClient 在其密钥已过期或尚未生效时将不再执行加密或包装操作

更改

• Key Vault API版本7.1现在是默认版本
• 将最小 azure-core 版本更新到1.7.0

添加

• 在构造时，客户端通过可选关键字参数 custom_hook_policy 接受 CustomHookPolicy
• 所有客户端请求都包括在头部 x-ms-client-request-id 中的唯一ID
• 依赖 azure-common 以支持多API

4.2.0b1 (2020-03-10)

• 支持Key Vault API版本7.1-preview (#10124)
  • 向 KeyOperation 添加了 import_key
  • 向 CertificateProperties 添加了 recoverable_days
  • 添加了识别此包支持的Key Vault版本的 ApiVersion 枚举

4.1.0 (2020-03-10)

• KeyClient 实例有一个 close 方法，它关闭打开的套接字。用作上下文管理器时，KeyClient 在退出时关闭打开的套接字。(#9906)
• 操作完成后Pollers不再休眠 (#9991)

4.0.1 (2020-02-11)

• azure.keyvault.keys 定义了 __version__
• 挑战认证策略保留请求选项 (#8999)
• 将 msrest 要求更新为>=0.6.0
• 挑战认证策略需要TLS (#9457)
• 方法不再抛出内部错误 KeyVaultErrorException (#9690)
• 修复异步CryptographyClient在远程验证签名时的 AttributeError (#9734)

4.0.0 (2019-10-31)

重大更改

• 删除了 KeyClient.get_cryptography_client() 和 CryptographyClient.get_key()
• 将多个方法的可选参数移动到kwargs中（文档详细说明了新的关键字参数）
  • create_key 现在有两个位置参数 name 和 key_type
  • create_ec_key 和 create_rsa_key 现在有一个位置参数，name
  • update_key_properties 现在有两个位置参数，分别是 name 和（可选的）version
  • import_key 现在有两个位置参数，分别是 name 和 key
• CryptographyClient 操作现在返回类实例而不是元组，并且重命名了以下属性
  • 将 DecryptResult 的 decrypted_bytes 属性重命名为 plaintext
  • 将 UnwrapResult 的 unwrapped_bytes 属性重命名为 key
  • 将 VerifyResult 的 result 属性重命名为 is_valid
• 将 UnwrapKeyResult 和 WrapKeyResult 类重命名为 UnwrapResult 和 WrapResult
• 将 list_keys 重命名为 list_properties_of_keys
• 将 list_key_versions 重命名为 list_properties_of_key_versions
• 将同步方法 delete_key 重命名为 begin_delete_key
• 同步方法 begin_delete_key 和异步 delete_key 现在返回返回 DeletedKey 的轮询器
• 将 Key 重命名为 KeyVaultKey
• KeyVaultKey 的属性 created、expires 和 updated 重命名为 created_on、expires_on 和 updated_on
• KeyClient 的 vault_endpoint 参数已被重命名为 vault_url
• 所有模型中的属性 vault_endpoint 已被重命名为 vault_url

新特性

• 现在所有 CryptographyClient 返回值都包括 key_id 和 algorithm 属性

4.0.0b4 (2019-10-08)

• 将枚举 JsonWebKeyCurveName、JsonWebKeyOperation 和 JsonWebKeyType 分别重命名为 KeyCurveName、KeyOperation 和 KeyType

• Key 现在具有属性 properties，该属性包含键的某些属性，例如 version。这改变了返回的 Key 类型形状，因为 Key 的某些属性（例如 version）必须通过 properties 属性来访问。

• 已将 update_key 重命名为 update_key_properties

• KeyClient 的 vault_url 参数已被重命名为 vault_endpoint

• 所有模型中的属性 vault_url 已被重命名为 vault_endpoint

修复和改进

• import_key 的 key 参数应该是 azure.keyvault.keys.JsonWebKey 的实例（#7590）

4.0.0b3 (2019-09-11)

重大更改

• 将 CryptographyClient 方法 wrap 和 unwrap 分别重命名为 wrap_key 和 unwrap_key

新特性

• 当 CryptographyClient 的密钥的公开材料可用时（即，当它具有 keys/get 权限时），它会在本地执行加密、验证和包装操作。

4.0.0b2 (2019-08-06)

重大更改

• 为了准备重新设计的配置 API，已从公共 API 中删除 azure.core.Configuration。静态 create_config 方法已被重命名为 _create_config，并将在未来版本中删除。
• 从 KeyClient 中删除了 wrap_key 和 unwrap_key。这些现在通过 CryptographyClient 提供。
• 此版本的库需要 azure-core 1.0.0b2
  • 如果您以后想恢复到需要 azure-core 1.0.0b1 的版本（此或另一个 Azure SDK 库），您必须显式安装 azure-core 1.0.0b1。例如：pip install azure-core==1.0.0b1 azure-keyvault-keys==4.0.0b1

新特性

• 添加了 CryptographyClient，这是一个执行与键相关的加密操作（加密/解密、包装/解包装、签名/验证）的客户端。
• 现在支持分布式跟踪框架 OpenCensus
• 添加了对基于 HTTP 挑战的身份验证的支持，允许客户端与主权云中的存储库交互。

其他更改

• 异步客户端默认使用 aiohttp 进行传输。有关使用其他传输的信息，请参阅 azure-core 文档。

4.0.0b1 (2019-06-28)

4.0.0b1版本是我们为创建一个用户友好且符合Python风格的Azure Key Vault客户端库所做的第一个预览版。有关其他Azure SDK库预览版的信息，请访问https://aka.ms/azure-sdk-preview1-python。

此库不是直接替换azure-keyvault的。使用该库的应用程序需要代码更改才能使用azure-keyvault-keys。此包的文档和示例演示了新的API。

与azure-keyvault相比的主要变化

• 按功能划分的包
  • azure-keyvault-keys包含密钥操作的客户端，azure-keyvault-secrets包含秘密操作的客户端
• 客户端实例的范围是保管库（一个实例只与一个保管库交互）
• 支持Python 3.5.3+的异步API
  • azure.keyvault.keys.aio命名空间包含与azure.keyvault.keys中同步客户端相对应的异步客户端
• 使用azure-identity凭据进行身份验证
  • 有关更多信息，请参阅此包的文档和Azure Identity文档

此版本中未实现azure-keyvault的功能

• 证书管理API
• 加密操作，例如签名、解密/加密密钥、验证、加密和解密
• 支持国家云。此版本支持公共全球云保管库，例如 https://{保管库名称}.vault.azure.net