Azure Key Vault Key-Clientbibliothek für Java – Version 4.7.1

Artikel
10/21/2023

Azure Key Vault ist ein Clouddienst, der eine sichere Speicherung von Schlüsseln zum Verschlüsseln Ihrer Daten ermöglicht. Mehrere Schlüssel und mehrere Versionen desselben Schlüssels können im Azure-Key Vault beibehalten werden. Kryptografische Schlüssel in Azure Key Vault werden als JSON-Webschlüssel [JWK]-Objekte dargestellt.

Azure Key Vault Managed HSM ist ein vollständig verwalteter, hochverfügbarer, standardkonformer Clouddienst, mit dem Sie kryptografische Schlüssel für Ihre Cloudanwendungen mithilfe von FIPS 140-2 Level 3 validierten HSMs schützen können.

Der Azure Key Vault-Schlüsselbibliotheksclient unterstützt RSA-Schlüssel und EC-Schlüssel (Elliptic Curve), die jeweils in Hardwaresicherheitsmodulen (HSM) unterstützt werden. Es bietet Vorgänge zum Erstellen, Abrufen, Aktualisieren, Löschen, Löschen, Sichern, Wiederherstellen und Auflisten der Schlüssel und ihrer Versionen.

Quellcode | API-Referenzdokumentation | Produktdokumentation | Beispiele

Erste Schritte

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie das azure-sdk-bom in Ihr Projekt ein, um die Abhängigkeit von der Allgemeinverfügbarkeitsversion der Bibliothek zu übernehmen. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur Stückliste finden Sie in der AZURE SDK-BOM-INFODATEI.

<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>

und fügen Sie dann die direkte Abhängigkeit in den Abschnitt abhängigkeiten ohne das Versionstag ein, wie unten gezeigt.

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

Direkte Abhängigkeiten einfügen

Wenn Sie abhängigkeiten von einer bestimmten Version der Bibliothek übernehmen möchten, die in der Stückliste nicht vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

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

Voraussetzungen

Java Development Kit (JDK), Version 8 oder höher.
Ein Azure-Abonnement.
Einer der folgenden:
- Eine vorhandene Azure Key Vault. Wenn Sie einen Schlüsseltresor erstellen müssen, können Sie dies im Azure-Portal tun, indem Sie die Schritte in diesem Dokument ausführen. Alternativ können Sie die Azure CLI verwenden, indem Sie die Schritte in diesem Dokument ausführen.
- Ein vorhandenes Azure Key Vault Managed HSM. Wenn Sie ein verwaltetes HSM erstellen müssen, können Sie dies mithilfe der Azure CLI tun, indem Sie die Schritte in diesem Dokument ausführen.

Authentifizieren des Clients

Um mit dem Azure Key Vault-Dienst zu interagieren, müssen Sie eine instance der KeyClient Klasse oder der CryptographyClient Klasse sowie eine Tresor-URL und ein Anmeldeinformationsobjekt erstellen. Die in diesem Dokument gezeigten Beispiele verwenden ein Anmeldeinformationsobjekt namens DefaultAzureCredential, das für die meisten Szenarien geeignet ist, einschließlich lokaler Entwicklungs- und Produktionsumgebungen. Darüber hinaus wird die Verwendung einer verwalteten Identität für die Authentifizierung in Produktionsumgebungen empfohlen.

Weitere Informationen zu verschiedenen Authentifizierungsmethoden und den entsprechenden Anmeldeinformationstypen finden Sie in der Dokumentation zu Azure Identity.

Erstellen eines Schlüsselclients

Nachdem Sie die für Sie am besten geeignete Authentifizierungs-Einrichtung durchgeführt und Ihre-key-vault-URL durch die URL für Ihren Schlüsseltresor oder das verwaltete HSM ersetzt haben, können Sie folgendes KeyClienterstellen:

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

HINWEIS: Verwenden Sie KeyAsyncClient für die Verwendung eines asynchronen Clients anstelle von KeyClient und aufrufen buildAsyncClient().

Erstellen eines Kryptografieclients

Nachdem Sie die DefaultAzureCredential für Sie am besten geeignete Einrichtung durchgeführt und Your-key-vault-url durch die URL für Ihren Schlüsseltresor oder das verwaltete HSM ersetzt haben, können Sie folgendes CryptographyClienterstellen:

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

HINWEIS: Verwenden Sie CryptographyAsyncClient für die Verwendung eines asynchronen Clients anstelle von CryptographyClient und aufrufen buildAsyncClient().

Wichtige Begriffe

Schlüssel

Azure Key Vault unterstützt mehrere Schlüsseltypen (RSA&EC) und Algorithmen und ermöglicht die Verwendung von Hardwaresicherheitsmodulen (HSM) für hochwertige Schlüssel. Zusätzlich zum Schlüsselmaterial können die folgenden Attribute angegeben werden:

enabled: Gibt an, ob der Schlüssel aktiviert und für kryptografische Vorgänge verwendet werden kann.
not_before: Gibt die Zeit an, vor der der Schlüssel nicht für kryptografische Vorgänge verwendet werden darf.
läuft ab: Gibt die Ablaufzeit an oder an, nach der der Schlüssel NICHT für kryptografische Vorgänge verwendet werden DARF.
created: Gibt an, wann diese Version des Schlüssels erstellt wurde.
aktualisiert: Gibt an, wann diese Version des Schlüssels aktualisiert wurde.

Schlüsselclient:

Der Schlüsselclient führt die Interaktionen mit dem Azure Key Vault-Dienst zum Abrufen, Festlegen, Aktualisieren, Löschen und Auflisten von Schlüsseln und zugehörigen Versionen aus. Im SDK sind asynchrone (KeyAsyncClient) und synchrone (KeyClient) Clients vorhanden, die die Auswahl eines Clients basierend auf dem Anwendungsfall einer Anwendung ermöglichen. Nachdem Sie einen Schlüssel initialisiert haben, können Sie mit den primären Ressourcentypen in Key Vault interagieren.

Kryptografieclient:

Der Kryptografieclient führt die kryptografischen Vorgänge lokal aus oder ruft den Azure Key Vault-Dienst auf, je nachdem, wie viele Schlüsselinformationen lokal verfügbar sind. Es unterstützt das Verschlüsseln, Entschlüsseln, Signieren, Überprüfen, Schlüsselumbruch, Schlüsselentpacken und Abrufen des konfigurierten Schlüssels. Im SDK sind asynchrone (CryptographyAsyncClient) und synchrone (CryptographyClient) Clients vorhanden, die die Auswahl eines Clients basierend auf dem Anwendungsfall einer Anwendung ermöglichen.

Beispiele

Synchronisierungs-API

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der häufigsten Azure Key Vault Key-Dienstaufgaben behandeln, einschließlich:

Erstellen eines Schlüssels
Abrufen eines Schlüssels
Aktualisieren eines vorhandenen Schlüssels
Löschen eines Schlüssels
Auflisten von Schlüsseln
Encrypt
Entschlüsseln

Erstellen eines Schlüssels

Erstellen Sie einen Schlüssel, der im Azure-Key Vault gespeichert werden soll.

createKey erstellt einen neuen Schlüssel im Schlüsseltresor. Wenn bereits ein Schlüssel mit demselben Namen vorhanden ist, wird eine neue Version des Schlüssels erstellt.

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

Abrufen eines Schlüssels

Rufen Sie einen zuvor gespeicherten Schlüssel ab, indem Sie aufrufen 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());

Aktualisieren eines vorhandenen Schlüssels

Aktualisieren Sie einen vorhandenen Schlüssel, indem Sie aufrufen 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());

Löschen eines Schlüssels

Löschen Sie einen vorhandenen Schlüssel, indem Sie aufrufen 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();

Auflisten von Schlüsseln

Listen Sie die Schlüssel im Schlüsseltresor auf, indem Sie aufrufen 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());
}

Verschlüsseln

Verschlüsseln Sie Nur-Text, indem Sie aufrufen 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());

Entschlüsseln

Entschlüsseln Sie verschlüsselte Inhalte, indem Sie aufrufen 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);

Asynchrone API

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der häufigsten asynchronen Azure Key Vault Key-Dienstaufgaben behandeln, einschließlich:

asynchrones Erstellen eines Schlüssels
asynchrones Abrufen eines Schlüssels
Asynchrones Aktualisieren eines vorhandenen Schlüssels
asynchrones Löschen eines Schlüssels
Asynchrones Auflisten von Schlüsseln
Asynchron verschlüsseln
asynchrones Entschlüsseln

Hinweis: Sie sollten oder nach den Funktionsaufrufen im Standard-Klasse/Thread hinzufügen System.in.read()Thread.sleep(), damit asynchrone Funktionen/Vorgänge ausgeführt und abgeschlossen werden können, bevor die Standard Anwendung/Thread beendet wird.

asynchrones Erstellen eines Schlüssels

Erstellen Sie einen Schlüssel, der im Azure-Key Vault gespeichert werden soll.

createKey erstellt einen neuen Schlüssel im Schlüsseltresor. Wenn bereits ein Schlüssel mit demselben Namen vorhanden ist, wird eine neue Version des Schlüssels erstellt.

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

asynchrones Abrufen eines Schlüssels

Rufen Sie einen zuvor gespeicherten Schlüssel ab, indem Sie aufrufen getKey.

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

Asynchrones Aktualisieren eines vorhandenen Schlüssels

Aktualisieren Sie einen vorhandenen Schlüssel, indem Sie aufrufen 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()));

asynchrones Löschen eines Schlüssels

Löschen Sie einen vorhandenen Schlüssel, indem Sie aufrufen 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());
    });

Asynchrones Auflisten von Schlüsseln

Listen Sie die Schlüssel im Azure-Key Vault auf, indem Sie aufrufenlistPropertiesOfKeys.

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

Asynchron verschlüsseln

Verschlüsseln Sie Nur-Text, indem Sie aufrufen 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()));

asynchrones Entschlüsseln

Entschlüsseln Sie verschlüsselte Inhalte, indem Sie aufrufen 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));

Problembehandlung

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Leitfaden zur Problembehandlung .

Allgemein

Azure Key Vault Key-Clients lösen Ausnahmen aus. Wenn Sie beispielsweise versuchen, nach dem Löschen einen Schlüssel abzurufen, wird ein 404 Fehler zurückgegeben, der angibt, dass die Ressource nicht gefunden wurde. Im folgenden Codeausschnitt wird der Fehler ordnungsgemäß behandelt, indem die Ausnahme abgefangen wird und zusätzliche Fehlerinformationen angezeigt werden.

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

HTTP-Standardclient

Alle Clientbibliotheken verwenden standardmäßig den Netty-HTTP-Client. Durch Hinzufügen der obigen Abhängigkeit wird die Clientbibliothek automatisch für die Verwendung des Netty-HTTP-Clients konfiguriert. Das Konfigurieren oder Ändern des HTTP-Clients wird detailliert im Wiki zu HTTP-Clients beschrieben.

SSL-Standardbibliothek

Alle Clientbibliotheken verwenden standardmäßig die Tomcat-native Boring-SSL-Bibliothek, um die Leistung auf nativer Ebene für SSL-Vorgänge zu ermöglichen. Die Boring SSL-Bibliothek ist eine Uber JAR,die native Bibliotheken für Linux/macOS/Windows enthält und eine bessere Leistung im Vergleich zur Standard-SSL-Implementierung innerhalb des JDK bietet. Weitere Informationen, einschließlich zur Reduzierung der Abhängigkeitsgröße, finden Sie im Abschnitt Leistungsoptimierung des Wikis.

Nächste Schritte

Mehrere Beispiele für die Azure Key Vault Java-Clientbibliothek stehen Ihnen im GitHub-Repository des SDK zur Verfügung. Diese Beispiele bieten Beispielcode für zusätzliche Szenarien, die häufig bei der Arbeit mit Azure Key Vault auftreten.

Beispiele für die nächsten Schritte

Die Beispiele werden hier ausführlich erläutert.

Zusätzliche Dokumentation

Eine ausführlichere Dokumentation zu Azure Key Vault finden Sie in der API-Referenzdokumentation.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe

Freigeben über