Criptografia do lado do cliente para blobs

Para usar a criptografia do lado do cliente do código .NET, consulte a Biblioteca de clientes do Armazenamento de Blobs. Verifique se você está usando a versão 12.13.0 ou posterior. Se precisar migrar da versão 11.x para a versão 12.13.0, confira o Guia de migração.

Dois pacotes adicionais são necessários para a integração do Azure Key Vault para a criptografia do lado do cliente:

• O pacote Azure.Core fornece as interfaces IKeyEncryptionKey e IKeyEncryptionKeyResolver. A biblioteca de clientes do Armazenamento de Blobs para .NET já define esse assembly como uma dependência.

• O pacote Azure.Security.KeyVault.Keys (versão 4.x e posterior) fornece o cliente REST do Key Vault e os clientes criptográficos usados com a criptografia do lado do cliente. Certifique-se de que esse pacote é referenciado em seu projeto, se você estiver usando o Azure Key Vault como repositório de chaves.

  O Azure Key Vault foi criado para chaves mestras de alto valor e os limites por cofre de chaves refletem esse design. A partir da versão 4.1.0 de Azure.Security.KeyVault.Keys, a interface IKeyEncryptionKeyResolver não dá suporte ao cache de chaves. Se o cache for necessário devido à limitação, você poderá usar a abordagem demonstrada neste exemplo para injetar uma camada de cache em uma instância de Azure.Security.KeyVault.Keys.Cryptography.KeyResolver.

Os desenvolvedores podem fornecer uma chave, um resolvedor de chaves ou uma chave junto com um resolvedor de chaves. As chaves são identificadas usando um identificador de chave que fornece a lógica para encapsulamento e desencapsulamento da CEK. Um resolvedor de chave é usado para resolver uma chave durante o processo de descriptografia. Ele define um método de resolução que retorna uma chave quando é fornecido um determinado identificador de chave. O resolvedor fornece aos usuários a capacidade de escolher entre várias chaves que são gerenciadas em vários locais.

Na criptografia, a chave é sempre usada e a ausência de uma chave resulta em um erro.

Na descriptografia, se a chave for especificada e seu identificador corresponder ao identificador de chave necessário, essa chave será usada para descriptografia. Caso contrário, a biblioteca de clientes tentará chamar o resolvedor. Se não houver nenhum resolvedor especificado, a biblioteca de clientes gerará um erro. Se um resolvedor for especificado, o resolvedor de chave será invocado para obter a chave. Se o resolvedor for especificado, mas não tiver um mapeamento para o identificador de chave, um erro será gerado pela biblioteca de clientes.

Para usar a criptografia do lado do cliente, crie um objetoClientSideEncryptionOptions e defina-o na criação do cliente com SpecializedBlobClientOptions. Não é possível definir opções de criptografia por API. Todo o resto é tratado internamente pela biblioteca de clientes.

// Your key and key resolver instances, either through Azure Key Vault SDK or an external implementation.
IKeyEncryptionKey key;
IKeyEncryptionKeyResolver keyResolver;

// Create the encryption options to be used for upload and download.
ClientSideEncryptionOptions encryptionOptions = new ClientSideEncryptionOptions(ClientSideEncryptionVersion.V2_0)
{
   KeyEncryptionKey = key,
   KeyResolver = keyResolver,
   // String value that the client library will use when calling IKeyEncryptionKey.WrapKey()
   KeyWrapAlgorithm = "some algorithm name"
};

// Set the encryption options on the client options.
BlobClientOptions options = new SpecializedBlobClientOptions() { ClientSideEncryption = encryptionOptions };

// Create blob client with client-side encryption enabled.
// Client-side encryption options are passed from service clients to container clients, 
// and from container clients to blob clients.
// Attempting to construct a BlockBlobClient, PageBlobClient, or AppendBlobClient from a BlobContainerClient
// with client-side encryption options present will throw, as this functionality is only supported with BlobClient.
BlobClient blob = new BlobServiceClient
(new Uri($"https://{accountName}.blob.core.windows.net"), new DefaultAzureCredential(), options).GetBlobContainerClient("my-container").GetBlobClient("myBlob");

// Upload the encrypted contents to the blob.
blob.Upload(stream);

// Download and decrypt the encrypted contents from the blob.
MemoryStream outputStream = new MemoryStream();
blob.DownloadTo(outputStream);

Você pode aplicar opções de criptografia a construtores BlobServiceClient, BlobContainerClient ou BlobClient que aceitam objetos BlobClientOptions.

Se um objeto BlobClient já existir no código, mas sem opções de criptografia do lado do cliente, você poderá usar um método de extensão para criar uma cópia desse objeto com o ClientSideEncryptionOptionsdeterminado. Esse método de extensão evita a sobrecarga de construir um novo objeto BlobClient do zero.

using Azure.Storage.Blobs.Specialized;

// An existing BlobClient instance and encryption options.
BlobClient plaintextBlob;
ClientSideEncryptionOptions encryptionOptions;

// Get a copy of the blob that uses client-side encryption.
BlobClient clientSideEncryptionBlob = plaintextBlob.WithClientSideEncryptionOptions(encryptionOptions);

Depois de atualizar o código para usar a criptografia do lado do cliente v2, descriptografe e criptografe novamente todos os dados criptografados existentes, conforme descrito em Criptografar novamente dados já criptografados com a criptografia do lado do cliente v2.

Para usar a criptografia do lado do cliente do código Java, consulte a Biblioteca de clientes do Armazenamento de Blobs. Verifique se você está usando a versão 12.18.0 ou posterior. Se você precisar migrar de uma versão anterior da biblioteca de clientes Java, consulte o Guia de migração do Armazenamento de Blobs para Java.

Para usar a criptografia do lado do cliente v2.1, inclua uma dependência na versão azure-storage-blob-cryptography 12.27.0 ou posterior. A criptografia do lado do cliente v2 tem um tamanho de parte fixo de 4 MiB, enquanto a v2.1 inclui a capacidade de configurar o comprimento da região para criptografia autenticada. O comprimento da região é configurável de 16 bytes até 1 GiB.

Para usar a criptografia do lado do cliente v2.1, crie uma instância BlobClientSideEncryptionOptions e, opcionalmente, defina o comprimento da região usando o método setAuthenticatedRegionDataLengthInBytes. Em seguida, passe as opções de criptografia para o construtor EncryptedBlobClientBuilder.

Adicione as seguintes diretivas import ao código:

import com.azure.core.cryptography.*;
import com.azure.storage.blob.specialized.cryptography.*;

O exemplo de código a seguir mostra como usar a criptografia do lado do cliente v2.1 para criptografar um blob para upload:

// Your key instance, either through Azure Key Vault SDK or an external implementation
AsyncKeyEncryptionKey keyEncryptionKey;
AsyncKeyEncryptionKeyResolver keyResolver;
String keyWrapAlgorithm = "algorithm name";

// Sets the region length to 4 KiB
BlobClientSideEncryptionOptions encryptionOptions = new BlobClientSideEncryptionOptions()
    .setAuthenticatedRegionDataLengthInBytes(1024 * 4);
 
EncryptedBlobClient ebc = new EncryptedBlobClientBuilder(EncryptionVersion.V2_1)
    .blobClient(client)
    .key(key, keyWrapAlgorithm)
    .keyResolver(keyResolver)
    .credential(new DefaultAzureCredentialBuilder().build())
    .endpoint("https://<storage-account-name>.blob.core.windows.net/")
    .clientSideEncryptionOptions(encryptionOptions)
    .buildEncryptedBlobClient();

ebc.upload(BinaryData.fromString("sample data"));

Para saber mais sobre a biblioteca usada para criptografia do lado do cliente, consulte a Biblioteca de clientes de Criptografia de Blobs para Java do Armazenamento do Azure.

Se você estiver migrando da criptografia do lado do cliente v1, descriptografe e criptografe novamente todos os dados criptografados existentes, conforme descrito em Criptografar novamente dados criptografados anteriormente com criptografia do lado do cliente v2.

Para usar a criptografia do lado do cliente do código Python, consulte a Biblioteca de clientes do Armazenamento de Blobs. Verifique se você está usando a versão 12.13.0 ou posterior. Se você precisar migrar de uma versão anterior da biblioteca de clientes Python, consulte o Guia de migração do Armazenamento de Blobs para Python.

O exemplo a seguir mostra como usar a migração do lado do cliente v2 do Python:

blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
    blob_client.require_encryption = True
    blob_client.key_encryption_key = kek
    blob_client.encryption_version = ‘2.0’  # Use Version 2.0!

    with open("decryptedcontentfile.txt", "rb") as stream:
        blob_client.upload_blob(stream, overwrite=OVERWRITE_EXISTING)

Depois de atualizar o código para usar a criptografia do lado do cliente v2, descriptografe e criptografe novamente todos os dados criptografados existentes, conforme descrito em Criptografar novamente dados já criptografados com a criptografia do lado do cliente v2.

Para ver um exemplo de projeto que mostra como migrar dados da criptografia do lado do cliente v1 para a v2 e como criptografar dados com a criptografia do lado do cliente v2 no .NET, consulte o Exemplo de projeto de migração de criptografia.

Para ver um exemplo de projeto que mostra como migrar dados da criptografia do lado do cliente v1 para a v2 e como criptografar dados com a criptografia do lado do cliente v2 no Java, consulte ClientSideEncryptionV2Uploader.

Para ver um exemplo de projeto que mostra como migrar dados da criptografia do lado do cliente v1 para a v2 e como criptografar dados com a criptografia do lado do cliente v2 no Python, consulte Migração da criptografia do lado do cliente V1 para a V2.