クラスKDF

java.lang.Object
javax.crypto.KDF
public final class KDF extends Object
KDFは、JavaプラットフォームのプレビューAPIです。
プレビュー機能が有効な場合のみ、プログラムでKDFを使用できます。
プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
このクラスは、キー導出ファンクション(KDF)の機能を提供します。これは、入力キーイング・マテリアル(IKM)および他のデータ(optionally)から追加キーを導出するための暗号化アルゴリズムです。

KDF オブジェクトは、getInstanceメソッド・ファミリを使用してインスタンス化されます。

クラスには、deriveKeyおよびderiveDataという2つの導出メソッドがあります。 deriveKeyメソッドは、アルゴリズム名を受け入れ、指定されたアルゴリズムでSecretKeyオブジェクトを返します。 deriveDataメソッドは、RAWデータのバイト配列を返します。

APIの使用方法の例: 

    KDF kdfHkdf = KDF.getInstance("HKDF-SHA256");

    AlgorithmParameterSpec derivationSpec =
             HKDFParameterSpec.ofExtract()
                              .addIKM(ikm)
                              .addSalt(salt).thenExpand(info, 32);

    SecretKey sKey = kdfHkdf.deriveKey("AES", derivationSpec);

並行アクセス

実装によって特に文書化されていないかぎり、このクラスで定義されたメソッドはスレッド・セーフではありません。 単一のオブジェクトに並行アクセスする必要のある複数スレッドは、スレッド間で同期をとり、必要に応じてロックする必要があります。 複数のスレッドがそれぞれ個別のオブジェクトを処理する場合、それらのスレッドは同期する必要はありません。

遅延プロバイダ選択

getInstanceメソッドの1つをコールするときにプロバイダを指定しない場合、deriveKeyまたはderiveDataメソッドがコールされるまで、実装によってプロバイダの選択が遅延されます。 これは「プロバイダ選択の遅延」と呼ばれます。 これが行われる主な理由は、選択したプロバイダが、それらのメソッドに渡されるキー・マテリアルを確実に処理できるようにするためです - たとえば、キー・マテリアルは、特定のKDFプロバイダのみが使用できるハードウェア・デバイス上に存在する場合があります。 getInstanceメソッドは、アルゴリズムを実装し、オプションのパラメータをサポートする登録済セキュリティ・プロバイダが少なくとも1つ存在するかぎり、KDFオブジェクトを返します。 遅延プロバイダ選択プロセスは、最も優先されるProviderから開始して、登録済セキュリティ・プロバイダのリストをトラバースします。 指定されたアルゴリズム、オプション・パラメータおよびキー・マテリアルをサポートする最初のプロバイダが選択されます。

deriveKeyまたはderiveDataメソッドの前にgetProviderNameまたはgetParametersメソッドをコールすると、KDFアルゴリズムとオプションのKDFParametersをサポートする最初のプロバイダが選択されます。 このプロバイダは、deriveKeyまたはderiveDataメソッドに渡されるキー・マテリアルをサポートしていない場合があります。 したがって、キー導出操作の後まで、getProviderNameまたはgetParametersメソッドをコールしないことをお薦めします。 一度プロバイダを選択すると、そのプロバイダは変更できません。

導入されたバージョン:
24
関連項目:

  • メソッドの詳細

    • getAlgorithm

      public String getAlgorithm()
      このKDFオブジェクトのアルゴリズム名を返します。
      戻り値:
      このKDFオブジェクトのアルゴリズム名

    • getProviderName

      public String getProviderName()
      プロバイダの名前を返します。
      戻り値:
      プロバイダの名前
      関連項目:

    • getParameters

      public KDFParametersPREVIEW getParameters()
      このKDFオブジェクトで使用されるKDFParametersを返します。

      返されるパラメータは、このKDFオブジェクトの初期化に使用したものと同じか、基礎となるKDFアルゴリズムで使用される追加のデフォルトまたはランダム・パラメータ値を含む場合があります。 必須パラメータが指定されておらず、KDFオブジェクトで生成できる場合は、生成されたパラメータが返されます。それ以外の場合は、nullが返されます。

      戻り値:
      このKDFオブジェクトまたはnullで使用されるパラメータ
      関連項目:

    • getInstance

      public static KDFPREVIEW getInstance(String algorithm) throws NoSuchAlgorithmException
      指定されたアルゴリズムを実装するKDFオブジェクトを返します。
      実装上のノート:
      JDKリファレンス実装では、さらにjdk.security.provider.preferred Securityプロパティを使用して、指定したアルゴリズムの優先プロバイダ順序を決定します。 これは、Security.getProviders()によって返されるプロバイダの順序とは異なる場合があります。
      パラメータ:
      algorithm - 使用するキー導出アルゴリズム。 標準のKDFアルゴリズム名の詳細は、「Javaセキュリティ標準アルゴリズム名仕様」のKDFセクションを参照してください。
      戻り値:
      KDFオブジェクト
      スロー:
      NoSuchAlgorithmException - Providerが、指定されたアルゴリズムのKDF実装をサポートしていない場合
      NullPointerException - algorithmがnullである場合
      関連項目:

    • getInstance

      public static KDFPREVIEW getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException
      指定されたセキュリティ・プロバイダから指定されたアルゴリズムを実装するKDFオブジェクトを返します。 指定したプロバイダは、セキュリティ・プロバイダ・リストに登録する必要があります。
      パラメータ:
      algorithm - 使用するキー導出アルゴリズム。 標準のKDFアルゴリズム名の詳細は、「Javaセキュリティ標準アルゴリズム名仕様」のKDFセクションを参照してください。
      provider - このキー導出に使用するプロバイダ
      戻り値:
      KDFオブジェクト
      スロー:
      NoSuchAlgorithmException - 指定されたプロバイダが、指定されたKDFアルゴリズムをサポートしていない場合
      NoSuchProviderException - 指定されたプロバイダがセキュリティ・プロバイダ・リストに登録されていない場合
      NullPointerException - algorithmまたはproviderがnullの場合

    • getInstance

      public static KDFPREVIEW getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException
      指定されたセキュリティ・プロバイダから指定されたアルゴリズムを実装するKDFオブジェクトを返します。
      パラメータ:
      algorithm - 使用するキー導出アルゴリズム。 標準のKDFアルゴリズム名の詳細は、「Javaセキュリティ標準アルゴリズム名仕様」のKDFセクションを参照してください。
      provider - このキー導出に使用するプロバイダ
      戻り値:
      KDFオブジェクト
      スロー:
      NoSuchAlgorithmException - 指定されたプロバイダが、指定されたKDFアルゴリズムをサポートしていない場合
      NullPointerException - algorithmまたはproviderがnullの場合

    • getInstance

      public static KDFPREVIEW getInstance(String algorithm, KDFParametersPREVIEW kdfParameters) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
      指定されたアルゴリズムを実装し、指定されたパラメータで初期化されるKDFオブジェクトを返します。
      実装上のノート:
      JDKリファレンス実装では、さらにjdk.security.provider.preferred Securityプロパティを使用して、指定したアルゴリズムの優先プロバイダ順序を決定します。 これは、Security.getProviders()によって返されるプロバイダの順序とは異なる場合があります。
      パラメータ:
      algorithm - 使用するキー導出アルゴリズム。 標準のKDFアルゴリズム名の詳細は、「Javaセキュリティ標準アルゴリズム名仕様」のKDFセクションを参照してください。
      kdfParameters - 導出アルゴリズムの構成に使用されるKDFParameters、またはパラメータが指定されていない場合はnull
      戻り値:
      KDFオブジェクト
      スロー:
      NoSuchAlgorithmException - Providerが、指定されたアルゴリズムのKDF実装をサポートしていない場合
      InvalidAlgorithmParameterException - 少なくとも1つのProviderが、指定されたアルゴリズムに対してKDF実装をサポートしているが、いずれも指定されたパラメータをサポートしていない場合
      NullPointerException - algorithmがnullである場合
      関連項目:

    • getInstance

      public static KDFPREVIEW getInstance(String algorithm, KDFParametersPREVIEW kdfParameters, String provider) throws NoSuchAlgorithmException, NoSuchProviderException, InvalidAlgorithmParameterException
      指定されたプロバイダから指定されたアルゴリズムを実装し、指定されたパラメータで初期化されるKDFオブジェクトを返します。 指定したプロバイダは、セキュリティ・プロバイダ・リストに登録する必要があります。
      パラメータ:
      algorithm - 使用するキー導出アルゴリズム。 標準のKDFアルゴリズム名の詳細は、「Javaセキュリティ標準アルゴリズム名仕様」のKDFセクションを参照してください。
      kdfParameters - 導出アルゴリズムの構成に使用されるKDFParameters、またはパラメータが指定されていない場合はnull
      provider - このキー導出に使用するプロバイダ
      戻り値:
      KDFオブジェクト
      スロー:
      NoSuchAlgorithmException - 指定されたプロバイダが、指定されたKDFアルゴリズムをサポートしていない場合
      NoSuchProviderException - 指定されたプロバイダがセキュリティ・プロバイダ・リストに登録されていない場合
      InvalidAlgorithmParameterException - 指定されたプロバイダが、指定されたKDFアルゴリズムをサポートしているが、指定されたパラメータをサポートしていない場合
      NullPointerException - algorithmまたはproviderがnullの場合

    • getInstance

      public static KDFPREVIEW getInstance(String algorithm, KDFParametersPREVIEW kdfParameters, Provider provider) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
      指定されたプロバイダから指定されたアルゴリズムを実装し、指定されたパラメータで初期化されるKDFオブジェクトを返します。
      パラメータ:
      algorithm - 使用するキー導出アルゴリズム。 標準のKDFアルゴリズム名の詳細は、「Javaセキュリティ標準アルゴリズム名仕様」のKDFセクションを参照してください。
      kdfParameters - 導出アルゴリズムの構成に使用されるKDFParameters、またはパラメータが指定されていない場合はnull
      provider - このキー導出に使用するプロバイダ
      戻り値:
      KDFオブジェクト
      スロー:
      NoSuchAlgorithmException - 指定されたプロバイダが、指定されたKDFアルゴリズムをサポートしていない場合
      InvalidAlgorithmParameterException - 指定されたプロバイダが、指定されたKDFアルゴリズムをサポートしているが、指定されたパラメータをサポートしていない場合
      NullPointerException - algorithmまたはproviderがnullの場合

    • deriveKey

      public SecretKey deriveKey(String alg, AlgorithmParameterSpec derivationSpec) throws InvalidAlgorithmParameterException, NoSuchAlgorithmException
      SecretKeyオブジェクトとして返されるキーを導出します。
      パラメータ:
      alg - 結果のSecretKeyオブジェクトのアルゴリズム
      derivationSpec - 導出関数への入力を記述するオブジェクト
      戻り値:
      導出キー
      スロー:
      InvalidAlgorithmParameterException - derivationSpecに含まれる情報が無効な場合、またはalgとderivationSpecの組合せが無効な場合
      NoSuchAlgorithmException - algが空または無効の場合
      NullPointerException - algまたはderivationSpecがnullの場合
      関連項目:

    • deriveData

      public byte[] deriveData(AlgorithmParameterSpec derivationSpec) throws InvalidAlgorithmParameterException
      キーを導出して、RAWデータをバイト配列として返します。
      パラメータ:
      derivationSpec - 導出関数への入力を記述するオブジェクト
      戻り値:
      rawバイト内の派生キー
      スロー:
      InvalidAlgorithmParameterException - derivationSpecに含まれる情報が無効な場合
      UnsupportedOperationException - 導出されたキーイング材料が抽出可能でない場合
      NullPointerException - derivationSpecがnullの場合
      関連項目: