Criptografia do lado do cliente para blobs

Para usar a criptografia do lado do cliente do seu código .NET, consulte a biblioteca de cliente de Armazenamento de Blob. Certifique-se de que está a utilizar a versão 12.13.0 ou posterior. Se você precisar migrar da versão 11.x para a versão 12.13.0, consulte o Guia de migração.

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

• O pacote Azure.Core fornece as IKeyEncryptionKey interfaces e IKeyEncryptionKeyResolver . A biblioteca de cliente de Armazenamento de Blob 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 Cofre da Chave e os clientes criptográficos usados com criptografia do lado do cliente. Certifique-se de que este pacote é referenciado em seu projeto se você estiver usando o Azure Key Vault como seu armazenamento de chaves.

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

Os desenvolvedores podem fornecer uma chave, um resolvedor de chaves ou ambos uma chave e um resolvedor de chaves. As chaves são identificadas usando um identificador de chave que fornece a lógica para encapsular e desembrulhar o CEK. Um resolvedor de chave é usado para resolver uma chave durante o processo de desencriptação. O resolvedor de chaves define um método de resolução que retorna uma chave dada um identificador de chave. O resolvedor oferece aos usuários a capacidade de escolher entre várias chaves que são gerenciadas em vários locais.

Na encriptação, a chave é sempre usada e a ausência de uma chave resulta num erro.

Na desencriptação, se a chave for especificada e o seu identificador corresponder ao identificador de chave necessário, essa chave é usada para desencriptação. Caso contrário, a biblioteca de cliente tentará chamar o resolvedor. Se não houver nenhum resolvedor especificado, a biblioteca do cliente lançará 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, a biblioteca do cliente lançará um erro.

Para usar a criptografia do lado do cliente, crie um objeto ClientSideEncryptionOptions 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 pela biblioteca do cliente internamente.

// 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 um construtor BlobServiceClient, BlobContainerClient ou BlobClient que aceitam objetos BlobClientOptions .

Se um objeto BlobClient já existir em seu código, mas não tiver 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 ClientSideEncryptionOptions fornecido. 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 seu código para usar a criptografia do lado do cliente v2, certifique-se de descriptografar e criptografar 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 seu código Java, consulte a biblioteca do cliente de Armazenamento de Blob. Certifique-se de que está a utilizar a versão 12.18.0 ou posterior. Se você precisar migrar de uma versão anterior da biblioteca do cliente 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 azure-storage-blob-cryptography versão 12.27.0 ou posterior. A criptografia do lado do cliente v2 tem um tamanho de bloco 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 setAuthenticatedRegionDataLengthInBytes método. Em seguida, passe as opções de criptografia para o construtor EncryptedBlobClientBuilder .

Adicione as seguintes diretivas import ao seu 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 Biblioteca de cliente de criptografia de Blobs de Armazenamento do Azure para Java.

Se você estiver migrando da criptografia do lado do cliente v1, certifique-se de descriptografar e criptografar 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 seu código Python, consulte a biblioteca de cliente de Armazenamento de Blob. Certifique-se de que está a utilizar a versão 12.13.0 ou posterior. Se você precisar migrar de uma versão anterior da biblioteca de cliente Python, consulte o guia de migração de armazenamento de Blob 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 seu código para usar a criptografia do lado do cliente v2, certifique-se de descriptografar e criptografar novamente todos os dados criptografados existentes, conforme descrito em Criptografar novamente dados criptografados anteriormente com criptografia do lado do cliente v2.

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

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

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