AWS Encryption SDK para .NET - AWS Encryption SDK
Instalar e compilarDepuraçãoTokens de autenticação do AWS KMSCMM do contexto de criptografia necessário

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

AWS Encryption SDK para .NET

AWS Encryption SDK para .NET é uma biblioteca de criptografia do lado do cliente para desenvolvedores que escrevem aplicações em C# e em outras linguagens de programação .NET. É compatível com Windows, macOS e Linux.

Todas as implementações de linguagem de programação do AWS Encryption SDK são interoperáveis. No entanto, se você criptografar dados usando o CMM de contexto de criptografia necessário na versão 4.x do AWS Encryption SDK para .NET, só poderá descriptografá-lo com a versão 4.x do AWS Encryption SDK para .NET ou versão 3.x do AWS Encryption SDK for Java.

nota

A versão 4.0.0 do AWS Encryption SDK para .NET se desvia da Especificação da mensagem AWS Encryption SDK. Como resultado, as mensagens criptografadas pela versão 4.0.0 só podem ser descriptografadas pela versão 4.0.0 ou posterior do AWS Encryption SDK para .NET. Eles não podem ser descriptografados por nenhuma outra implementação de linguagem de programação.

A versão 4.0.1 do AWS Encryption SDK para .NET grava mensagens de acordo com a especificação da mensagem do AWS Encryption SDK e é interoperável com outras implementações de linguagem de programação. Por padrão, a versão 4.0.1 pode ler mensagens criptografadas pela versão 4.0.0. No entanto, se você não quiser descriptografar mensagens criptografadas pela versão 4.0.0, você pode especificar a propriedade NetV4_0_0_RetryPolicy para impedir que o cliente leia essas mensagens. Para obter mais informações, consulte as notas da versão v4.0.1 no repositório aws-encryption-sdk-dafny no GitHub.

O AWS Encryption SDK para .NET difere de algumas das outras implementações de linguagem de programação do AWS Encryption SDK das seguintes maneiras:

O AWS Encryption SDK para .NET inclui todos os atributos de segurança introduzidos nas versões 2.0.x e posteriores de outras implementações de linguagem do AWS Encryption SDK. No entanto, se você estiver usando o AWS Encryption SDK for. NET para descriptografar dados criptografados por uma versão pré-2.0.x, outra implementação de linguagem do AWS Encryption SDK, talvez seja necessário ajustar sua política de compromisso. Para obter mais detalhes, consulte Como definir sua política de compromisso.

O AWS Encryption SDK para .NET é um produto do AWS Encryption SDK no Dafny, uma linguagem de verificação formal na qual você escreve especificações, o código para implementá-las e as provas para testá-las. O resultado é uma biblioteca que implementa os atributos do AWS Encryption SDK em uma estrutura que garante a correção funcional.

Saiba mais

  • Para ver exemplos de como configurar opções no AWS Encryption SDK, como especificar um pacote alternativo de algoritmos, limitar chaves de dados criptografadas e usar chaves de várias regiões do AWS KMS, consulte Configurar o AWS Encryption SDK.

  • Para obter detalhes sobre como programar com o AWS Encryption SDK para .NET, consulte o diretório aws-encryption-sdk-net do repositório aws-encryption-sdk-dafny no GitHub.

Tópicos

Instalar o AWS Encryption SDK para .NET

O AWS Encryption SDK para .NET está disponível como pacote do AWS.Cryptography.EncryptionSDK no NuGet. Para obter detalhes sobre como instalar e criar o AWS Encryption SDK para .NET, consulte o arquivo README.md no repositório aws-encryption-sdk-net.

Versão 3.x

Versão 3.x do AWS Encryption SDK para .NET oferece suporte ao .NET Framework 4.5.2 – 4.8 somente no Windows. É compatível com o .NET Core 3.0+ e o .NET 5.0 e versões posteriores em todos os sistemas operacionais compatíveis.

Versão 4.x

A versão 4.x do AWS Encryption SDK para .NET oferece suporte ao .NET 6.0 e ao .NET Framework net48 e versões posteriores.

O AWS Encryption SDK para .NET exige o AWS SDK for .NET mesmo se você não estiver usando as chaves AWS Key Management Service (AWS KMS). É instalado com o pacote NuGet. No entanto, a menos que você esteja usando chaves AWS KMS, o AWS Encryption SDK para .NET não exige uma Conta da AWS, credenciais da AWS ou interação com nenhum serviço da AWS. Para obter ajuda para configurar uma conta da AWS, se necessário, consulteUso da AWS Encryption SDK com o AWS KMS.

Depuração do AWS Encryption SDK para .NET

O AWS Encryption SDK para .NET não gera nenhum log. As exceções no AWS Encryption SDK para .NET geram uma mensagem de exceção, mas nenhum rastreamento de pilha.

Para ajudar na depuração, certifique-se de habilitar o login no AWS SDK for .NET. Os registros e mensagens de erro do AWS SDK for .NET podem ajudar você a distinguir os erros decorrentes do AWS SDK for .NET e os do AWS Encryption SDK para .NET. Para obter ajuda com o registro em log do AWS SDK for .NET, consulte AWSLogging no Guia do desenvolvedor do AWS SDK for .NET. (Para ver o tópico, expanda a seção Abrir para ver o conteúdo do .NET Framework.)

Tokens de autenticação do AWS KMS no AWS Encryption SDK para .NET

Os token de autenticação básicos do AWS KMS no AWS Encryption SDK para .NET usam apenas uma chave do KMS. Eles também exigem um cliente do AWS KMS, o que dá a você a oportunidade de configurar o cliente para a Região da AWS da chave KMS.

Para criar um token de autenticação do AWS KMS com uma ou mais chaves de encapsulamento, use um multitoken de autenticação. O AWS Encryption SDK para .NET tem um multitoken especial que aceita uma ou mais chaves do AWS KMS e um multitoken padrão que aceita um ou mais tokens de autenticação de qualquer tipo compatível. Alguns programadores preferem usar um método multitoken de autenticação para criar todos os seus tokens de autenticação, e o AWS Encryption SDK para .NET é compatível com essa estratégia.

O AWS Encryption SDK para .NET fornece tokens de autenticação básicos de chave única e multitokens de autenticação para todos os casos de uso típicos, incluindo chaves multirregionais doAWS KMS.

Por exemplo, você pode usar o método CreateAwsKmsKeyring() para criar um token de autenticação do AWS KMS com uma chave do AWS KMS.

Version 3.x

O exemplo a seguir usa a versão 3 x do AWS Encryption SDK para .NET para criar um cliente do AWS KMS padrão para a região que contém a chave especificada.

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

O exemplo a seguir usa a versão 4x do AWS Encryption SDK para .NET para criar um cliente do AWS KMS para a região que contém a chave especificada.

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

Para criar um token de autenticação com uma ou mais chaves do AWS KMS, use o método CreateAwsKmsMultiKeyring(). Este exemplo usa duas chaves do AWS KMS. Para especificar uma chave do KMS, use o parâmetro Generator. O parâmetro KmsKeyIds, que especifica chaves KMS adicionais, é opcional.

A entrada para este token de autenticação não requer um cliente do AWS KMS. Em vez disso, o AWS Encryption SDK usa o cliente do AWS KMS padrão para cada região representada por uma chave do KMS no token de autenticação. Por exemplo, se a chave KMS identificada pelo valor do parâmetro Generator estiver na região Oeste dos EUA (Oregon) (us-west-2), o AWS Encryption SDK criará um cliente do AWS KMS padrão para a região us-west-2. Se você precisar personalizar o cliente do AWS KMS, use o método CreateAwsKmsKeyring().

O exemplo a seguir usa a versão 4.x do AWS Encryption SDK para .NET e o método CreateAwsKmsKeyring() para personalizar o cliente do 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);

A versão 4.x do AWS Encryption SDK para .NET é compatível com tokens de autenticação do AWS KMS que usam criptografia simétrica (SYMMETRIC_DEFAULT) ou chaves RSA do KMS assimétricas. Tokens de autenticação do AWS KMS criados com chaves RSA do KMS assimétricas só podem conter um par de chaves.

Para criptografar com um token de autenticação de RSA assimétrico do AWS KMS, você não precisa de kms:GenerateDataKey ou kms:Encrypt, porque deve especificar o material de chave pública que deseja usar para criptografia ao criar o token de autenticação. Nenhuma chamada do AWS KMS é feita ao criptografar com este token de autenticação. Para descriptografar com um token de autenticação de RSA assimétrico do AWS KMS, é necessária a permissão KMS:Decrypt.

Para criar um token de autenticação de RSA assimétrico do AWS KMS, você deve fornecer o ARN de chave pública e de chave privada da sua chave RSA assimétrica do KMS. A chave pública deve ser codificada em PEM. O exemplo a seguir cria um token de autenticação do AWS KMS com um par de chaves RSA assimétricas.

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

Contextos de criptografia necessários na versão 4.x

Com a versão 4.x do AWS Encryption SDK para .NET, você pode usar o CMM de contexto de criptografia necessário para exigir contextos de criptografia em suas operações criptográficas. Um contexto de criptografia é um conjunto de pares de chave/valor não secretos. O contexto de criptografia é associado de maneira criptográfica aos dados criptografados de forma que o mesmo contexto de criptografia é necessário para descriptografar o campo. Ao usar o CMM de contexto de criptografia necessário, é possível especificar uma ou mais chaves de contexto de criptografia necessárias (chaves obrigatórias) que devem ser incluídas em todas as chamadas de criptografia e descriptografia.

nota

O contexto de criptografia necessário (CMM) só é interoperável com a versão 3.x do AWS Encryption SDK for Java. Não é interoperável com nenhuma outra implementação de linguagem de programação. Se você criptografar dados usando o CMM de contexto de criptografia necessário, só poderá descriptografá-los com a versão 3.x do AWS Encryption SDK for Java ou a versão 4.x do AWS Encryption SDK para .NET.

Ao criptografar, o AWS Encryption SDK verifica se todas as chaves de contexto de criptografia necessárias estão incluídas no contexto de criptografia que você especificou. O AWS Encryption SDK sinaliza os contextos de criptografia que você especificou. Somente os pares de chave/valor que não são chaves obrigatórias são serializados e armazenados em texto simples no cabeçalho da mensagem criptografada retornada pela operação de criptografia.

Ao descriptografar, você deve fornecer um contexto de criptografia que contenha todos os pares de chave/valor que representam as chaves necessárias. O AWS Encryption SDK usa esse contexto de criptografia e os pares de chave/valor armazenados no cabeçalho da mensagem criptografada para reconstruir o contexto de criptografia original que você especificou na operação de criptografia. Se o AWS Encryption SDK não puder reconstruir o contexto de criptografia original, a operação de descriptografia falhará. Se você fornecer um par de chave/valor que contenha a chave necessária com um valor incorreto, a mensagem criptografada não poderá ser descriptografada. Você deve fornecer o mesmo par de chave/valor especificado na criptografia.

Importante

Considere cuidadosamente quais valores você escolhe para as chaves necessárias no contexto de criptografia. Você deverá fornecer as mesmas chaves e os valores correspondentes novamente na descriptografia. Se você não conseguir reproduzir as chaves necessárias, a mensagem criptografada não poderá ser descriptografada.

O exemplo a seguir inicializa um token de autenticação do AWS KMS com o CMM de contexto de criptografia necessário.

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

Se você usar um token de autenticação do AWS KMS, o AWS Encryption SDK para .NET também usará o contexto de criptografia para fornecer dados autenticados adicionais (AAD) nas chamadas que o token de autenticação faz para o AWS KMS.