AWS Encryption SDK 对于。 NET - AWS Encryption SDK
安装和构建调试AWS KMS 钥匙圈所需的加密上下文 CMM

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

AWS Encryption SDK 对于。 NET

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

注意

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

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

那个 AWS Encryption SDK for。 NET与其他一些编程语言实现的不同之处 AWS Encryption SDK 在于：

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

那个 AWS Encryption SDK for。 NET是 AWS Encryption SDK in Dafny 的产物，这是一种正式的验证语言，你可以用它来编写规范、实现规范的代码以及测试规范。结果为在确保功能正确性的框架中实施 AWS Encryption SDK 功能的库。

了解更多

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

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

主题

正在安装 f AWS Encryption SDK or. NET

那个 AWS Encryption SDK for。 NET以AWS.Cryptography.EncryptionSDK套餐形式提供 NuGet。有关安装和构建 for 的 AWS Encryption SDK 详细信息。 NET，请参阅aws-encryption-sdk-net存储库中的 README.md 文件。

版本 3.x

版本 3。 for AWS Encryption SDK 的 x。 NET支持。 NET框架 4.5.2 — 4.8 仅在 Windows 上运行。它支持。 NET酷睿 3.0+ 和。 NET在所有支持的操作系统上均为 5.0 及更高版本。

版本 4.x

版本 4。 for AWS Encryption SDK 的 x。 NET支持。 NET6.0 和。 NET框架 net48 及更高版本。

那个 AWS Encryption SDK for。 NET AWS SDK for .NET 即使你没有使用 AWS Key Management Service (AWS KMS) 键，也需要。它与 NuGet 软件包一起安装。但是，除非您使用的是 AWS KMS 密钥，否 AWS Encryption SDK 则。 NET不需要 AWS 凭证 AWS 账户，也不需要与任何 AWS 服务进行交互。如需有关设置 AWS 账户的帮助，请参阅将 AWS Encryption SDK 与 AWS KMS 结合使用。

正在调试 f AWS Encryption SDK or. NET

那个 AWS Encryption SDK for。 NET不生成任何日志。for 中的 AWS Encryption SDK 例外情况。 NET生成异常消息，但不生成堆栈跟踪。

为了帮助您进行调试，请务必在 AWS SDK for .NET中启用日志记录功能。中的日志和错误消息 AWS SDK for .NET 可以帮助您区分中出现的错误和 for 中出现 AWS Encryption SDK 的错误。 AWS SDK for .NET NET。有关 AWS SDK for .NET 日志记录的帮助，请参阅AWSLogging《AWS SDK for .NET 开发人员指南》。（要查看主题，请展开 “打开查看”。 NET框架内容部分。）

AWS KMS for 中的钥匙圈 AWS Encryption SDK 。 NET

for 中的基本 AWS KMS 钥匙圈 AWS Encryption SDK 。 NET只拿一把KMS钥匙。它们还需要一个 AWS KMS 客户端，这使您有机会为KMS密钥配置客户端。 AWS 区域

要创建带有一个或多个包装密 AWS KMS 钥的密钥环，请使用多密钥环。那个 AWS Encryption SDK for。 NET有一个特殊的多密钥环，可以带一个或多个 AWS KMS 密钥，还有一个标准的多密钥环，可以接受任何支持类型的一个或多个钥匙圈。一些程序员更喜欢使用多密钥环方法来创建他们所有的钥匙圈，而且 for. AWS Encryption SDK NET支持该策略。

那个 AWS Encryption SDK for。 NET为所有典型用例（包括多区域密钥）提供基本的单钥匙圈和多密钥环。 AWS KMS

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

Version 3.x

以下示例使用版本 3。 for AWS Encryption SDK 的 x。 NET为包含指定密钥的区域创建默认 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

以下示例使用版本 4。 for AWS Encryption SDK 的 x。 NET为包含指定密钥的区域创建 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)，则会为该us-west-2区域 AWS Encryption SDK 创建默认 AWS KMS 客户端。如果需要自定义 AWS KMS 客户端，请使用 CreateAwsKmsKeyring() 方法。

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

// 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);

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

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

要创建非对称RSA AWS KMS 密钥环，必须提供非对称RSAKMS密钥中的公钥和私钥ARN。必须对公钥进行PEM编码。以下示例使用非对称 AWS KMS 密钥对创建RSA密钥环。

// 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 中必需的加密上下文

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

注意

CMM只有以下版本支持所需的加密上下文：

  • 版本 3。 的 x AWS Encryption SDK for Java

  • 版本 4。 for AWS Encryption SDK 的 x。 NET

  • 版本 4。 的 x AWS Encryption SDK for Python，与可选的加密材料提供者库 (MPL) 依赖项一起使用时。

如果您使用所需的加密上下文对数据进行加密CMM，则只能使用这些支持的版本之一对其进行解密。

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

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

重要

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

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

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 钥匙圈，则 AWS Encryption SDK 为。 NET还使用加密上下文在密钥环的调用中提供其他经过身份验证的数据 (AAD)。 AWS KMS