モジュール java.base

パッケージ 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回呼び出す必要があります。 鍵交換の相手の数は任意です。

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

• DiffieHellman

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

導入されたバージョン:

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, String provider)	指定した鍵合意アルゴリズムを実装するKeyAgreementオブジェクトを返します。
static KeyAgreement	getInstance(String algorithm, Provider provider)	指定した鍵合意アルゴリズムを実装するKeyAgreementオブジェクトを返します。
Provider	getProvider()	このKeyAgreementオブジェクトのプロバイダを返します。
void	init(Key key)	指定された鍵でこの鍵合意を初期化します。これには、この鍵合意に必要なすべてのアルゴリズム・パラメータを含める必要があります。
void	init(Key key, SecureRandom random)	指定された鍵と乱数発生の元でこの鍵合意を初期化します。
void	init(Key key, AlgorithmParameterSpec params)	指定された鍵とアルゴリズム・パラメータのセットを使用してこの鍵合意を初期化します。
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オブジェクトを返します。

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

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

実装上の注意:

JDKリファレンス実装では、jdk.security.provider.preferred Securityプロパティを使用して、指定されたアルゴリズムの優先プロバイダの順序を決定します。 これは、Security.getProviders()によって返されるプロバイダの順序とは異なる場合があります。

パラメータ:

algorithm - 要求された鍵合意アルゴリズムの標準名。 標準アルゴリズム名については、「Javaセキュリティ標準アルゴリズム名指定」のKeyAgreementセクションを参照してください。

戻り値:

新しいKeyAgreementオブジェクト

例外:

NoSuchAlgorithmException - Providerが、指定されたアルゴリズムのKeyAgreementSpi実装をサポートしていない場合

NullPointerException - algorithmがnullである場合

関連項目:

Provider

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である場合

関連項目:

Provider

getInstance

public static final KeyAgreement getInstance(String algorithm,
                                             Provider provider)
                                      throws NoSuchAlgorithmException

指定した鍵合意アルゴリズムを実装するKeyAgreementオブジェクトを返します。

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

パラメータ:

algorithm - 要求された鍵合意アルゴリズムの標準名。 標準アルゴリズム名については、「Javaセキュリティ標準アルゴリズム名指定」のKeyAgreementセクションを参照してください。

provider - プロバイダ

戻り値:

新しいKeyAgreementオブジェクト

例外:

IllegalArgumentException - providerがnullの場合

NoSuchAlgorithmException - 指定されたProviderオブジェクトから指定されたアルゴリズムのKeyAgreementSpi実装を使用できない場合

NullPointerException - algorithmが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 - 共有の秘密鍵データを使用して、指定されたアルゴリズムの秘密鍵を生成できない場合(鍵データが短すぎるなど)