适用于 .NET 的 AWS Encryption SDK - AWS Encryption SDK
安装和构建调试AWS KMS 密钥环必需的加密上下文 CMM

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

适用于 .NET 的 AWS Encryption SDK

适用于 .NET 的 AWS Encryption SDK 属于客户端加密库，适用于使用 C# 和其他 .NET 编程语言编写应用程序的开发人员。它在 Windows、macOS 和 Linux 上受支持。

AWS Encryption SDK 的所有编程语言实施完全可互操作。但如果您在适用于 .NET 的 AWS Encryption SDK 版本 4.x 中使用必需的加密上下文 CMM 加密数据，则只能使用适用于 .NET 的 AWS Encryption SDK 版本 4.x 或 AWS Encryption SDK for Java 的版本 3.x 进行解密。

注意

适用于 .NET 的 AWS Encryption SDK 版本 4.0.0 偏离了 AWS Encryption SDK 消息规范。因此，由版本 4.0.0 加密的消息只能由适用于 .NET 的 AWS Encryption SDK 版本 4.0.0，或更高版本进行解密。任何其他编程语言都无法对其进行解密。

适用于 .NET AWS Encryption SDK 的版本 4.0.1 根据 AWS Encryption SDK 消息规范写入消息，并可与其他编程语言实现互操作。默认情况下，版本 4.0.1 可以读取版本 4.0.0 加密的消息。但如果您不想解密由版本 4.0.0 加密的消息，则可以指定 NetV4_0_0_RetryPolicy 属性来阻止客户端读取这些消息。有关更多信息，请参阅 GitHub 上 aws-encryption-sdk-dafny 存储库中的 v4.0.1 发行说明。

适用于 .NET 的 AWS Encryption SDK 与 AWS Encryption SDK 的其他某些编程语言实施的不同之处在于：

适用于 .NET 的 AWS Encryption SDK 包括 AWS Encryption SDK 其他语言实施版本 2.0.x 以及更高版本中引入的所有安全功能。但是，如果您使用适用于 .NET 的 AWS Encryption SDK 解密由 AWS Encryption SDK 其他语言实施 2.0 x 之前版本加密的数据，您可能需要调整承诺政策。有关详细信息，请参阅 如何设置您的承诺策略。

适用于 .NET 的 AWS Encryption SDK 是 Dafny 中 AWS Encryption SDK 的产物，属于正式的验证语言，您可以用其编写规范、规范实施代码以及规范测试证明。结果为在确保功能正确性的框架中实施 AWS Encryption SDK 功能的库。

了解更多

  • 有关说明如何在 AWS Encryption SDK 中配置选项（例如指定备用算法套件、限制加密数据密钥和使用 AWS KMS 多区域密钥）的示例，请参阅 配置 AWS Encryption SDK。

  • 有关使用适用于 .NET 的 AWS Encryption SDK 进行编程的详细信息，请参阅 GitHub aws-encryption-sdk-dafny 存储库的 aws-encryption-sdk-net 目录。

主题

安装适用于 .NET 的 AWS Encryption SDK

适用于 .NET 的 AWS Encryption SDK 在 NuGet 中作为 AWS.Cryptography.EncryptionSDK 程序包提供。有关安装和构建适用于 .NET 的 AWS Encryption SDK 的详细信息，请参阅 aws-encryption-sdk-net 存储库中的 README.md 文件。

版本 3.x

适用于 .NET 的 AWS Encryption SDK 版本 3.x 在 Windows 中仅支持 .NET Framework 4.5.2-4.8。其在所有支持的操作系统中均支持 .NET Core 3.0+ 和 .NET 5.0 及更高版本。

版本 4.x

适用于 .NET 的 AWS Encryption SDK 版本 4.x 支持 .NET 6.0 和 .NET Framework net48 及更高版本。

即使您未使用 AWS Key Management Service（AWS KMS）密钥，适用于 .NET 的 AWS Encryption SDK 也需要 AWS SDK for .NET。其与 NuGet 程序包一起安装。但是，除非您使用 AWS KMS 密钥，否则适用于 .NET 的 AWS Encryption SDK 不需要 AWS 账户、AWS 凭证或与任何 AWS 服务交互。如需帮助设置 AWS 账户，请参阅 将 AWS Encryption SDK 与 AWS KMS 结合使用。

调试适用于 .NET 的 AWS Encryption SDK

适用于 .NET 的 AWS Encryption SDK 不生成任何日志。适用于 .NET 的 AWS Encryption SDK 异常会生成异常消息，但不会生成堆栈跟踪。

为了帮助您进行调试，请务必在 AWS SDK for .NET 中启用日志记录功能。AWS SDK for .NET 中的日志和错误消息可以帮助您区分 AWS SDK for .NET 中出现的错误和适用于 .NET 的 AWS Encryption SDK 中出现的错误。有关 AWS SDK for .NET 日志记录的帮助，请参阅《AWS SDK for .NET Developer Guide》中的 AWSLogging。（要查看该主题，请展开 Open to view .NET Framework content 部分。）

适用于 .NET 的 AWS Encryption SDK 中的 AWS KMS 密钥环

适用于 .NET 的 AWS Encryption SDK 中的基本 AWS KMS 密钥环只需一个 KMS 密钥。密钥环还需要一个 AWS KMS 客户端，以便您能够为 KMS 密钥的 AWS 区域 配置客户端。

要使用一个或多个包装密钥创建 AWS KMS 密钥环，请使用多重密钥环。适用于 .NET 的 AWS Encryption SDK 有一个特殊多重密钥环，其需要一个或多个 AWS KMS 密钥；还有一个标准多重密钥环，其需要一个或多个任何支持类型的密钥环。某些编程人员更喜欢使用多重密钥环方法创建所有密钥环，而适用于 .NET 的 AWS Encryption SDK 支持该策略。

适用于 .NET 的 AWS Encryption SDK 为所有典型用例（包括 AWS KMS 多区域密钥）提供基本的单密钥环和多重密钥环。

例如，要使用一个 AWS KMS 密钥创建 AWS KMS 密钥环，可以使用 CreateAwsKmsKeyring() 方法。

Version 3.x

以下示例使用适用于 .NET 的 AWS Encryption SDK 版本 3.x 为包含指定密钥的区域创建默认 AWS KMS 客户端。

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};

// Create the keyring
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
Version 4.x

以下示例使用适用于 .NET 的 AWS Encryption SDK 版本 4.x 为包含指定密钥的区域创建 AWS KMS 客户端。

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = kmsArn
};

// Create the keyring
var kmsKeyring = mpl.CreateAwsKmsKeyring(createKeyringInput);

要使用一个或多个 AWS KMS 密钥创建密钥环，请使用 CreateAwsKmsMultiKeyring() 方法。此示例使用两个 AWS KMS 密钥。要指定 KMS 密钥，请仅使用 Generator 参数。指定其他 KMS 密钥的 KmsKeyIds 参数为可选参数。

此密钥环的输入不需要 AWS KMS 客户端。相反，AWS Encryption SDK 使用由密钥环中的 KMS 密钥表示的各区域默认 AWS KMS 客户端。例如，如果由 Generator 参数值标识的 KMS 密钥位于美国西部（俄勒冈州）区域 (us-west-2)，AWS Encryption SDK 则会为 us-west-2 区域创建默认 AWS KMS 客户端。如果需要自定义 AWS KMS 客户端，请使用 CreateAwsKmsKeyring() 方法。

以下示例使用适用于 .NET 的 AWS Encryption SDK 版本 4.x 和 CreateAwsKmsKeyring() 方法自定义 AWS KMS 客户端。

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<string> additionalKeys = new List<string> { "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321" };

// Instantiate the keyring input object
var createEncryptKeyringInput = new CreateAwsKmsMultiKeyringInput
{
    Generator = generatorKey,
    KmsKeyIds = additionalKeys
};

var kmsEncryptKeyring = materialProviders.CreateAwsKmsMultiKeyring(createEncryptKeyringInput);

适用于 .NET 的 AWS Encryption SDK 版本 4.x 支持使用对称加密 (SYMMETRIC_DEFAULT) 或非对称 RSA KMS 密钥的 AWS KMS 密钥环。使用非对称 RSA KMS 密钥创建的 AWS KMS 密钥环只能包含一个密钥对。

要使用非对称 RSA AWS KMS 密钥环进行加密，您不需要 kms:GenerateDataKey 或 kms:Encrypt，因为在创建密钥环时必须指定要用于加密的公有密钥材料。使用此密钥环进行加密时不会调用任何 AWS KMS。要使用非对称 RSA AWS KMS 密钥环进行解密，您需要 kms:Decrypt 权限。

要创建非对称 RSA AWS KMS 密钥环，您必须提供来自非对称 RSA KMS 密钥的公有密钥和私有密钥 ARN。公有密钥必须采用 PEM 编码。以下示例使用非对称 RSA 密钥对创建 AWS KMS 密钥环。

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
        
var publicKey = new MemoryStream(Encoding.UTF8.GetBytes(AWS KMS RSA public key));

// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsRsaKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = AWS KMS RSA private key ARN,
    PublicKey = publicKey,
    EncryptionAlgorithm = EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256
};

// Create the keyring
var kmsRsaKeyring = mpl.CreateAwsKmsRsaKeyring(createKeyringInput);

版本 4.x 中必需的加密上下文

借助适用于 .NET 的 AWS Encryption SDK 版本 4.x，您可以使用必需的加密上下文 CMM 在加密操作中要求提供加密上下文。加密上下文是一组非机密键值对。加密上下文以加密方式绑定到加密的数据，以便需要使用相同的加密上下文解密字段。使用必需的加密上下文 CMM 时，可以指定一个或多个必需的加密上下文密钥（必需的密钥），这些密钥必须包含在所有加密和解密调用中。

注意

所需的加密上下文 CMM 只能与 AWS Encryption SDK for Java 的版本 3.x 互操作。而不能与任何其他编程语言实现互操作。如果您使用所需的加密上下文 CMM 加密数据，则只能使用 AWS Encryption SDK for Java 的版本 3.x，或适用于 .NET 的 AWS Encryption SDK 版本 4.x 进行解密。

加密时，AWS Encryption SDK 验证所有必需的加密上下文密钥是否包含在您指定的加密上下文中。AWS Encryption SDK 对您指定的加密上下文进行签名。只有非所需密钥的键值对才会序列化并以明文格式存储在加密操作返回的加密消息的标头中。

解密时，必须提供包含代表所需密钥的所有键值对的加密上下文。AWS Encryption SDK 使用此加密上下文和存储在加密消息标头中的键值对来重建您在加密操作中指定的原始加密上下文。如果 AWS Encryption SDK 无法重建原始加密上下文，则解密操作失败。如果您提供的键值对包含值不正确的所需密钥，则无法解密加密消息。您提供的键值对必须与加密时指定的相同。

重要

请仔细考虑您在加密上下文中为所需密钥选择的值。您必须能够在解密时再次提供相同密钥及其对应值。如果您无法重现所需密钥，则无法解密加密消息。

以下示例使用必需的加密上下文 CMM 初始化 AWS KMS 密钥环。

var encryptionContext = new Dictionary<string, string>()
{
    {"encryption", "context"},
    {"is not", "secret"},
    {"but adds", "useful metadata"},
    {"that can help you", "be confident that"},
    {"the data you are handling", "is what you think it is"}
};

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
        
// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = kmsKey
};
 
// Create the keyring 
var kmsKeyring = mpl.CreateAwsKmsKeyring(createKeyringInput);
        
var createCMMInput = new CreateRequiredEncryptionContextCMMInput
{
    UnderlyingCMM = mpl.CreateDefaultCryptographicMaterialsManager(new CreateDefaultCryptographicMaterialsManagerInput{Keyring = kmsKeyring}),
    // If you pass in a keyring but no underlying cmm, it will result in a failure because only cmm is supported.
    RequiredEncryptionContextKeys = new List<string>(encryptionContext.Keys)
};
 
// Create the required encryption context CMM
var requiredEcCMM = mpl.CreateRequiredEncryptionContextCMM(createCMMInput);

如果您使用 AWS KMS 密钥环，适用于 .NET 的 AWS Encryption SDK 还会使用加密上下文在密钥环调用 AWS KMS 时提供额外验证数据。