javax.crypto
類別 KeyAgreement

java.lang.Object
  javax.crypto.KeyAgreement

public class KeyAgreement
extends Object

此類別提供密鑰協定（或密鑰交換）協議的功能。

建立共享秘密所涉及的密鑰由某個密鑰產生器（KeyPairGenerator 或 KeyGenerator）或一個 KeyFactory 來創建，或者在密鑰協定協議的中間階段創建。

對於密鑰交換中的每個相關方，需要調用 doPhase。例如，如果此密鑰交換是與其他一個參與者進行的，則需要調用一次 doPhase，調用時將 lastPhase 標誌設置為 true。如果此密鑰交換是與其他兩個參與者進行的，則需要調用兩次 doPhase，第一次將 lastPhase 標誌設置為 false，第二次將它設置為 true。密鑰交換可以涉及任意數量的參與者。

從以下版本開始：

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) 產生共享秘密，並將其放入緩衝區 sharedSecret，從 offset（包括）開始。
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 調用中指定的名稱相同。

返回：

此 KeyAgreement 物件的演算法名稱。

getInstance

public static final KeyAgreement getInstance(String algorithm)
                                      throws NoSuchAlgorithmException

返回實作指定密鑰協定演算法的 KeyAgreement 物件。

此方法從首選 Provider 開始遍歷已註冊安全提供者列表。返回一個封裝 KeyAgreementSpi 實作的新 KeyAgreement 物件，該實作取自支持指定演算法的第一個 Provider。

注意，可以通過 Security.getProviders() 方法獲取已註冊提供者列表。

參數：

algorithm - 所請求密鑰協定演算法的標準名稱。有關標準演算法名稱的資訊，請參閱 Java Cryptography Architecture Reference Guide 中的附錄 A。

返回：

新的 KeyAgreement 物件。

拋出：

NullPointerException - 如果指定的演算法為 null。

NoSuchAlgorithmException - 如果沒有 Provider 支持指定演算法的 KeyAgreementSpi 實作。

另請參見：

Provider

getInstance

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

返回實作指定密鑰協定演算法的 KeyAgreement 物件。

返回一個封裝 KeyAgreementSpi 實作的新 KeyAgreement 物件，該實作取自指定的提供者。指定提供者必須在安全提供者列表中註冊。

注意，可以通過 Security.getProviders() 方法獲取已註冊提供者列表。

參數：

algorithm - 所請求密鑰協定演算法的標準名稱。有關標準演算法名稱的資訊，請參閱 Java Cryptography Architecture Reference Guide 中的附錄 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 物件。

返回一個封裝 KeyAgreementSpi 實作的新 KeyAgreement 物件，該實作取自指定的 Provider 物件。 注意，指定的 Provider 物件無需在提供者列表中註冊。

參數：

algorithm - 所請求密鑰協定演算法的標準名稱。有關標準演算法名稱的資訊，請參閱 Java Cryptography Architecture Reference Guide 中的附錄 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 實作，則將使用系統提供的隨機源。）

參數：

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 - 此階段的密鑰。例如，對於兩個參與者之間的 Diffie-Hellman，此密鑰將是另一個參與者的 Diffie-Hellman 公鑰。

lastPhase - 表示這是否是此密鑰協定最後階段的標誌。

返回：

從此階段得到的（中間）密鑰；如果此階段不產生密鑰，則返回 null

拋出：

InvalidKeyException - 如果給定密鑰不適合此階段。

IllegalStateException - 如果尚未初始化此密鑰協定。

generateSecret

public final byte[] generateSecret()
                            throws IllegalStateException

產生共享秘密並在新的緩衝區中返回它。

此方法重置此 KeyAgreement 物件，以便能夠將它重用於進一步的密鑰協定。如果沒有使用某個 init 方法重新初始化此密鑰協定，則將相同的私有資訊和演算法參數用於後續密鑰協定。

返回：

包含共享秘密的新緩衝區

拋出：

IllegalStateException - 如果尚未完成此密鑰協定

generateSecret

public final int generateSecret(byte[] sharedSecret,
                                int offset)
                         throws IllegalStateException,
                                ShortBufferException

產生共享秘密，並將其放入緩衝區 sharedSecret，從 offset（包括）開始。

如果 sharedSecret 緩衝區太小而無法保存該結果，則拋出 ShortBufferException。在此情況下，應該用更大的輸出緩衝區再次調用此方法。

此方法重置此 KeyAgreement 物件，以便能夠將它重用於進一步的密鑰協定。如果沒有使用某個 init 方法重新初始化此密鑰協定，則將相同的私有資訊和演算法參數用於後續密鑰協定。

參數：

sharedSecret - 共享秘密的緩衝區

offset - sharedSecret 中將存儲共享秘密處的偏移量

返回：

放入 sharedSecret 中的位元組數

拋出：

IllegalStateException - 如果尚未完成此密鑰協定

ShortBufferException - 如果給定輸出緩衝區太小而無法保存該秘密

generateSecret

public final SecretKey generateSecret(String algorithm)
                               throws IllegalStateException,
                                      NoSuchAlgorithmException,
                                      InvalidKeyException

創建共享秘密並將其作為指定演算法的 SecretKey 物件返回。

此方法重置此 KeyAgreement 物件，以便能夠將它重用於進一步的密鑰協定。如果沒有使用某個 init 方法重新初始化此密鑰協定，則將相同的私有資訊和演算法參數用於後續密鑰協定。

參數：

algorithm - 所請求秘密密鑰的演算法

返回：

共享的秘密密鑰

拋出：

IllegalStateException - 如果尚未完成此密鑰協定

NoSuchAlgorithmException - 如果指定的秘密密鑰演算法不可用

InvalidKeyException - 如果無法使用共享秘密密鑰材料產生指定演算法的秘密密鑰（例如，密鑰材料太短）