Biblioteca cliente de clave de Azure Key Vault para Java: versión 4.7.1

Artículo
10/25/2023

Azure Key Vault es un servicio en la nube que proporciona almacenamiento seguro de claves para cifrar los datos. Se pueden conservar varias claves y varias versiones de la misma clave en azure Key Vault. Las claves criptográficas de Azure Key Vault se representan como objetos JSON Web Key [JWK].

Azure Key Vault HSM administrado es un servicio en la nube totalmente administrado, de alta disponibilidad, de inquilino único y compatible con estándares que le permite proteger las claves criptográficas para las aplicaciones en la nube mediante HSM validados de nivel 3 de FIPS 140-2.

El cliente de la biblioteca de claves de Azure Key Vault admite claves RSA y claves de curva elíptica (EC), cada una con la compatibilidad correspondiente en los módulos de seguridad de hardware (HSM). Ofrece operaciones para crear, recuperar, actualizar, eliminar, purgar, realizar copias de seguridad, restaurar y enumerar las claves y sus versiones.

Código fuente | Documentación de referencia de API | Documentación del producto | Ejemplos

Introducción

Inclusión del paquete

Inclusión del archivo BOM

Incluya en el azure-sdk-bom proyecto para que dependa de la versión de disponibilidad general (GA) de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte EL ARCHIVO LÉAME BOM del SDK de 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>

y, a continuación, incluya la dependencia directa en la sección dependencias sin la etiqueta de versión, como se muestra a continuación.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-security-keyvault-keys</artifactId>
    </dependency>
</dependencies>

Inclusión de dependencias directas

Si quiere depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-security-keyvault-keys</artifactId>
    <version>4.7.1</version>
</dependency>

Requisitos previos

Un kit de desarrollo de Java (JDK), versión 8 o posterior.
Una suscripción a Azure.
Uno de los siguientes:
- Una Key Vault de Azure existente. Si necesita crear un almacén de claves, puede hacerlo en Azure Portal siguiendo los pasos descritos en este documento. Como alternativa, puede usar la CLI de Azure siguiendo los pasos descritos en este documento.
- Un HSM administrado de Azure Key Vault existente. Si necesita crear un HSM administrado, puede hacerlo mediante la CLI de Azure siguiendo los pasos descritos en este documento.

Autenticar el cliente

Para interactuar con el servicio azure Key Vault, deberá crear una instancia de la KeyClient clase o la CryptographyClient clase , así como una dirección URL del almacén y un objeto de credencial. Los ejemplos que se muestran en este documento usan un objeto de credencial denominado DefaultAzureCredential, que es adecuado para la mayoría de los escenarios, incluidos los entornos de desarrollo y producción locales. Además, se recomienda usar una identidad administrada para la autenticación en entornos de producción.

Puede encontrar más información sobre las distintas formas de autenticación y sus tipos de credenciales correspondientes en la documentación de Azure Identity.

Creación de un cliente de clave

Una vez que realice la configuración de autenticación que mejor le convenga y reemplace su dirección URL-key-vault-url por la dirección URL del almacén de claves o HSM administrado, puede crear :KeyClient

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

NOTA: Para usar un cliente asincrónico, use KeyAsyncClient en lugar de KeyClient y llame a buildAsyncClient().

Creación de un cliente de criptografía

Una vez que realice la DefaultAzureCredential configuración que mejor le convenga y reemplace su dirección URL-key-vault-url por la dirección URL del almacén de claves o HSM administrado, puede crear :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();

NOTA: Para usar un cliente asincrónico, use CryptographyAsyncClient en lugar de CryptographyClient y llame a buildAsyncClient().

Conceptos clave

Clave

Azure Key Vault admite varios tipos de clave (RSA&EC) y algoritmos, y habilita el uso de módulos de seguridad de hardware (HSM) para claves de alto valor. Además del material clave, se pueden especificar los siguientes atributos:

habilitado: especifica si la clave está habilitada y utilizable para las operaciones criptográficas.
not_before: identifica el tiempo antes del cual no se debe usar la clave para las operaciones criptográficas.
expires: identifica la hora de expiración en o después de la cual no se debe usar la clave para las operaciones criptográficas.
created: indica cuándo se creó esta versión de la clave.
actualizado: indica cuándo se actualizó esta versión de la clave.

Cliente clave:

El cliente clave realiza las interacciones con el servicio azure Key Vault para obtener, establecer, actualizar, eliminar y enumerar claves y sus versiones. Los clientes asincrónicos (KeyAsyncClient) y sincrónicos (KeyClient) existen en el SDK, lo que permite seleccionar un cliente en función del caso de uso de una aplicación. Una vez que haya inicializado una clave, puede interactuar con los tipos de recursos principales en Key Vault.

Cliente de criptografía:

El cliente de criptografía realiza las operaciones criptográficas localmente o llama al servicio azure Key Vault en función de la cantidad de información de clave disponible localmente. Admite el cifrado, el descifrado, la firma, la comprobación, el ajuste de claves, la desencapsulación de claves y la recuperación de la clave configurada. Los clientes asincrónicos (CryptographyAsyncClient) y sincrónicos (CryptographyClient) existen en el SDK, lo que permite seleccionar un cliente en función del caso de uso de una aplicación.

Ejemplos

API de sincronización

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes del servicio Azure Key Vault Key, entre las que se incluyen:

Crear una clave
Recuperación de una clave
Actualización de una clave existente
Eliminar una clave
Enumeración de claves
Encrypt
Descifrado

Crear una clave

Cree una clave que se almacenará en azure Key Vault.

createKey crea una nueva clave en el almacén de claves. Si ya existe una clave con el mismo nombre, se crea una nueva versión de la clave.

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());

Recuperación de una clave

Recupere una clave almacenada previamente mediante una llamada a 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());

Actualización de una clave existente

Actualice una clave existente llamando a 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());

Eliminación de una clave

Para eliminar una clave existente, llame a 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();

Enumeración de claves

Enumere las claves en el almacén de claves mediante una llamada a 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());
}

Cifrado

Cifre texto sin formato llamando a 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());

Descifrado

Descifra el contenido cifrado mediante una llamada a 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 asincrónica

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas asincrónicas más comunes del servicio Azure Key Vault Key, entre las que se incluyen:

Creación de una clave de forma asincrónica
Recuperar una clave de forma asincrónica
Actualizar una clave existente de forma asincrónica
Eliminar una clave de forma asincrónica
Enumerar claves de forma asincrónica
Cifrar de forma asincrónica
Descifrar de forma asincrónica

Nota: Debe agregar System.in.read() o Thread.sleep() después de las llamadas de función en la clase o subproceso principal para permitir que las funciones o operaciones asincrónicas se ejecuten y finalicen antes de que se cierre la aplicación o subproceso principal.

Creación de una clave de forma asincrónica

Cree una clave que se almacenará en azure Key Vault.

createKey crea una nueva clave en el almacén de claves. Si ya existe una clave con el mismo nombre, se crea una nueva versión de la clave.

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 una clave de forma asincrónica

Recupere una clave almacenada previamente mediante una llamada a getKey.

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

Actualizar una clave existente de forma asincrónica

Actualice una clave existente llamando a 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()));

Eliminar una clave de forma asincrónica

Para eliminar una clave existente, llame a 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());
    });

Enumerar claves de forma asincrónica

Enumere las claves de Azure Key Vault mediante una llamada a 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()));

Cifrar de forma asincrónica

Cifre texto sin formato llamando a 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()));

Descifrar de forma asincrónica

Descifra el contenido cifrado mediante una llamada a 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));

Solución de problemas

Consulte nuestra guía de solución de problemas para obtener más información sobre cómo diagnosticar varios escenarios de error.

General

Los clientes clave de Azure Key Vault generan excepciones. Por ejemplo, si intenta recuperar una clave después de eliminarse, se devuelve un 404 error, lo que indica que no se encontró el recurso. En el siguiente fragmento, el error se controla correctamente al detectar la excepción y mostrar información adicional sobre el error.

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

Cliente HTTP predeterminado

Todas las bibliotecas cliente usan de forma predeterminada el cliente HTTP de Netty. Al agregar la dependencia anterior, se configurará automáticamente la biblioteca cliente para usar el cliente HTTP de Netty. La configuración o el cambio del cliente HTTP se detalla en la wiki de clientes HTTP.

Biblioteca SSL predeterminada

De forma predeterminada, todas las bibliotecas cliente usan la biblioteca Boring SSL nativa de Tomcat para habilitar el rendimiento de nivel nativo para las operaciones SSL. La biblioteca SSL boring es un ARCHIVO JAR de Uber que contiene bibliotecas nativas para Linux / macOS / Windows, y proporciona un mejor rendimiento en comparación con la implementación SSL predeterminada dentro del JDK. Para obtener más información, incluido cómo reducir el tamaño de las dependencias, consulte la sección optimización del rendimiento de la wiki.

Pasos siguientes

Hay varios ejemplos de biblioteca cliente de Java de Azure Key Vault disponibles en el repositorio de GitHub del SDK. Estos ejemplos proporcionan código de ejemplo para escenarios adicionales que se suelen encontrar al trabajar con Azure Key Vault.

Ejemplos de pasos siguientes

Los ejemplos se explican detalladamente aquí.

Documentación adicional

Para obtener documentación más amplia sobre Azure Key Vault, consulte la documentación de referencia de API.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones

Compartir a través de