Biblioteca de clientes do Azure Key Vault Key para Java – versão 4.7.1

  • Artigo

O Azure Key Vault é um serviço de nuvem que fornece armazenamento seguro de chaves para criptografar seus dados. Várias chaves e várias versões da mesma chave podem ser mantidas no Key Vault do Azure. As chaves criptográficas no Azure Key Vault são representadas como objetos JSON Web Key [JWK].

O Azure Key Vault O HSM Gerenciado é um serviço de nuvem totalmente gerenciado, altamente disponível, de locatário único e compatível com padrões, que permite proteger chaves criptográficas para seus aplicativos de nuvem usando HSMs validados fips 140-2 nível 3.

O cliente da biblioteca de chaves Key Vault do Azure dá suporte a chaves RSA e chaves EC (Curva Elíptica), cada uma com suporte correspondente em HSM (módulos de segurança de hardware). Ele oferece operações para criar, recuperar, atualizar, excluir, limpar, fazer backup, restaurar e listar as chaves e suas versões.

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

Introdução

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 (disponibilidade geral) 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>

e inclua a dependência direta na seção dependências sem a marca de versão, conforme mostrado abaixo.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-security-keyvault-keys</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-security-keyvault-keys</artifactId>
    <version>4.7.1</version>
</dependency>

Pré-requisitos

Autenticar o cliente

Para interagir com o serviço de Key Vault do Azure, você precisará criar uma instância da KeyClient classe ou da CryptographyClient classe, bem como uma URL do cofre e um objeto de credencial. Os exemplos mostrados neste documento usam um objeto de credencial chamado DefaultAzureCredential, que é apropriado para a maioria dos cenários, incluindo ambientes locais de desenvolvimento e produção. Além disso, recomendamos usar uma identidade gerenciada para autenticação em ambientes de produção.

Você pode encontrar mais informações sobre diferentes maneiras de autenticação e seus tipos de credencial correspondentes na documentação da Identidade do Azure.

Criar cliente chave

Depois de executar a configuração de autenticação que melhor se adequa a você e substituiu a URL-key-vault pela URL do cofre de chaves ou do HSM gerenciado, você poderá criar o KeyClient:

KeyClient keyClient = new KeyClientBuilder()
    .vaultUrl("<your-key-vault-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

OBSERVAÇÃO: para usar um cliente assíncrono, use KeyAsyncClient em vez de KeyClient e chame buildAsyncClient().

Criar cliente de criptografia

Depois de executar a DefaultAzureCredential configuração que melhor se adequa a você e substituiu your-key-vault-url pela URL do cofre de chaves ou HSM gerenciado, você pode criar o CryptographyClient:

// Create client with key identifier from Key Vault.
CryptographyClient cryptoClient = new CryptographyClientBuilder()
    .keyIdentifier("<your-key-id-from-key-vault>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

OBSERVAÇÃO: para usar um cliente assíncrono, use CryptographyAsyncClient em vez de CryptographyClient e chame buildAsyncClient().

Principais conceitos

Chave

O Azure Key Vault dá suporte a vários tipos de chave (RSA&EC) e algoritmos e permite o uso de HSM (Módulos de Segurança de Hardware) para chaves de alto valor. Além do material de chave, os seguintes atributos podem ser especificados:

  • habilitado: especifica se a chave está habilitada e utilizável para operações criptográficas.
  • not_before: identifica a hora anterior à qual a chave não deve ser usada para operações criptográficas.
  • expira: identifica o tempo de expiração em ou após o qual a chave NÃO DEVE ser usada para operações criptográficas.
  • criado: indica quando essa versão da chave foi criada.
  • atualizado: indica quando esta versão da chave foi atualizada.

Cliente-chave:

O cliente-chave executa as interações com o serviço de Key Vault do Azure para obter, definir, atualizar, excluir e listar chaves e suas versões. Existem clientes assíncronos (KeyAsyncClient) e síncronos (KeyClient) no SDK, permitindo a seleção de um cliente com base no caso de uso de um aplicativo. Depois de inicializar uma chave, você poderá interagir com os tipos de recursos primários em Key Vault.

Cliente de criptografia:

O cliente de criptografia executa as operações criptográficas localmente ou chama o serviço de Key Vault do Azure, dependendo da quantidade de informações importantes disponíveis localmente. Ele dá suporte à criptografia, descriptografia, assinatura, verificação, encapsulamento de chave, desembrulhamento de chave e recuperação da chave configurada. Existem clientes assíncronos (CryptographyAsyncClient) e síncronos (CryptographyClient) no SDK, permitindo a seleção de um cliente com base no caso de uso de um aplicativo.

Exemplos

API síncrona

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas de serviço mais comuns do Azure Key Vault Key, incluindo:

Criar uma chave

Crie uma chave a ser armazenada no Key Vault do Azure.

  • createKey cria uma nova chave no cofre de chaves. Se uma chave com o mesmo nome já existir, uma nova versão da chave será criada.
KeyVaultKey rsaKey = keyClient.createRsaKey(new CreateRsaKeyOptions("CloudRsaKey")
    .setExpiresOn(OffsetDateTime.now().plusYears(1))
    .setKeySize(2048));
System.out.printf("Key created with name \"%s\" and id %s%n", rsaKey.getName(), rsaKey.getId());

KeyVaultKey ecKey = keyClient.createEcKey(new CreateEcKeyOptions("CloudEcKey")
    .setCurveName(KeyCurveName.P_256)
    .setExpiresOn(OffsetDateTime.now().plusYears(1)));
System.out.printf("Key created with name \"%s\" and id %s%n", ecKey.getName(), ecKey.getId());

Recuperar uma chave

Recupere uma chave armazenada anteriormente chamando getKey.

KeyVaultKey key = keyClient.getKey("<key-name>");
System.out.printf("A key was returned with name \"%s\" and id %s%n", key.getName(), key.getId());

Atualizar uma chave existente

Atualize uma chave existente chamando updateKeyProperties.

// Get the key to update.
KeyVaultKey key = keyClient.getKey("<key-name>");
// Update the expiry time of the key.
key.getProperties().setExpiresOn(OffsetDateTime.now().plusDays(30));
KeyVaultKey updatedKey = keyClient.updateKeyProperties(key.getProperties());
System.out.printf("Key's updated expiry time: %s%n", updatedKey.getProperties().getExpiresOn());

Excluir uma chave

Exclua uma chave existente chamando beginDeleteKey.

SyncPoller<DeletedKey, Void> deletedKeyPoller = keyClient.beginDeleteKey("<key-name>");

PollResponse<DeletedKey> deletedKeyPollResponse = deletedKeyPoller.poll();

// Deleted key is accessible as soon as polling begins.
DeletedKey deletedKey = deletedKeyPollResponse.getValue();
// Deletion date only works for a soft-delete enabled key vault.
System.out.printf("Deletion date: %s%n", deletedKey.getDeletedOn());

// The key is being deleted on the server.
deletedKeyPoller.waitForCompletion();

Listar chaves

Liste as chaves no cofre de chaves chamando listPropertiesOfKeys.

// List operations don't return the keys with key material information. So, for each returned key we call getKey to
// get the key with its key material information.
for (KeyProperties keyProperties : keyClient.listPropertiesOfKeys()) {
    KeyVaultKey keyWithMaterial = keyClient.getKey(keyProperties.getName(), keyProperties.getVersion());
    System.out.printf("Received key with name \"%s\" and type \"%s\"%n", keyWithMaterial.getName(),
        keyWithMaterial.getKey().getKeyType());
}

Encrypt

Criptografar texto sem formatação chamando encrypt.

byte[] plaintext = new byte[100];
new SecureRandom(SEED).nextBytes(plaintext);

// Let's encrypt a simple plain text of size 100 bytes.
EncryptResult encryptionResult = cryptoClient.encrypt(EncryptionAlgorithm.RSA_OAEP, plaintext);
System.out.printf("Returned ciphertext size is %d bytes with algorithm \"%s\"%n",
    encryptionResult.getCipherText().length, encryptionResult.getAlgorithm());

Descriptografar

Descriptografe o conteúdo criptografado chamando decrypt.

byte[] plaintext = new byte[100];
new SecureRandom(SEED).nextBytes(plaintext);
EncryptResult encryptionResult = cryptoClient.encrypt(EncryptionAlgorithm.RSA_OAEP, plaintext);

//Let's decrypt the encrypted result.
DecryptResult decryptionResult = cryptoClient.decrypt(EncryptionAlgorithm.RSA_OAEP, encryptionResult.getCipherText());
System.out.printf("Returned plaintext size is %d bytes%n", decryptionResult.getPlainText().length);

API assíncrona

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas de serviço assíncronas mais comuns do Azure Key Vault Key, incluindo:

Observação: você deve adicionar System.in.read() ou Thread.sleep() depois que a função chamar no main classe/thread para permitir que funções/operações assíncronas sejam executadas e concluídas antes que o main aplicativo/thread seja encerrado.

Criar uma chave de forma assíncrona

Crie uma chave a ser armazenada no Key Vault do Azure.

  • createKey cria uma nova chave no cofre de chaves. Se uma chave com o mesmo nome já existir, uma nova versão da chave será criada.
keyAsyncClient.createRsaKey(new CreateRsaKeyOptions("CloudRsaKey")
        .setExpiresOn(OffsetDateTime.now().plusYears(1))
        .setKeySize(2048))
    .subscribe(key ->
        System.out.printf("Key created with name \"%s\" and id %s%n", key.getName(), key.getId()));

keyAsyncClient.createEcKey(new CreateEcKeyOptions("CloudEcKey")
        .setExpiresOn(OffsetDateTime.now().plusYears(1)))
    .subscribe(key ->
        System.out.printf("Key created with name \"%s\" and id %s%n", key.getName(), key.getId()));

Recuperar uma chave de forma assíncrona

Recupere uma chave armazenada anteriormente chamando getKey.

keyAsyncClient.getKey("<key-name>")
    .subscribe(key ->
        System.out.printf("Key was returned with name \"%s\" and id %s%n", key.getName(), key.getId()));

Atualizar uma chave existente de forma assíncrona

Atualize uma chave existente chamando updateKeyProperties.

keyAsyncClient.getKey("<key-name>")
    .flatMap(key -> {
        // Update the expiry time of the key.
        key.getProperties().setExpiresOn(OffsetDateTime.now().plusDays(50));
        return keyAsyncClient.updateKeyProperties(key.getProperties());
    }).subscribe(updatedKey ->
        System.out.printf("Key's updated expiry time: %s%n", updatedKey.getProperties().getExpiresOn()));

Excluir uma chave de forma assíncrona

Exclua uma chave existente chamando beginDeleteKey.

keyAsyncClient.beginDeleteKey("<key-name>")
    .subscribe(pollResponse -> {
        System.out.printf("Deletion status: %s%n", pollResponse.getStatus());
        System.out.printf("Deleted key name: %s%n", pollResponse.getValue().getName());
        System.out.printf("Key deletion date: %s%n", pollResponse.getValue().getDeletedOn());
    });

Listar chaves de forma assíncrona

Liste as chaves no Key Vault do Azure chamando listPropertiesOfKeys.

// The List Keys operation returns keys without their value, so for each key returned we call `getKey` to get its value
// as well.
keyAsyncClient.listPropertiesOfKeys()
    .flatMap(keyProperties -> keyAsyncClient.getKey(keyProperties.getName(), keyProperties.getVersion()))
    .subscribe(key ->
        System.out.printf("Received key with name \"%s\" and type \"%s\"", key.getName(), key.getKeyType()));

Criptografar de forma assíncrona

Criptografar texto sem formatação chamando encrypt.

byte[] plaintext = new byte[100];
new SecureRandom(SEED).nextBytes(plaintext);

// Let's encrypt a simple plain text of size 100 bytes.
cryptoAsyncClient.encrypt(EncryptionAlgorithm.RSA_OAEP, plaintext)
    .subscribe(encryptionResult -> System.out.printf("Returned ciphertext size is %d bytes with algorithm \"%s\"%n",
        encryptionResult.getCipherText().length, encryptionResult.getAlgorithm()));

Descriptografar de forma assíncrona

Descriptografe o conteúdo criptografado chamando decrypt.

byte[] plaintext = new byte[100];
new SecureRandom(SEED).nextBytes(plaintext);

// Let's encrypt a simple plain text of size 100 bytes.
cryptoAsyncClient.encrypt(EncryptionAlgorithm.RSA_OAEP, plaintext)
    .flatMap(encryptionResult -> {
        System.out.printf("Returned ciphertext size is %d bytes with algorithm \"%s\"%n",
            encryptionResult.getCipherText().length, encryptionResult.getAlgorithm());
        //Let's decrypt the encrypted response.
        return cryptoAsyncClient.decrypt(EncryptionAlgorithm.RSA_OAEP, encryptionResult.getCipherText());
    }).subscribe(decryptionResult ->
        System.out.printf("Returned plaintext size is %d bytes%n", decryptionResult.getPlainText().length));

Solução de problemas

Consulte nosso guia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Geral

Os principais clientes do Azure Key Vault geram exceções. Por exemplo, se você tentar recuperar uma chave depois que ela for excluída, um 404 erro será retornado, indicando que o recurso não foi encontrado. No snippet a seguir, o erro é tratado normalmente capturando a exceção e exibindo informações adicionais sobre o erro.

try {
    keyClient.getKey("<deleted-key-name>");
} catch (ResourceNotFoundException e) {
    System.out.println(e.getMessage());
}

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 Chata é um JAR do Uber que contém bibliotecas nativas para Linux/macOS/Windows e fornece melhor desempenho em comparação com a implementação de 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

Vários exemplos de biblioteca de clientes Java Key Vault do Azure estão disponíveis para você no repositório GitHub do SDK. Esses exemplos fornecem código de exemplo para cenários adicionais comumente encontrados ao trabalhar com o Azure Key Vault.

Exemplos das próximas etapas

Os exemplos são explicados em detalhes aqui.

Documentação adicional

Para obter uma documentação mais abrangente sobre Key Vault do Azure, consulte a documentação de referência da API.

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