クラスKeyAgreement

java.lang.Object
javax.crypto.KeyAgreement
public class KeyAgreement extends Object
このクラスは、キーの合意プロトコル、つまりキーの交換プロトコルの機能を提供します。

共有の秘密の確立に関係するキーは、キー・ジェネレータのいずれか(KeyPairGeneratorまたはKeyGenerator)かKeyFactoryによって、またはキー協定プロトコルの中間フェーズの結果として作成されます。

キー交換の対応関係ごとに、doPhaseを呼び出す必要があります。 たとえば、キー交換の相手が1つの場合は、lastPhaseフラグをtrueに設定してdoPhaseを1回呼び出す必要があります。 キー交換の相手が2つの場合は、最初はlastPhaseフラグをfalseに設定し、2回目はtrueに設定して、doPhaseを2回呼び出す必要があります。 キー交換の相手の数は任意です。 ただし、2つ以上のパーティを持つキー交換のサポートは、実装固有であるか、標準キー契約アルゴリズムで指定されています。

Javaプラットフォームの実装は、すべて次の標準のKeyAgreementアルゴリズムをサポートする必要があります。

  • DiffieHellman
このアルゴリズムは、Javaセキュリティ標準アルゴリズム名仕様の「KeyAgreementセクション」で説明されています。 サポートされているその他のアルゴリズムについては、実装のリリース・ドキュメントを参照してください。

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

  • コンストラクタのサマリー

    コンストラクタ
    修飾子
    コンストラクタ
    説明
    protected
    KeyAgreement(KeyAgreementSpi keyAgreeSpi, Provider provider, String algorithm)
    KeyAgreementオブジェクトを作成します。

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    final Key
    doPhase(Key key, boolean lastPhase)
    このキー合意に関係する相手のだれかから受け取った、指定されたキーを使用してこのキー合意の次の段階を実行します。
    final byte[]
    generateSecret()
    共有の秘密情報を生成して新しいバッファ内に返します。
    final int
    generateSecret(byte[] sharedSecret, int offset)
    共有の秘密情報を生成して、offsetから始まるsharedSecretバッファ内に格納します。
    final SecretKey
    generateSecret(String algorithm)
    共有の秘密情報を作成して、それを指定されたアルゴリズムのSecretKeyオブジェクトとして返します。
    final String
    getAlgorithm()
    このKeyAgreementオブジェクトのアルゴリズム名を返します。
    static final KeyAgreement
    getInstance(String algorithm)
    指定したキー合意アルゴリズムを実装するKeyAgreementオブジェクトを返します。
    static final KeyAgreement
    getInstance(String algorithm, String provider)
    指定したキー合意アルゴリズムを実装するKeyAgreementオブジェクトを返します。
    static final KeyAgreement
    getInstance(String algorithm, Provider provider)
    指定したキー合意アルゴリズムを実装するKeyAgreementオブジェクトを返します。
    final Provider
    getProvider()
    このKeyAgreementオブジェクトのプロバイダを返します。
    final void
    init(Key key)
    指定されたキーでこのキー合意を初期化します。これには、このキー合意に必要なすべてのアルゴリズム・パラメータを含める必要があります。
    final void
    init(Key key, SecureRandom random)
    指定されたキーと乱数発生の元でこのキー合意を初期化します。
    final void
    init(Key key, AlgorithmParameterSpec params)
    指定されたキーとアルゴリズム・パラメータのセットを使用してこのキー合意を初期化します。
    final void
    init(Key key, AlgorithmParameterSpec params, SecureRandom random)
    指定されたキー、アルゴリズム・パラメータのセット、および乱数発生の元を使用してこのキー合意を初期化します。

    クラスjava.lang.Objectで宣言されたメソッド

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • コンストラクタの詳細

    • KeyAgreement

      protected KeyAgreement(KeyAgreementSpi keyAgreeSpi, Provider provider, String algorithm)
      KeyAgreementオブジェクトを作成します。
      パラメータ:
      keyAgreeSpi - 委譲先
      provider - プロバイダ
      algorithm - アルゴリズム

  • メソッドの詳細

    • getAlgorithm

      public final String getAlgorithm()
      このKeyAgreementオブジェクトのアルゴリズム名を返します。

      これは、このKeyAgreementオブジェクトを作成したgetInstance呼出しのいずれかに指定された名前と同じです。

      戻り値:
      このKeyAgreementオブジェクトのアルゴリズム名。

    • getInstance

      public static final KeyAgreement getInstance(String algorithm) throws NoSuchAlgorithmException
      指定したキー合意アルゴリズムを実装するKeyAgreementオブジェクトを返します。

      このメソッドは、最も優先されるプロバイダから始まる登録済セキュリティ・プロバイダのリストを横断します。 指定されたアルゴリズムをサポートする最初のプロバイダからKeyAgreementSpi実装をカプセル化する新しいKeyAgreementオブジェクトが返されます。

      登録済みプロバイダのリストは、Security.getProviders()メソッド経由で取得できます。

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

    • getInstance

      public static final KeyAgreement getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException
      指定したキー合意アルゴリズムを実装するKeyAgreementオブジェクトを返します。

      指定したプロバイダからKeyAgreementSpi実装をカプセル化する新しいKeyAgreementオブジェクトが返されます。 指定したプロバイダは、セキュリティ・プロバイダ・リストに登録する必要があります。

      登録済みプロバイダのリストは、Security.getProviders()メソッド経由で取得できます。

      パラメータ:
      algorithm - 要求されたキー合意アルゴリズムの標準名。 標準アルゴリズム名の詳細は、「Javaセキュリティ標準アルゴリズム名仕様」のKeyAgreementの項を参照してください。
      provider - プロバイダ名。
      戻り値:
      新しいKeyAgreementオブジェクト
      スロー:
      IllegalArgumentException - providerがnullまたは空の場合
      NoSuchAlgorithmException - 指定されたアルゴリズムのKeyAgreementSpi実装が、指定されたプロバイダから利用可能でない場合
      NoSuchProviderException - 指定されたプロバイダがセキュリティ・プロバイダ・リストに登録されていない場合
      NullPointerException - algorithmがnullである場合
      関連項目:

    • getInstance

      public static final KeyAgreement getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException
      指定したキー合意アルゴリズムを実装するKeyAgreementオブジェクトを返します。

      指定したプロバイダからKeyAgreementSpi実装をカプセル化する新しいKeyAgreementオブジェクトが返されます。 指定されたプロバイダをプロバイダ・リストに登録する必要はありません。

      パラメータ:
      algorithm - 要求されたキー合意アルゴリズムの標準名。 標準アルゴリズム名の詳細は、「Javaセキュリティ標準アルゴリズム名仕様」のKeyAgreementの項を参照してください。
      provider - プロバイダ
      戻り値:
      新しいKeyAgreementオブジェクト
      スロー:
      IllegalArgumentException - providerがnullの場合
      NoSuchAlgorithmException - 指定されたアルゴリズムのKeyAgreementSpi実装が、指定されたProviderオブジェクトから使用できない場合
      NullPointerException - algorithmがnullである場合
      関連項目:

    • getProvider

      public final Provider getProvider()
      このKeyAgreementオブジェクトのプロバイダを返します。
      戻り値:
      このKeyAgreementオブジェクトのプロバイダ

    • init

      public final void init(Key key) throws InvalidKeyException
      指定されたキーでこのキー合意を初期化します。これには、このキー合意に必要なすべてのアルゴリズム・パラメータを含める必要があります。

      このキー合意が乱数バイトを必要とする場合は、インストールされているプロバイダのうち、もっとも優先順位の高いプロバイダのSecureRandomの実装を乱数発生の元として使用して乱数バイトを取得します。 (インストールされたプロバイダがいずれもSecureRandomの実装を提供しない場合、システム提供のランダム性ソースが使用されます。)

      パラメータ:
      key - 当事者の非公開情報。 たとえば、Diffie-Hellmanのキー合意の場合は、当事者自身のDiffie-Hellman非公開キー
      スロー:
      InvalidKeyException - 指定されたキーがこのキー合意に不適切な場合。たとえば、型が間違っている場合、またはアルゴリズムの型に互換性がない場合。

    • init

      public final void init(Key key, SecureRandom random) throws InvalidKeyException
      指定されたキーと乱数発生の元でこのキー合意を初期化します。 指定されたキーには、このキー合意に必要なすべてのアルゴリズム・パラメータを含める必要があります。

      キー合意アルゴリズムが乱数バイトを必要とする場合は、指定された乱数発生の元randomから取得します。 ただし、基本となるアルゴリズム実装が乱数バイトを必要としない場合、randomは無視されます。

      パラメータ:
      key - 当事者の非公開情報。 たとえば、Diffie-Hellmanのキー合意の場合は、当事者自身のDiffie-Hellman非公開キー
      random - 乱数発生の元
      スロー:
      InvalidKeyException - 指定されたキーがこのキー合意に不適切な場合。たとえば、型が間違っている場合、またはアルゴリズムの型に互換性がない場合。

    • init

      public final void init(Key key, AlgorithmParameterSpec params) throws InvalidKeyException, InvalidAlgorithmParameterException
      指定されたキーとアルゴリズム・パラメータのセットを使用してこのキー合意を初期化します。

      このキー合意が乱数バイトを必要とする場合は、インストールされているプロバイダのうち、もっとも優先順位の高いプロバイダのSecureRandomの実装を乱数発生の元として使用して乱数バイトを取得します。 (インストールされたプロバイダがいずれもSecureRandomの実装を提供しない場合、システム提供のランダム性ソースが使用されます。)

      パラメータ:
      key - 当事者の非公開情報。 たとえば、Diffie-Hellmanのキー合意の場合は、当事者自身のDiffie-Hellman非公開キー
      params - キー合意パラメータ
      スロー:
      InvalidKeyException - 指定されたキーがこのキー合意に不適切な場合。たとえば、型が間違っている場合、またはアルゴリズムの型に互換性がない場合。
      InvalidAlgorithmParameterException - 指定されたパラメータがこのキー合意に不適切な場合。

    • init

      public final void init(Key key, AlgorithmParameterSpec params, SecureRandom random) throws InvalidKeyException, InvalidAlgorithmParameterException
      指定されたキー、アルゴリズム・パラメータのセット、および乱数発生の元を使用してこのキー合意を初期化します。
      パラメータ:
      key - 当事者の非公開情報。 たとえば、Diffie-Hellmanのキー合意の場合は、当事者自身のDiffie-Hellman非公開キー
      params - キー合意パラメータ
      random - 乱数発生の元
      スロー:
      InvalidKeyException - 指定されたキーがこのキー合意に不適切な場合。たとえば、型が間違っている場合、またはアルゴリズムの型に互換性がない場合。
      InvalidAlgorithmParameterException - 指定されたパラメータがこのキー合意に不適切な場合。

    • doPhase

      public final Key doPhase(Key key, boolean lastPhase) throws InvalidKeyException, IllegalStateException
      このキー合意に関係する相手のだれかから受け取った、指定されたキーを使用してこのキー合意の次の段階を実行します。
      パラメータ:
      key - この段階のキー。 たとえば、2当事者間のDiffie-Hellmanの場合は、相手のDiffie-Hellman公開キー
      lastPhase - このキー契約の最終フェーズであるかどうかを示すフラグ。
      戻り値:
      このフェーズによって生成された(中間)キー、またはこのフェーズでキーが生成されない場合はnull
      スロー:
      InvalidKeyException - 指定されたキーがこの段階に不適切な場合。
      IllegalStateException - このキー合意が初期化されていない場合。

    • generateSecret

      public final byte[] generateSecret() throws IllegalStateException
      共有の秘密情報を生成して新しいバッファ内に返します。

      このメソッドは、KeyAgreementオブジェクトを、initメソッドのいずれかへの最新の呼出し後の状態にリセットします。 generateSecretへの呼び出し後、新しいキーを提供するためにdoPhaseを呼び出し、generateSecretを呼び出して新しいシークレットを生成することによって、オブジェクトを今後のキー協定操作に再利用できます。 この場合、initに提供されているプライベート情報とアルゴリズム・パラメータは、複数のキー協定操作に使用されます。 initメソッドは、generateSecretより後に呼び出すことで、後続の操作で使用されるプライベート情報を変更できます。

      戻り値:
      共有の秘密情報の入った新しいバッファ
      スロー:
      IllegalStateException - このキー協定が初期化されていない場合、またはアグリーメントのすべてのパーティに対してキーを指定するためにdoPhaseがコールされていない場合

    • generateSecret

      public final int generateSecret(byte[] sharedSecret, int offset) throws IllegalStateException, ShortBufferException
      共有の秘密情報を生成して、offsetから始まるsharedSecretバッファ内に格納します。

      sharedSecretバッファが小さすぎて結果を保持できない場合は、ShortBufferExceptionがスローされます。 この場合、より大きな出力バッファを使用してこの呼出しを繰り返します。

      このメソッドは、KeyAgreementオブジェクトを、initメソッドのいずれかへの最新の呼出し後の状態にリセットします。 generateSecretへの呼び出し後、新しいキーを提供するためにdoPhaseを呼び出し、generateSecretを呼び出して新しいシークレットを生成することによって、オブジェクトを今後のキー協定操作に再利用できます。 この場合、initに提供されているプライベート情報とアルゴリズム・パラメータは、複数のキー協定操作に使用されます。 initメソッドは、generateSecretより後に呼び出すことで、後続の操作で使用されるプライベート情報を変更できます。

      パラメータ:
      sharedSecret - 共有の秘密情報を格納するバッファ
      offset - 共有の秘密情報が格納されるsharedSecret内のオフセット
      戻り値:
      sharedSecretに格納されたバイト数
      スロー:
      IllegalStateException - このキー協定が初期化されていない場合、またはアグリーメントのすべてのパーティに対してキーを指定するためにdoPhaseがコールされていない場合
      ShortBufferException - 指定された出力バッファが小さすぎて秘密情報を保持できない場合

    • generateSecret

      public final SecretKey generateSecret(String algorithm) throws IllegalStateException, NoSuchAlgorithmException, InvalidKeyException
      共有の秘密情報を作成して、それを指定されたアルゴリズムのSecretKeyオブジェクトとして返します。

      このメソッドは、KeyAgreementオブジェクトを、initメソッドのいずれかへの最新の呼出し後の状態にリセットします。 generateSecretへの呼び出し後、新しいキーを提供するためにdoPhaseを呼び出し、generateSecretを呼び出して新しいシークレットを生成することによって、オブジェクトを今後のキー協定操作に再利用できます。 この場合、initに提供されているプライベート情報とアルゴリズム・パラメータは、複数のキー協定操作に使用されます。 initメソッドは、generateSecretより後に呼び出すことで、後続の操作で使用されるプライベート情報を変更できます。

      パラメータ:
      algorithm - 要求された秘密キーアルゴリズム
      戻り値:
      共有の秘密キー
      スロー:
      IllegalStateException - このキー協定が初期化されていない場合、またはアグリーメントのすべてのパーティに対してキーを指定するためにdoPhaseがコールされていない場合
      NoSuchAlgorithmException - 指定された秘密キーアルゴリズムがない場合
      InvalidKeyException - 共有の秘密キー・マテリアルが、指定されたアルゴリズムの秘密キーを生成に使用できない場合 (キー・データが短すぎるなど)