次の方法で共有


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

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>

前提条件

クライアントを認証する

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 キー サービス タスクをカバーするいくつかのコード スニペットを示します。

キーの作成

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 宛てに質問またはコメントをお送りください。

インプレッション数