Bibliothèque de client Azure Key Vault Key pour Java - version 4.7.1

  • Article

Azure Key Vault est un service cloud qui fournit un stockage sécurisé des clés pour le chiffrement de vos données. Plusieurs clés, et plusieurs versions de la même clé, peuvent être conservées dans le Key Vault Azure. Les clés de chiffrement dans Azure Key Vault sont représentées en tant qu’objets de clé web JSON [JWK].

Azure Key Vault HSM managé est un service cloud entièrement managé, hautement disponible, monolocataire et conforme aux normes qui vous permet de protéger les clés de chiffrement pour vos applications cloud à l’aide de HSM validés FIPS 140-2 De niveau 3.

Le client de bibliothèque de clés Azure Key Vault prend en charge les clés RSA et les clés de courbe elliptique (EC), chacune avec la prise en charge correspondante dans les modules de sécurité matériels (HSM). Il offre des opérations pour créer, récupérer, mettre à jour, supprimer, vider, sauvegarder, restaurer et répertorier les clés et leurs versions.

Code source | Documentation de référence de l’API | Documentation du produit | Exemples

Prise en main

Inclure le package

Inclure le fichier de nomenclature

Incluez le azure-sdk-bom dans votre projet pour qu’il soit dépendant de la version en disponibilité générale de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez le README BOM du KIT DE DÉVELOPPEMENT LOGICIEL 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>

puis incluez la dépendance directe dans la section dépendances sans la balise de version, comme indiqué ci-dessous.

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

Inclure une dépendance directe

Si vous souhaitez dépendre d’une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.

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

Prérequis

Authentifier le client

Pour interagir avec le service Azure Key Vault, vous devez créer un instance de la classe ou de la KeyClientCryptographyClient classe, ainsi qu’une URL de coffre et un objet d’informations d’identification. Les exemples présentés dans ce document utilisent un objet d’informations d’identification nommé DefaultAzureCredential, qui convient à la plupart des scénarios, notamment aux environnements de développement et de production locaux. En outre, nous vous recommandons d’utiliser une identité managée pour l’authentification dans les environnements de production.

Vous trouverez plus d’informations sur les différentes méthodes d’authentification et leurs types d’informations d’identification correspondants dans la documentation Azure Identity.

Créer un client de clé

Une fois que vous avez effectué la configuration d’authentification qui vous convient le mieux et que vous avez remplacé your-key-vault-url par l’URL de votre coffre de clés ou HSM managé, vous pouvez créer le KeyClient:

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

REMARQUE : Pour utiliser un client asynchrone, utilisez KeyAsyncClient au lieu de KeyClient et appelez buildAsyncClient().

Créer un client de chiffrement

Une fois que vous avez effectué la DefaultAzureCredential configuration qui vous convient le mieux et que vous avez remplacé your-key-vault-url par l’URL de votre coffre de clés ou HSM managé, vous pouvez créer le 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();

REMARQUE : Pour utiliser un client asynchrone, utilisez CryptographyAsyncClient au lieu de CryptographyClient et appelez buildAsyncClient().

Concepts clés

Clé :

Azure Key Vault prend en charge plusieurs types de clés (RSA&EC) et algorithmes, et permet l’utilisation de modules de sécurité matériels (HSM) pour les clés à valeur élevée. En plus de la clé, les attributs suivants peuvent être spécifiés :

  • enabled : spécifie si la clé est activée et utilisable pour les opérations de chiffrement.
  • not_before : identifie l’heure avant laquelle la clé ne doit pas être utilisée pour les opérations de chiffrement.
  • expire : identifie le délai d’expiration sur ou après lequel la clé NE DOIT PAS être utilisée pour les opérations de chiffrement.
  • created : indique quand cette version de la clé a été créée.
  • updated : indique quand cette version de la clé a été mise à jour.

Client clé :

Le client de clé effectue les interactions avec le service Azure Key Vault pour obtenir, définir, mettre à jour, supprimer et répertorier les clés et ses versions. Les clients asynchrones (KeyAsyncClient) et synchrones (KeyClient) existent dans le Kit de développement logiciel (SDK) ce qui permet de sélectionner un client en fonction du cas d’usage d’une application. Une fois que vous avez initialisé une clé, vous pouvez interagir avec les types de ressources primaires dans Key Vault.

Client de chiffrement :

Le client de chiffrement effectue les opérations de chiffrement localement ou appelle le service Azure Key Vault en fonction de la quantité d’informations de clé disponibles localement. Il prend en charge le chiffrement, le déchiffrement, la signature, la vérification, l’habillage de clé, le désencapsulation de clé et la récupération de la clé configurée. Les clients asynchrones (CryptographyAsyncClient) et synchrones (CryptographyClient) existent dans le Kit de développement logiciel (SDK) ce qui permet de sélectionner un client en fonction du cas d’usage d’une application.

Exemples

API synchrone

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches de service Azure Key Vault Key les plus courantes, notamment :

Créer une clé

Créez une clé à stocker dans le Key Vault Azure.

  • createKey crée une clé dans le coffre de clés. Si une clé portant le même nom existe déjà, une nouvelle version de la clé est créée.
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());

Récupérer une clé

Récupérez une clé précédemment stockée en appelant 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());

Mettre à jour une clé existante

Mettez à jour une clé existante en appelant 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());

Supprimer une clé

Supprimez une clé existante en appelant 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();

List keys (Afficher la liste des clés)

Répertoriez les clés dans le coffre de clés en appelant 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 (Chiffrer)

Chiffrez du texte brut en appelant 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());

Déchiffrer

Déchiffrez le contenu chiffré en appelant 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 asynchrone

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches de service azure Key Vault key asynchrones les plus courantes, notamment :

Remarque : Vous devez ajouter System.in.read() ou Thread.sleep() après les appels de fonction dans le main classe/thread pour permettre aux fonctions/opérations asynchrones de s’exécuter et de se terminer avant la fermeture de l’application/du thread main.

Créer une clé de manière asynchrone

Créez une clé à stocker dans le Key Vault Azure.

  • createKey crée une clé dans le coffre de clés. Si une clé portant le même nom existe déjà, une nouvelle version de la clé est créée.
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()));

Récupérer une clé de manière asynchrone

Récupérez une clé précédemment stockée en appelant getKey.

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

Mettre à jour une clé existante de façon asynchrone

Mettez à jour une clé existante en appelant 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()));

Supprimer une clé de façon asynchrone

Supprimez une clé existante en appelant 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());
    });

Répertorier les clés de façon asynchrone

Répertoriez les clés dans le Key Vault Azure en appelant 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()));

Chiffrer de manière asynchrone

Chiffrez du texte brut en appelant 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()));

Déchiffrer de manière asynchrone

Déchiffrez le contenu chiffré en appelant 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));

Dépannage

Consultez notre guide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Général

Les clients Azure Key Vault Key lèvent des exceptions. Par exemple, si vous essayez de récupérer une clé après sa suppression, une 404 erreur est retournée, indiquant que la ressource est introuvable. Dans l’extrait suivant, l’erreur est prise en charge correctement via l’interception de l’exception et l’affichage d’informations supplémentaires sur l’erreur en question.

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

Client HTTP par défaut

Toutes les bibliothèques de client utilisent par défaut le client HTTP Netty. L’ajout de la dépendance ci-dessus configure automatiquement la bibliothèque de client pour utiliser le client HTTP Netty. La configuration ou la modification du client HTTP sont détaillées dans le wiki pour clients HTTP.

Bibliothèque SSL par défaut

Toutes les bibliothèques de client utilisent par défaut la bibliothèque BoringSSL Tomcat native pour permettre des performances de niveau natif pour les opérations SSL. La bibliothèque SSL ennuyeuse est un fichier JAR Uber contenant des bibliothèques natives pour Linux / macOS / Windows, et offre de meilleures performances par rapport à l’implémentation SSL par défaut dans le JDK. Pour plus d’informations, notamment sur la réduction de la taille des dépendances, consultez la section du wiki consacrée à l’optimisation des performances.

Étapes suivantes

Plusieurs exemples de bibliothèque de client Azure Key Vault Java sont disponibles dans le référentiel GitHub du SDK. Ces exemples fournissent un exemple de code pour des scénarios supplémentaires couramment rencontrés lors de l’utilisation d’Azure Key Vault.

Exemples d’étapes suivantes

Les exemples sont expliqués en détail ici.

Documentation complémentaire

Pour obtenir une documentation plus complète sur Azure Key Vault, consultez la documentation de référence sur les API.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions