JavaTM Platform
Standard Ed. 6

javax.crypto
クラス 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 回呼び出す必要があります。鍵交換の相手の数は任意です。

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

コンストラクタの概要
protected KeyAgreement(KeyAgreementSpi keyAgreeSpi, Provider provider, String algorithm)
          KeyAgreement オブジェクトを生成します。
 
メソッドの概要
 Key doPhase(Key key, boolean lastPhase)
          この鍵合意に関係する相手のだれかから受け取った、指定された鍵を使用してこの鍵合意の次の段階を実行します。
 byte[] generateSecret()
          共有の秘密情報を生成して新しいバッファー内に返します。
 int generateSecret(byte[] sharedSecret, int offset)
          共有の秘密情報を生成して、offset から始まる sharedSecret バッファー内に格納します。
 SecretKey generateSecret(String algorithm)
          共有の秘密情報を作成して、それを指定されたアルゴリズムの SecretKey オブジェクトとして返します。
 String getAlgorithm()
          この KeyAgreement オブジェクトのアルゴリズム名を返します。
static KeyAgreement getInstance(String algorithm)
          指定した鍵合意アルゴリズムを実装する KeyAgreement オブジェクトを返します。
static KeyAgreement getInstance(String algorithm, Provider provider)
          指定した鍵合意アルゴリズムを実装する KeyAgreement オブジェクトを返します。
static KeyAgreement getInstance(String algorithm, String provider)
          指定した鍵合意アルゴリズムを実装する KeyAgreement オブジェクトを返します。
 Provider getProvider()
          この KeyAgreement オブジェクトのプロバイダを返します。
 void init(Key key)
          指定された鍵でこの鍵合意を初期化します。
 void init(Key key, AlgorithmParameterSpec params)
          指定された鍵とアルゴリズムパラメータのセットを使用してこの鍵合意を初期化します。
 void init(Key key, AlgorithmParameterSpec params, SecureRandom random)
          指定された鍵、アルゴリズムパラメータのセット、および乱数発生の元を使用してこの鍵合意を初期化します。
 void init(Key key, 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 呼び出しの 1 つで指定された名前と同じです。

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

getInstance

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

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

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

パラメータ:
algorithm - 要求された鍵合意アルゴリズムの標準名標準のアルゴリズム名については、「Java 暗号化アーキテクチャーリファレンスガイド」の付録 A を参照
戻り値:
新しい KeyAgreement オブジェクト
例外:
NullPointerException - 指定されたアルゴリズムが null である場合
NoSuchAlgorithmException - 指定したアルゴリズムの KeyAgreementSpi 実装をサポートするプロバイダが存在しない場合
関連項目:
Provider

getInstance

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

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

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

パラメータ:
algorithm - 要求された鍵合意アルゴリズムの標準名標準のアルゴリズム名については、「Java 暗号化アーキテクチャーリファレンスガイド」の付録 A を参照
provider - プロバイダ名
戻り値:
新しい KeyAgreement オブジェクト
例外:
NullPointerException - 指定されたアルゴリズムが null である場合
NoSuchAlgorithmException - 指定されたプロバイダに指定されたアルゴリズムの KeyAgreementSpi の実装がない場合
NoSuchProviderException - 指定されたプロバイダがセキュリティープロバイダリストに登録されていない場合
IllegalArgumentException - provider が null または空の場合
関連項目:
Provider

getInstance

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

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

パラメータ:
algorithm - 要求された鍵合意アルゴリズムの標準名標準のアルゴリズム名については、「Java 暗号化アーキテクチャーリファレンスガイド」の付録 A を参照
provider - プロバイダ
戻り値:
新しい KeyAgreement オブジェクト
例外:
NullPointerException - 指定されたアルゴリズムが null である場合
NoSuchAlgorithmException - 指定された Provider オブジェクトに指定されたアルゴリズムの KeyAgreementSpi の実装がない場合
IllegalArgumentException - provider が null の場合
関連項目:
Provider

getProvider

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

戻り値:
この KeyAgreement オブジェクトのプロバイダ

init

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

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

パラメータ:
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 を提供するプロバイダが 1 つもインストールされていない場合は、システムが提供する乱数発生の元が使用されます。

パラメータ:
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 メソッドの 1 つで再初期化されない場合、その後の鍵合意では、同じ非公開情報とアルゴリズムパラメータが使用されます。

戻り値:
共有の秘密情報の入った新しいバッファー
例外:
IllegalStateException - この鍵合意がまだ完了していない場合

generateSecret

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

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

このメソッドは、この KeyAgreement オブジェクトをリセットするので、さらにほかの鍵合意に再使用できます。この鍵合意が init メソッドの 1 つで再初期化されない場合、その後の鍵合意では、同じ非公開情報とアルゴリズムパラメータが使用されます。

パラメータ:
sharedSecret - 共有の秘密情報を格納するバッファー
offset - 共有の秘密情報が格納される sharedSecret 内のオフセット
戻り値:
sharedSecret に格納されたバイト数
例外:
IllegalStateException - この鍵合意がまだ完了していない場合
ShortBufferException - 指定された出力バッファーが小さすぎて秘密情報を保持できない場合

generateSecret

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

このメソッドは、この KeyAgreement オブジェクトをリセットするので、さらにほかの鍵合意に再使用できます。この鍵合意が init メソッドの 1 つで再初期化されない場合、その後の鍵合意では、同じ非公開情報とアルゴリズムパラメータが使用されます。

パラメータ:
algorithm - 要求された秘密鍵アルゴリズム
戻り値:
共有の秘密鍵
例外:
IllegalStateException - この鍵合意がまだ完了していない場合
NoSuchAlgorithmException - 指定された秘密鍵アルゴリズムがない場合
InvalidKeyException - 共有の秘密鍵データを使用して、指定されたアルゴリズムの秘密鍵を生成できない場合 (鍵データが短すぎるなど)

JavaTM Platform
Standard Ed. 6

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2009 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。