Migração do cliente de criptografia Amazon S3 (V2 para V3) - AWS SDK para C++
Visão geral da migraçãoCompreendendo os conceitos da V3Atualizar os clientes existentes para ler novos formatosMigre clientes de criptografia e descriptografia para a V3Exemplos adicionais

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á.

Migração do cliente de criptografia Amazon S3 (V2 para V3)

nota

Se você estiver usando a V1 do cliente de criptografia Amazon S3, você deve primeiro migrar para a V2 antes de migrar para a V3. Consulte Migração do cliente de criptografia Amazon S3 (V1 para V2).

Este tópico mostra como migrar seus aplicativos da versão 2 (V2) para a versão 3 (V3) do cliente de criptografia Amazon Simple Storage Service (Amazon S3) e garantir a disponibilidade dos aplicativos durante todo o processo de migração. A V3 apresenta o ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY algoritmo e as políticas de compromisso para aprimorar a segurança, protegendo contra a adulteração da chave de dados nos arquivos de instruções.

Visão geral da migração

Essa migração acontece em duas fases:

1. Atualize os clientes existentes para ler novos formatos. Primeiramente, implante a versão atualizada do AWS SDK para C++ na aplicação. Isso permite que os clientes de criptografia V2 existentes descriptografem objetos escritos pelos novos clientes V3. Se seu aplicativo usa vários AWS SDKs, você deve atualizar cada SDK separadamente.

2. Migre clientes de criptografia e descriptografia para a V3. Depois que todos os seus clientes de criptografia V2 puderem ler novos formatos, você poderá migrar seus clientes de criptografia e descriptografia existentes para suas respectivas versões V3.

Compreendendo os conceitos da V3

A versão 3 do cliente de criptografia Amazon S3 introduz novos recursos de segurança que aprimoram a proteção contra adulteração de chaves de dados. Compreender esses conceitos é essencial para uma migração bem-sucedida.

Política de compromisso

As políticas de compromisso controlam como o cliente de criptografia lida com o comprometimento da chave durante as operações de criptografia e descriptografia. A V3 fornece três opções de política para oferecer suporte a diferentes cenários de migração e requisitos de segurança:

FORBID_ENCRYPT_ALLOW_DECRYPT

Comportamento de criptografia: criptografa objetos sem comprometer a chave, usando os mesmos algoritmos da V2.

Comportamento de descriptografia: permite a descriptografia de objetos criptografados com e sem comprometimento de chave.

Implicações de segurança: esta política não impõe o compromisso da chave e pode permitir a adulteração da chave de dados criptografada nos arquivos de instruções. Use essa política somente durante a fase inicial de migração, quando precisar que os clientes V2 leiam objetos recém-criptografados.

Compatibilidade de versão: objetos criptografados com essa política podem ser lidos por todas as implementações V2 e V3.

REQUIRE_ENCRYPT_ALLOW_DECRYPT (padrão)

Comportamento de criptografia: criptografa objetos com comprometimento de chave usando o ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY algoritmo.

Comportamento de descriptografia: permite a descriptografia de objetos criptografados com comprometimento de chave e objetos criptografados sem comprometimento de chave.

Implicações de segurança: essa política fornece uma forte segurança para objetos recém-criptografados, mantendo a compatibilidade com versões anteriores para leitura de objetos mais antigos. Essa é a política recomendada para a maioria dos cenários de migração.

Compatibilidade de versão: objetos criptografados com essa política só podem ser lidos pela V3 e pelas implementações mais recentes da V2. Os clientes V2 não podem descriptografar esses objetos. No entanto, os clientes V3 que usam essa política ainda podem descriptografar objetos criptografados por clientes V2.

REQUIRE_ENCRYPT_REQUIRE_DECRYPT

Comportamento de criptografia: criptografa objetos com comprometimento de chave usando o ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY algoritmo.

Comportamento de descriptografia: permite somente a decodificação de objetos criptografados com comprometimento de chave. Rejeita objetos criptografados sem compromisso de chave.

Implicações de segurança: essa política fornece o mais alto nível de segurança ao impor um compromisso fundamental para todas as operações. Use essa política somente depois que todos os objetos tiverem sido criptografados novamente com comprometimento de chave e você não precisar mais ler objetos criptografados herdados V1 ou V2.

Compatibilidade de versão: objetos criptografados com essa política só podem ser lidos pela V3 e pelas implementações mais recentes da V2. Além disso, os clientes que usam essa política não podem descriptografar objetos criptografados por clientes V1 ou V2.

Considerações sobre migração: durante a migração, comece FORBID_ENCRYPT_ALLOW_DECRYPT se você precisar que os clientes V2 leiam novos objetos e, em seguida, passe para REQUIRE_ENCRYPT_ALLOW_DECRYPT quando todos os clientes forem atualizados para a V3. Por fim, considere REQUIRE_ENCRYPT_REQUIRE_DECRYPT somente depois que todos os objetos legados tiverem sido criptografados novamente.

ALG_AES_256_GCM_HKDF_ _ALGORITMO COMMIT_KEY SHA512

O ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY algoritmo é um novo algoritmo de criptografia introduzido na V3 que fornece segurança aprimorada para chaves de dados criptografadas armazenadas em arquivos de instruções.

Impacto do arquivo de instruções: o ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY algoritmo afeta somente os arquivos de instruções, que são objetos separados do S3 que armazenam metadados de criptografia, incluindo a chave de dados criptografada. Objetos que armazenam metadados de criptografia em metadados de objetos (o método de armazenamento padrão) não são afetados por essa alteração de algoritmo.

Proteção contra adulteração: o ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY algoritmo protege contra a adulteração da chave de dados vinculando criptograficamente a chave de dados criptografada ao contexto de criptografia. Isso impede que os invasores substituam uma chave de dados criptografada diferente no Arquivo de Instruções, o que poderia levar à descriptografia por uma chave não intencional.

Compatibilidade de versão: objetos criptografados com o ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY algoritmo só podem ser descriptografados pelas implementações V3 e pelas versões de transição V2 mais recentes do SDK que incluem suporte à descriptografia V3.

Atenção

Importante: antes de habilitar a criptografia com o ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY algoritmo (usando REQUIRE_ENCRYPT_ALLOW_DECRYPT ou REQUIRE_ENCRYPT_REQUIRE_DECRYPT comprometendo políticas), você deve garantir que todos os clientes que lerão esses objetos tenham sido atualizados para a V3 ou para a versão de transição V2 mais recente que ofereça suporte à descriptografia V3. A falha em atualizar todos os leitores primeiro resultará em falhas na decodificação de objetos recém-criptografados.

Atualizar os clientes existentes para ler novos formatos

Você deve primeiro atualizar seus clientes existentes para a versão mais recente do SDK. Depois de concluir essa etapa, os clientes V2 do seu aplicativo poderão descriptografar objetos criptografados por clientes de criptografia V3 sem atualizar a base de código do seu aplicativo.

Crie e instale a versão mais recente do AWS SDK para C++

Aplicações que consomem o SDK do código-fonte

Se você criar e instalar o AWS SDK para C++ do código-fonte, baixe ou clone o código-fonte do SDK a partir de aws/aws-sdk-cppagora. GitHub Depois, repita as etapas normais de compilação e instalação.

Se você estiver atualizando AWS SDK para C++ de uma versão anterior à 1.11.x, consulte este CHANGELOG para ver as alterações significativas introduzidas em cada versão principal. Para obter mais informações sobre como criar e instalar o AWS SDK para C++, consulte Acessar o AWS SDK para C++ do código-fonte.

Aplicações que consomem o SDK do Vcpkg

Se sua aplicação usa o Vcpkg para monitorar as atualizações do SDK, basta usar o método de atualização do Vcpkg existente para atualizar o SDK para a versão mais recente. Lembre-se de que há um atraso entre o lançamento da versão e a disponibilização dela por meio de um gerenciador de pacotes. A versão mais recente está sempre disponível por meio da instalação do código-fonte.

Você pode executar o seguinte comando para atualizar o pacoteaws-sdk-cpp:

vcpkg upgrade aws-sdk-cpp

E verifique a versão do pacote aws-sdk-cpp:

vcpkg list aws-sdk-cpp

A versão deve ser pelo menos 1.11.x para oferecer suporte à descriptografia de objetos criptografados em V3.

Para obter mais informações sobre como usar o Vcpkg com o AWS SDK para C++, consulte. Acessar o AWS SDK para C++ de um gerenciador de pacotes

Compilar, instalar e implantar suas aplicações

Se seu aplicativo estiver vinculado estaticamente ao AWS SDK para C++, alterações de código não serão necessárias em seu aplicativo, mas você deverá criar seu aplicativo novamente para consumir as alterações mais recentes do SDK. Essa etapa não é necessária para a vinculação dinâmica.

Depois de atualizar a versão de dependência do seu aplicativo e verificar a funcionalidade do aplicativo, continue implantando seu aplicativo em sua frota. Quando a implantação do aplicativo estiver concluída, você poderá prosseguir com a próxima fase de migração do aplicativo para usar os clientes de criptografia e descriptografia V3.

Migre clientes de criptografia e descriptografia para a V3

As etapas a seguir mostram como migrar com sucesso seu código da V2 para a V3 do cliente de criptografia Amazon S3. Como as alterações de código são necessárias, você precisará reconstruir seu aplicativo, independentemente de ele estar vinculado estática ou dinamicamente ao. AWS SDK para C++

Usando clientes de criptografia V3

V3 introduz a S3EncryptionClientV3 classe e substitui CryptoConfigurationV3 os equivalentes V2. As principais diferenças na V3 são:

  • A V3 usa KMSWithContextEncryptionMaterials (o mesmo que a V2), mas requer configuração explícita em. CryptoConfigurationV3

  • Todas as PutObject operações exigem um mapa de contexto de criptografia (pode estar vazio).

  • A V3 apresenta políticas de compromisso para controlar o comportamento de criptografia e descriptografia.

  • Por padrão, a V3 criptografa com comprometimento de chave usando o ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY algoritmo.

  • A API de configuração de descriptografia do algoritmo legado muda de para. config.SetSecurityProfile(SecurityProfile::V2_AND_LEGACY); config.AllowLegacy();

Exemplo: migração da V2 para a V3 com criptografia KMS

Pré-migração (V2) 

// Create encryption materials
auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV2", CUSTOMER_MASTER_KEY_ID);

// Create V2 crypto configuration
CryptoConfigurationV2 cryptoConfig(materials);

// Create V2 encryption client
S3EncryptionClientV2 encryptionClient(cryptoConfig);

// Put object with encryption context
Aws::Map<Aws::String, Aws::String> encryptionContext;
encryptionContext.emplace("client", "aws-sdk-cpp");
encryptionContext.emplace("version", "1.11.0");

PutObjectRequest putObjectRequest;
putObjectRequest.SetBucket(BUCKET_NAME);
putObjectRequest.SetKey(OBJECT_KEY);
// Set object body...

auto putOutcome = encryptionClient.PutObject(putObjectRequest, encryptionContext);

// Get object with encryption context
GetObjectRequest getObjectRequest;
getObjectRequest.SetBucket(BUCKET_NAME);
getObjectRequest.SetKey(OBJECT_KEY);

auto getOutcome = encryptionClient.GetObject(getObjectRequest, encryptionContext);

Durante a migração (V3 com compatibilidade com versões anteriores) 

// Create encryption materials
auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV3", CUSTOMER_MASTER_KEY_ID);

// Create V3 crypto configuration with materials
CryptoConfigurationV3 cryptoConfig(materials);

// Set commitment policy to maintain compatibility with V2 encrypted objects
// This allows V3 clients to decrypt objects encrypted by the V2 client
cryptoConfig.SetCommitmentPolicy(CommitmentPolicy::REQUIRE_ENCRYPT_ALLOW_DECRYPT);

// Create V3 encryption client
S3EncryptionClientV3 encryptionClient(cryptoConfig);

// Put object with encryption context
Aws::Map<Aws::String, Aws::String> encryptionContext;
encryptionContext.emplace("client", "aws-sdk-cpp");
encryptionContext.emplace("version", "1.11.0");

PutObjectRequest putObjectRequest;
putObjectRequest.SetBucket(BUCKET_NAME);
putObjectRequest.SetKey(OBJECT_KEY);
// Set object body...

auto putOutcome = encryptionClient.PutObject(putObjectRequest, encryptionContext);

// Get object with encryption context
GetObjectRequest getObjectRequest;
getObjectRequest.SetBucket(BUCKET_NAME);
getObjectRequest.SetKey(OBJECT_KEY);

auto getOutcome = encryptionClient.GetObject(getObjectRequest, encryptionContext);

Pós-migração (V3 com compromisso fundamental) 

// Create encryption materials
auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV3", CUSTOMER_MASTER_KEY_ID);

// Create V3 crypto configuration with materials
CryptoConfigurationV3 cryptoConfig(materials);

// Use the default commitment policy (REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
// This encrypts with key commitment and does not decrypt V2 objects
// cryptoConfig.SetCommitmentPolicy(CommitmentPolicy::REQUIRE_ENCRYPT_ALLOW_DECRYPT);

// Create V3 encryption client
S3EncryptionClientV3 encryptionClient(cryptoConfig);

// Put object with encryption context
Aws::Map<Aws::String, Aws::String> encryptionContext;
encryptionContext.emplace("client", "aws-sdk-cpp");
encryptionContext.emplace("version", "1.11.0");

PutObjectRequest putObjectRequest;
putObjectRequest.SetBucket(BUCKET_NAME);
putObjectRequest.SetKey(OBJECT_KEY);
// Set object body...

auto putOutcome = encryptionClient.PutObject(putObjectRequest, encryptionContext);

// Get object with encryption context
GetObjectRequest getObjectRequest;
getObjectRequest.SetBucket(BUCKET_NAME);
getObjectRequest.SetKey(OBJECT_KEY);

auto getOutcome = encryptionClient.GetObject(getObjectRequest, encryptionContext);

Exemplos adicionais

Esta seção fornece exemplos adicionais para configurar as opções do cliente de criptografia V3 para oferecer suporte a vários cenários e requisitos de migração.

Habilitando o Legacy Support

Os clientes V3 podem descriptografar objetos criptografados por clientes V2 somente ao usar as políticas de compromisso ou. REQUIRE_ENCRYPT_ALLOW_DECRYPT FORBID_ENCRYPT_ALLOW_DECRYPT No entanto, se você precisar descriptografar objetos criptografados por clientes V1, deverá habilitar explicitamente o suporte legado usando o método. AllowLegacy()

Quando usar o suporte antigo:

  • Você tem objetos no S3 que foram criptografados usando a V1 do S3 Encryption Client.

  • Você precisa ler esses objetos criptografados em V1 com seu cliente V3 durante o processo de migração.

  • Você está usando a política de FORBID_ENCRYPT_ALLOW_DECRYPT compromisso REQUIRE_ENCRYPT_ALLOW_DECRYPT ou.

Atenção

O suporte antigo só deve ser ativado temporariamente durante a migração. Depois que todos os objetos V1 tiverem sido criptografados novamente com V2 ou V3, desative o suporte legado para garantir a máxima segurança.

Exemplo: habilitando o Legacy Support

// Create encryption materials
auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV3", CUSTOMER_MASTER_KEY_ID);

// Create V3 crypto configuration
CryptoConfigurationV3 cryptoConfig(materials);

// Enable legacy support to read V1 encrypted objects
cryptoConfig.AllowLegacy();

// Set commitment policy (default is REQUIRE_ENCRYPT_REQUIRE_DECRYPT but we need to allow decryption)
cryptoConfig.SetCommitmentPolicy(CommitmentPolicy::REQUIRE_ENCRYPT_ALLOW_DECRYPT);

// Create V3 encryption client with legacy support enabled
S3EncryptionClientV3 encryptionClient(cryptoConfig);

// Now you can decrypt objects encrypted by V1, V2, and V3 clients
GetObjectRequest getObjectRequest;
getObjectRequest.SetBucket(BUCKET_NAME);
getObjectRequest.SetKey(LEGACY_OBJECT_KEY);

Aws::Map<Aws::String, Aws::String> encryptionContext;
auto getOutcome = encryptionClient.GetObject(getObjectRequest, encryptionContext);

Configurando o método de armazenamento

O S3 Encryption Client pode armazenar metadados de criptografia de duas maneiras: como metadados de objeto (o padrão) ou em um arquivo de instruções separado. Você pode configurar o método de armazenamento usando o SetStorageMethod() método ativadoCryptoConfigurationV3.

Opções de método de armazenamento:

METADATA (padrão)

Os metadados de criptografia são armazenados nos cabeçalhos de metadados do objeto. Esse é o método mais comum e conveniente, pois todas as informações de criptografia são armazenadas com o próprio objeto.

Quando usar: use esse método para a maioria dos cenários. Ele simplifica o gerenciamento de objetos, pois os metadados de criptografia viajam com o objeto.

INSTRUCTION_FILE

Os metadados de criptografia são armazenados em um objeto S3 separado (o Arquivo de Instruções) com o sufixo. .instruction

Quando usar: use esse método quando o tamanho dos metadados do objeto for uma preocupação ou quando você precisar separar os metadados de criptografia do objeto criptografado. Observe que o uso de arquivos de instruções requer o gerenciamento de dois objetos do S3 (o objeto criptografado e seu arquivo de instruções) em vez de um.

Exemplo: Configurando o método de armazenamento

// Create encryption materials
auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV3", CUSTOMER_MASTER_KEY_ID);

// Create V3 crypto configuration
CryptoConfigurationV3 cryptoConfig(materials);

// Option 1: Use metadata storage (default, can be omitted)
cryptoConfig.SetStorageMethod(StorageMethod::METADATA);

// Option 2: Use instruction file storage
cryptoConfig.SetStorageMethod(StorageMethod::INSTRUCTION_FILE);

// Create V3 encryption client with the configured storage method
S3EncryptionClientV3 encryptionClient(cryptoConfig);

// Put object - encryption metadata will be stored according to the configured method
Aws::Map<Aws::String, Aws::String> encryptionContext;
encryptionContext.emplace("client", "aws-sdk-cpp");

PutObjectRequest putObjectRequest;
putObjectRequest.SetBucket(BUCKET_NAME);
putObjectRequest.SetKey(OBJECT_KEY);
// Set object body...

auto putOutcome = encryptionClient.PutObject(putObjectRequest, encryptionContext);

// If using INSTRUCTION_FILE, a separate object with key "OBJECT_KEY.instruction" will be created
nota

Ao usar o método INSTRUCTION_FILE de armazenamento, lembre-se de que a exclusão do objeto criptografado não exclui automaticamente o arquivo de instruções. Você deve gerenciar os dois objetos separadamente.