Biblioteca de clientes de Criptografia de Blobs de Armazenamento do Azure para Java – versão 12.23.1

Artigo
10/25/2023

O Armazenamento de Blobs do Azure é uma solução de armazenamento de objetos da Microsoft para a nuvem. O armazenamento de Blobs é otimizado para armazenar grandes quantidades de dados não estruturados. Dados não estruturados são dados que não estão de acordo com uma definição ou um modelo de dados específico, como texto ou dados binários. Esse pacote dá suporte à criptografia do lado do cliente para armazenamento de blobs.

Código-fonte | Documentação | de referência da APIDocumentação | da API REST Documentação do produto | Amostras

Introdução

Pré-requisitos

JDK (Java Development Kit) com a versão 8 ou superior
Assinatura do Azure
Criar conta de armazenamento

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Depois, inclua a dependência direta na seção de dependências sem a marca de versão.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob-cryptography</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-blob-cryptography</artifactId>
  <version>12.23.1</version>
</dependency>

Criar uma conta de armazenamento

Para criar uma Conta de Armazenamento, você pode usar o Portal do Azure ou a CLI do Azure.

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

Autenticar o cliente

Para interagir com o serviço de Armazenamento (Blob, Fila, Mensagem, MessageId, Arquivo), você precisará criar uma instância da classe Cliente de Serviço. Para tornar isso possível, você precisará da cadeia de caracteres SAS da Conta SAS (assinatura de acesso compartilhado) da conta de Armazenamento. Saiba mais em Token SAS

Obter credenciais

SAS Token

a. Use o snippet da CLI do Azure abaixo para obter o token SAS da Conta de Armazenamento.

az storage blob generate-sas \
    --account-name {Storage Account name} \
    --container-name {container name} \
    --name {blob name} \
    --permissions {permissions to grant} \
    --expiry {datetime to expire the SAS token} \
    --services {storage services the SAS allows} \
    --resource-types {resource types the SAS allows}

Exemplo:

CONNECTION_STRING=<connection-string>

az storage blob generate-sas \
    --account-name MyStorageAccount \
    --container-name MyContainer \
    --name MyBlob \
    --permissions racdw \
    --expiry 2020-06-15

b. Como alternativa, obtenha o Token SAS da conta no Portal do Azure.

Vá para sua conta de armazenamento
Selecione Shared access signature no menu à esquerda
Clique em Generate SAS and connection string (após a instalação)

Credencial de chave compartilhada

a. Use o Nome da conta e a chave da conta. O nome da conta é o nome da conta de armazenamento.

Vá para sua conta de armazenamento
Selecione Access keys no menu à esquerda
Em key1/key2 Copiar o conteúdo do Key campo

b. Use o cadeia de conexão.

Vá para sua conta de armazenamento
Selecione Access keys no menu à esquerda
Em key1/key2 Copiar o conteúdo do Connection string campo

Principais conceitos

O Armazenamento de Blobs foi projetado para:

Fornecimento de imagens ou de documentos diretamente a um navegador.
Armazenamento de arquivos para acesso distribuído.
Transmissão por streaming de áudio e vídeo.
Gravando nos arquivo de log.
Armazenamento de dados de backup e restauração, recuperação de desastres e arquivamento.
Armazenamento de dados para análise por um serviço local ou hospedado no Azure.

Exemplos

Observação: o EncryptedBlobClient uso do é o mesmo que o equivalente BlobClient, a única diferença é a construção do cliente. azure-storage-blob Consulte para casos de uso comuns doBlobClient

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns de criação de criptografia de Blob de Armazenamento do Azure, incluindo:

Criar um EncryptedBlobClient de um BlobClient
Criar um EncryptedBlobClient
Usar um LocalKeyEncryptionKey
Usar um KeyVaultKey

Criar um `EncryptedBlobClient` de um `BlobClient`

Crie um EncryptedBlobClient usando um BlobClient. BlobClient a construção é explicada no azure-storage-blob README.

EncryptedBlobClient client = new EncryptedBlobClientBuilder()
    .key(key, keyWrapAlgorithm)
    .keyResolver(keyResolver)
    .blobClient(blobClient)
    .buildEncryptedBlobClient();

Criar uma `EncryptedBlobClient`

Crie um BlobServiceClient usando um cadeia de conexão.

EncryptedBlobClient client = new EncryptedBlobClientBuilder()
    .key(key, keyWrapAlgorithm)
    .keyResolver(keyResolver)
    .connectionString(connectionString)
    .containerName(containerName)
    .blobName(blobName)
    .buildEncryptedBlobClient();

Usar um local `KeyEncryptionKey`

JsonWebKey localKey = JsonWebKey.fromAes(new SecretKeySpec(keyBytes, secretKeyAlgorithm),
    Arrays.asList(KeyOperation.WRAP_KEY, KeyOperation.UNWRAP_KEY))
    .setId("my-id");
AsyncKeyEncryptionKey akek = new KeyEncryptionKeyClientBuilder()
    .buildAsyncKeyEncryptionKey(localKey).block();

EncryptedBlobClient client = new EncryptedBlobClientBuilder()
    .key(akek, keyWrapAlgorithm)
    .connectionString(connectionString)
    .containerName(containerName)
    .blobName(blobName)
    .buildEncryptedBlobClient();

Usar um `KeyVaultKey`

KeyClient keyClient = new KeyClientBuilder()
    .vaultUrl(keyVaultUrl)
    .credential(tokenCredential)
    .buildClient();
KeyVaultKey rsaKey = keyClient.createRsaKey(new CreateRsaKeyOptions(keyName)
    .setExpiresOn(OffsetDateTime.now().plusYears(1))
    .setKeySize(2048));
AsyncKeyEncryptionKey akek = new KeyEncryptionKeyClientBuilder()
    .credential(tokenCredential)
    .buildAsyncKeyEncryptionKey(rsaKey.getId())
    .block();

EncryptedBlobClient client = new EncryptedBlobClientBuilder()
    .key(akek, keyWrapAlgorithm)
    .connectionString(connectionString)
    .containerName(containerName)
    .blobName(blobName)
    .buildEncryptedBlobClient();

Solução de problemas

Ao interagir com blobs usando essa biblioteca de clientes Java, os erros retornados pelo serviço correspondem aos mesmos códigos de status HTTP retornados para solicitações da API REST. Por exemplo, se você tentar recuperar um contêiner ou blob que não existe em sua Conta de Armazenamento, um 404 erro será retornado, indicando Not Found.

Cliente HTTP padrão

Por padrão, todas as bibliotecas de cliente usam o cliente HTTP do Netty. Adicionar a dependência acima configurará automaticamente a biblioteca de cliente para usar o cliente HTTP do Netty. A configuração ou a alteração do cliente HTTP é detalhada no wiki de clientes HTTP.

Biblioteca SSL padrão

Todas as bibliotecas de cliente, por padrão, usam a biblioteca SSL com o uso do Tomcat nativo para habilitar o desempenho de nível nativo para operações SSL. A biblioteca SSL é um uber jar que contém bibliotecas nativas para Linux/macOS/Windows e fornece melhor desempenho em comparação com a implementação SSL padrão no JDK. Para obter mais informações, incluindo como reduzir o tamanho da dependência, consulte a seção ajuste de desempenho da wiki.

Próximas etapas

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas Frequentes Sobre o Código de Conduta ou entre em contato pelo email opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões

Compartilhar via

Biblioteca de clientes de Criptografia de Blobs de Armazenamento do Azure para Java – versão 12.23.1

Introdução

Pré-requisitos

Incluir o pacote

Incluir o arquivo da BOM

Incluir dependência direta

Criar uma conta de armazenamento

Autenticar o cliente

Obter credenciais

Credencial de chave compartilhada

Principais conceitos

Exemplos

Criar um `EncryptedBlobClient` de um `BlobClient`

Criar uma `EncryptedBlobClient`

Usar um local `KeyEncryptionKey`

Usar um `KeyVaultKey`

Solução de problemas

Cliente HTTP padrão

Biblioteca SSL padrão

Próximas etapas

Contribuição

Comentários

Recursos adicionais

Compartilhar via

Biblioteca de clientes de Criptografia de Blobs de Armazenamento do Azure para Java – versão 12.23.1

Introdução

Pré-requisitos

Incluir o pacote

Incluir o arquivo da BOM

Incluir dependência direta

Criar uma conta de armazenamento

Autenticar o cliente

Obter credenciais

Credencial de chave compartilhada

Principais conceitos

Exemplos

Criar um EncryptedBlobClient de um BlobClient

Criar uma EncryptedBlobClient

Usar um local KeyEncryptionKey

Usar um KeyVaultKey

Solução de problemas

Cliente HTTP padrão

Biblioteca SSL padrão

Próximas etapas

Contribuição

Comentários

Recursos adicionais

Criar um `EncryptedBlobClient` de um `BlobClient`

Criar uma `EncryptedBlobClient`

Usar um local `KeyEncryptionKey`

Usar um `KeyVaultKey`