Java 用 Azure Key Vault キークライアントライブラリ - バージョン 4.7.1

[アーティクル]
10/25/2023

Azure Key Vault は、データを暗号化するためのキーのセキュリティで保護されたストレージを提供するクラウドサービスです。複数のキーと同じキーの複数のバージョンを Azure Key Vaultに保持できます。 Azure Key Vaultの暗号化キーは、JSON Web キー [JWK] オブジェクトとして表されます。

Azure Key Vault Managed HSM は、FIPS 140-2 レベル 3 で検証された HSM を使用してクラウドアプリケーションの暗号化キーを保護できるようにする、フルマネージドの高可用性シングルテナント標準準拠クラウドサービスです。

Azure Key Vault キーライブラリクライアントでは、RSA キーと楕円曲線 (EC) キーがサポートされています。それぞれに、ハードウェアセキュリティモジュール (HSM) で対応するサポートがあります。キーとそのバージョンを作成、取得、更新、削除、消去、バックアップ、復元、一覧表示する操作が提供されます。

ソースコード | API リファレンスドキュメント | 製品ドキュメント | サンプル

作業の開始

パッケージを組み込む

BOM ファイルを含める

ライブラリの azure-sdk-bom 一般提供 (GA) バージョンに依存するには、をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

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

次に、次に示すようにバージョンタグを使用せずに、依存関係セクションに直接依存関係を含めます。

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

直接依存関係を含める

BOM に存在しないライブラリの特定のバージョンに依存する場合は、次のように直接依存関係をプロジェクトに追加します。

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

前提条件

Java Development Kit (JDK) バージョン 8 以降。
Azure サブスクリプション。
次のいずれか:
- 既存の Azure Key Vault。キーコンテナーを作成する必要がある場合は、このドキュメントの手順に従って Azure Portal で作成できます。または、このドキュメントの手順に従って Azure CLI を使用することもできます。
- 既存の Azure Key Vault Managed HSM。 Managed HSM を作成する必要がある場合は、このドキュメントの手順に従って Azure CLI を使用して作成できます。

クライアントを認証する

Azure Key Vault サービスと対話するには、クラスまたは CryptographyClient クラスのKeyClientインスタンスと、コンテナーの URL と資格情報オブジェクトを作成する必要があります。このドキュメントに示す例では、という名前 DefaultAzureCredentialの資格情報オブジェクトを使用します。これは、ローカルの開発環境や運用環境など、ほとんどのシナリオに適しています。さらに、運用環境での認証にはマネージド ID を使用することをお勧めします。

さまざまな認証方法と、それに対応する資格情報の種類の詳細については、 Azure Id のドキュメントを参照してください。

キークライアントを作成する

最適な認証設定を実行し、your-key-vault-url をキーコンテナーまたはマネージド HSM の URL に置き換えたら、をKeyClient作成できます。

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

注: 非同期クライアントを使用する場合は、 KeyClient ではなくを使用KeyAsyncClientし、を呼び出しますbuildAsyncClient()。

暗号化クライアントを作成する

最適な設定をDefaultAzureCredential実行し、your-key-vault-url をキーコンテナーまたはマネージド HSM の URL に置き換えたら、を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();

注: 非同期クライアントを使用する場合は、 CryptographyClient ではなくを使用CryptographyAsyncClientし、を呼び出しますbuildAsyncClient()。

主要な概念

キー

Azure Key Vaultでは、複数のキーの種類 (RSA&EC) とアルゴリズムがサポートされており、高価値のキーに対してハードウェアセキュリティモジュール (HSM) を使用できます。キーマテリアルに加えて、次の属性を指定できます。

enabled: キーを有効にし、暗号化操作に使用できるかどうかを指定します。
not_before: 暗号化操作にキーを使用しない時間を識別します。
expires: 暗号化操作にキーを使用してはならない、またはそれ以降の有効期限を識別します。
created: このバージョンのキーがいつ作成されたかを示します。
updated: このバージョンのキーがいつ更新されたかを示します。

キークライアント:

キークライアントは、キーとそのバージョンを取得、設定、更新、削除、一覧表示するために、Azure Key Vault サービスとの対話を実行します。 SDK には非同期 (KeyAsyncClient) および同期 (KeyClient) クライアントが存在し、アプリケーションのユースケースに基づいてクライアントを選択できます。キーを初期化したら、Key Vaultでプライマリリソースの種類を操作できます。

暗号化クライアント:

暗号化クライアントは、暗号化操作をローカルで実行するか、ローカルで使用できるキー情報の量に応じて Azure Key Vault サービスを呼び出します。暗号化、暗号化解除、署名、検証、キーラッピング、キーのラップ解除、構成されたキーの取得がサポートされています。 SDK には非同期 (CryptographyAsyncClient) および同期 (CryptographyClient) クライアントが存在し、アプリケーションのユースケースに基づいてクライアントを選択できます。

例

同期 API

次のセクションでは、次のような最も一般的な Azure Key Vault キーサービスタスクをカバーするいくつかのコードスニペットを示します。

キーを作成します
キーの取得
既存のキーを更新する
キーを削除します
キーのリスト
Encrypt
復号化

キーの作成

Azure Key Vaultに格納するキーを作成します。

createKey は、キーコンテナーに新しいキーを作成します。同じ名前のキーが既に存在する場合は、新しいバージョンのキーが作成されます。

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

キーの取得

を呼び出 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());

既存のキーを更新する

を呼び出 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());

キーの削除

を呼び出 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();

キーのリスト

を呼び出 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してプレーンテキストを暗号化します。

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

復号化

を呼び出 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

次のセクションでは、最も一般的な非同期 Azure Key Vault キーサービスタスクの一部をカバーするいくつかのコードスニペットを示します。

キーを非同期的に作成する
キーを非同期的に取得する
既存のキーを非同期的に更新する
キーを非同期的に削除する
キーを非同期的に一覧表示する
非同期で暗号化する
非同期で復号化する

注: メインアプリケーション/スレッドが終了する前に非同期関数/操作を実行して終了できるように、メインクラス/スレッドで関数呼び出しの後にまたは Thread.sleep() を追加System.in.read()する必要があります。

キーを非同期的に作成する

Azure Key Vaultに格納するキーを作成します。

createKey は、キーコンテナーに新しいキーを作成します。同じ名前のキーが既に存在する場合は、新しいバージョンのキーが作成されます。

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

キーを非同期的に取得する

を呼び出 getKeyして、以前に格納されたキーを取得します。

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

既存のキーを非同期的に更新する

を呼び出 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()));

キーを非同期的に削除する

を呼び出 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());
    });

キーを非同期的に一覧表示する

を呼び出listPropertiesOfKeysして、Azure Key Vault内のキーを一覧表示します。

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

非同期で暗号化する

を呼び出 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()));

非同期で復号化する

を呼び出 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));

トラブルシューティング

さまざまな障害シナリオを診断する方法の詳細については、トラブルシューティングガイドを参照してください。

全般

Azure Key Vault キークライアントでは例外が発生します。たとえば、削除後にキーを取得しようとすると、 404 リソースが見つからなかったというエラーが返されます。次のスニペットでは、例外をキャッチし、エラーに関する追加情報を表示することで、エラーが適切に処理されます。

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

既定の HTTP クライアント

すべてのクライアントライブラリでは、Netty HTTP クライアントが既定で使用されます。前述の依存関係を追加すると、Netty HTTP クライアントを使用するようにクライアントライブラリが自動的に構成されます。 HTTP クライアントの構成と変更については、HTTP クライアントの Wiki で詳しく説明されています。

既定の SSL ライブラリ

すべてのクライアントライブラリは、Tomcat ネイティブの Boring SSL ライブラリを既定で使用して、SSL 操作にネイティブレベルのパフォーマンスを実現しています。ボーリング SSL ライブラリは、Linux/macOS/Windows 用のネイティブライブラリを含む Uber JAR であり、JDK 内の既定の SSL 実装と比較してパフォーマンスが向上します。依存関係のサイズを縮小する方法など、詳細については、Wiki の「パフォーマンスチューニング」セクションを参照してください。

次の手順

いくつかの Azure Key Vault Java クライアントライブラリサンプルは、SDK の GitHub リポジトリで入手できます。これらのサンプルでは、Azure Key Vaultの操作中に一般的に発生するその他のシナリオのコード例を示します。

次の手順のサンプル

サンプルについては、こちらを参照してください。

その他のドキュメント

Azure Key Vaultの詳細なドキュメントについては、API リファレンスドキュメントを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

次の方法で共有

Java 用 Azure Key Vault キー クライアント ライブラリ - バージョン 4.7.1