< prev index next >
src/java.base/share/classes/javax/crypto/KeyAgreement.java
Print this page
*** 38,65 ****
/**
* This class provides the functionality of a key agreement (or key
* exchange) protocol.
* <p>
* The keys involved in establishing a shared secret are created by one of the
! * key generators (<code>KeyPairGenerator</code> or
! * <code>KeyGenerator</code>), a <code>KeyFactory</code>, or as a result from
* an intermediate phase of the key agreement protocol.
*
! * <p> For each of the correspondents in the key exchange, <code>doPhase</code>
* needs to be called. For example, if this key exchange is with one other
! * party, <code>doPhase</code> needs to be called once, with the
! * <code>lastPhase</code> flag set to <code>true</code>.
* If this key exchange is
! * with two other parties, <code>doPhase</code> needs to be called twice,
! * the first time setting the <code>lastPhase</code> flag to
! * <code>false</code>, and the second time setting it to <code>true</code>.
* There may be any number of parties involved in a key exchange.
*
* <p> Every implementation of the Java platform is required to support the
! * following standard <code>KeyAgreement</code> algorithm:
* <ul>
! * <li><tt>DiffieHellman</tt></li>
* </ul>
* This algorithm is described in the <a href=
* "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyAgreement">
* KeyAgreement section</a> of the
* Java Cryptography Architecture Standard Algorithm Name Documentation.
--- 38,65 ----
/**
* This class provides the functionality of a key agreement (or key
* exchange) protocol.
* <p>
* The keys involved in establishing a shared secret are created by one of the
! * key generators ({@code KeyPairGenerator} or
! * {@code KeyGenerator}), a {@code KeyFactory}, or as a result from
* an intermediate phase of the key agreement protocol.
*
! * <p> For each of the correspondents in the key exchange, {@code doPhase}
* needs to be called. For example, if this key exchange is with one other
! * party, {@code doPhase} needs to be called once, with the
! * {@code lastPhase} flag set to {@code true}.
* If this key exchange is
! * with two other parties, {@code doPhase} needs to be called twice,
! * the first time setting the {@code lastPhase} flag to
! * {@code false}, and the second time setting it to {@code true}.
* There may be any number of parties involved in a key exchange.
*
* <p> Every implementation of the Java platform is required to support the
! * following standard {@code KeyAgreement} algorithm:
* <ul>
! * <li>{@code DiffieHellman}</li>
* </ul>
* This algorithm is described in the <a href=
* "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyAgreement">
* KeyAgreement section</a> of the
* Java Cryptography Architecture Standard Algorithm Name Documentation.
*** 123,146 ****
this.algorithm = algorithm;
lock = new Object();
}
/**
! * Returns the algorithm name of this <code>KeyAgreement</code> object.
*
* <p>This is the same name that was specified in one of the
! * <code>getInstance</code> calls that created this
! * <code>KeyAgreement</code> object.
*
! * @return the algorithm name of this <code>KeyAgreement</code> object.
*/
public final String getAlgorithm() {
return this.algorithm;
}
/**
! * Returns a <code>KeyAgreement</code> object that implements the
* specified key agreement algorithm.
*
* <p> This method traverses the list of registered security Providers,
* starting with the most preferred Provider.
* A new KeyAgreement object encapsulating the
--- 123,146 ----
this.algorithm = algorithm;
lock = new Object();
}
/**
! * Returns the algorithm name of this {@code KeyAgreement} object.
*
* <p>This is the same name that was specified in one of the
! * {@code getInstance} calls that created this
! * {@code KeyAgreement} object.
*
! * @return the algorithm name of this {@code KeyAgreement} object.
*/
public final String getAlgorithm() {
return this.algorithm;
}
/**
! * Returns a {@code KeyAgreement} object that implements the
* specified key agreement algorithm.
*
* <p> This method traverses the list of registered security Providers,
* starting with the most preferred Provider.
* A new KeyAgreement object encapsulating the
*** 155,165 ****
* See the KeyAgreement section in the <a href=
* "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyAgreement">
* Java Cryptography Architecture Standard Algorithm Name Documentation</a>
* for information about standard algorithm names.
*
! * @return the new <code>KeyAgreement</code> object.
*
* @exception NullPointerException if the specified algorithm
* is null.
*
* @exception NoSuchAlgorithmException if no Provider supports a
--- 155,165 ----
* See the KeyAgreement section in the <a href=
* "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyAgreement">
* Java Cryptography Architecture Standard Algorithm Name Documentation</a>
* for information about standard algorithm names.
*
! * @return the new {@code KeyAgreement} object.
*
* @exception NullPointerException if the specified algorithm
* is null.
*
* @exception NoSuchAlgorithmException if no Provider supports a
*** 184,194 ****
throw new NoSuchAlgorithmException
("Algorithm " + algorithm + " not available");
}
/**
! * Returns a <code>KeyAgreement</code> object that implements the
* specified key agreement algorithm.
*
* <p> A new KeyAgreement object encapsulating the
* KeyAgreementSpi implementation from the specified provider
* is returned. The specified provider must be registered
--- 184,194 ----
throw new NoSuchAlgorithmException
("Algorithm " + algorithm + " not available");
}
/**
! * Returns a {@code KeyAgreement} object that implements the
* specified key agreement algorithm.
*
* <p> A new KeyAgreement object encapsulating the
* KeyAgreementSpi implementation from the specified provider
* is returned. The specified provider must be registered
*** 204,214 ****
* Java Cryptography Architecture Standard Algorithm Name Documentation</a>
* for information about standard algorithm names.
*
* @param provider the name of the provider.
*
! * @return the new <code>KeyAgreement</code> object.
*
* @exception NullPointerException if the specified algorithm
* is null.
*
* @exception NoSuchAlgorithmException if a KeyAgreementSpi
--- 204,214 ----
* Java Cryptography Architecture Standard Algorithm Name Documentation</a>
* for information about standard algorithm names.
*
* @param provider the name of the provider.
*
! * @return the new {@code KeyAgreement} object.
*
* @exception NullPointerException if the specified algorithm
* is null.
*
* @exception NoSuchAlgorithmException if a KeyAgreementSpi
*** 216,226 ****
* available from the specified provider.
*
* @exception NoSuchProviderException if the specified provider is not
* registered in the security provider list.
*
! * @exception IllegalArgumentException if the <code>provider</code>
* is null or empty.
*
* @see java.security.Provider
*/
public static final KeyAgreement getInstance(String algorithm,
--- 216,226 ----
* available from the specified provider.
*
* @exception NoSuchProviderException if the specified provider is not
* registered in the security provider list.
*
! * @exception IllegalArgumentException if the {@code provider}
* is null or empty.
*
* @see java.security.Provider
*/
public static final KeyAgreement getInstance(String algorithm,
*** 231,241 ****
return new KeyAgreement((KeyAgreementSpi)instance.impl,
instance.provider, algorithm);
}
/**
! * Returns a <code>KeyAgreement</code> object that implements the
* specified key agreement algorithm.
*
* <p> A new KeyAgreement object encapsulating the
* KeyAgreementSpi implementation from the specified Provider
* object is returned. Note that the specified Provider object
--- 231,241 ----
return new KeyAgreement((KeyAgreementSpi)instance.impl,
instance.provider, algorithm);
}
/**
! * Returns a {@code KeyAgreement} object that implements the
* specified key agreement algorithm.
*
* <p> A new KeyAgreement object encapsulating the
* KeyAgreementSpi implementation from the specified Provider
* object is returned. Note that the specified Provider object
*** 248,267 ****
* Java Cryptography Architecture Standard Algorithm Name Documentation</a>
* for information about standard algorithm names.
*
* @param provider the provider.
*
! * @return the new <code>KeyAgreement</code> object.
*
* @exception NullPointerException if the specified algorithm
* is null.
*
* @exception NoSuchAlgorithmException if a KeyAgreementSpi
* implementation for the specified algorithm is not available
* from the specified Provider object.
*
! * @exception IllegalArgumentException if the <code>provider</code>
* is null.
*
* @see java.security.Provider
*/
public static final KeyAgreement getInstance(String algorithm,
--- 248,267 ----
* Java Cryptography Architecture Standard Algorithm Name Documentation</a>
* for information about standard algorithm names.
*
* @param provider the provider.
*
! * @return the new {@code KeyAgreement} object.
*
* @exception NullPointerException if the specified algorithm
* is null.
*
* @exception NoSuchAlgorithmException if a KeyAgreementSpi
* implementation for the specified algorithm is not available
* from the specified Provider object.
*
! * @exception IllegalArgumentException if the {@code provider}
* is null.
*
* @see java.security.Provider
*/
public static final KeyAgreement getInstance(String algorithm,
*** 406,418 ****
+ kName, lastException);
}
}
/**
! * Returns the provider of this <code>KeyAgreement</code> object.
*
! * @return the provider of this <code>KeyAgreement</code> object
*/
public final Provider getProvider() {
chooseFirstProvider();
return this.provider;
}
--- 406,418 ----
+ kName, lastException);
}
}
/**
! * Returns the provider of this {@code KeyAgreement} object.
*
! * @return the provider of this {@code KeyAgreement} object
*/
public final Provider getProvider() {
chooseFirstProvider();
return this.provider;
}
*** 445,458 ****
* Initializes this key agreement with the given key and source of
* randomness. The given key is required to contain all the algorithm
* parameters required for this key agreement.
*
* <p> If the key agreement algorithm requires random bytes, it gets them
! * from the given source of randomness, <code>random</code>.
* However, if the underlying
* algorithm implementation does not require any random bytes,
! * <code>random</code> is ignored.
*
* @param key the party's private information. For example, in the case
* of the Diffie-Hellman key agreement, this would be the party's own
* Diffie-Hellman private key.
* @param random the source of randomness
--- 445,458 ----
* Initializes this key agreement with the given key and source of
* randomness. The given key is required to contain all the algorithm
* parameters required for this key agreement.
*
* <p> If the key agreement algorithm requires random bytes, it gets them
! * from the given source of randomness, {@code random}.
* However, if the underlying
* algorithm implementation does not require any random bytes,
! * {@code random} is ignored.
*
* @param key the party's private information. For example, in the case
* of the Diffie-Hellman key agreement, this would be the party's own
* Diffie-Hellman private key.
* @param random the source of randomness
*** 568,580 ****
}
/**
* Generates the shared secret and returns it in a new buffer.
*
! * <p>This method resets this <code>KeyAgreement</code> object, so that it
* can be reused for further key agreements. Unless this key agreement is
! * reinitialized with one of the <code>init</code> methods, the same
* private information and algorithm parameters will be used for
* subsequent key agreements.
*
* @return the new buffer with the shared secret
*
--- 568,580 ----
}
/**
* Generates the shared secret and returns it in a new buffer.
*
! * <p>This method resets this {@code KeyAgreement} object, so that it
* can be reused for further key agreements. Unless this key agreement is
! * reinitialized with one of the {@code init} methods, the same
* private information and algorithm parameters will be used for
* subsequent key agreements.
*
* @return the new buffer with the shared secret
*
*** 586,612 ****
return spi.engineGenerateSecret();
}
/**
* Generates the shared secret, and places it into the buffer
! * <code>sharedSecret</code>, beginning at <code>offset</code> inclusive.
*
! * <p>If the <code>sharedSecret</code> buffer is too small to hold the
! * result, a <code>ShortBufferException</code> is thrown.
* In this case, this call should be repeated with a larger output buffer.
*
! * <p>This method resets this <code>KeyAgreement</code> object, so that it
* can be reused for further key agreements. Unless this key agreement is
! * reinitialized with one of the <code>init</code> methods, the same
* private information and algorithm parameters will be used for
* subsequent key agreements.
*
* @param sharedSecret the buffer for the shared secret
! * @param offset the offset in <code>sharedSecret</code> where the
* shared secret will be stored
*
! * @return the number of bytes placed into <code>sharedSecret</code>
*
* @exception IllegalStateException if this key agreement has not been
* completed yet
* @exception ShortBufferException if the given output buffer is too small
* to hold the secret
--- 586,612 ----
return spi.engineGenerateSecret();
}
/**
* Generates the shared secret, and places it into the buffer
! * {@code sharedSecret}, beginning at {@code offset} inclusive.
*
! * <p>If the {@code sharedSecret} buffer is too small to hold the
! * result, a {@code ShortBufferException} is thrown.
* In this case, this call should be repeated with a larger output buffer.
*
! * <p>This method resets this {@code KeyAgreement} object, so that it
* can be reused for further key agreements. Unless this key agreement is
! * reinitialized with one of the {@code init} methods, the same
* private information and algorithm parameters will be used for
* subsequent key agreements.
*
* @param sharedSecret the buffer for the shared secret
! * @param offset the offset in {@code sharedSecret} where the
* shared secret will be stored
*
! * @return the number of bytes placed into {@code sharedSecret}
*
* @exception IllegalStateException if this key agreement has not been
* completed yet
* @exception ShortBufferException if the given output buffer is too small
* to hold the secret
*** 617,632 ****
chooseFirstProvider();
return spi.engineGenerateSecret(sharedSecret, offset);
}
/**
! * Creates the shared secret and returns it as a <code>SecretKey</code>
* object of the specified algorithm.
*
! * <p>This method resets this <code>KeyAgreement</code> object, so that it
* can be reused for further key agreements. Unless this key agreement is
! * reinitialized with one of the <code>init</code> methods, the same
* private information and algorithm parameters will be used for
* subsequent key agreements.
*
* @param algorithm the requested secret-key algorithm
*
--- 617,632 ----
chooseFirstProvider();
return spi.engineGenerateSecret(sharedSecret, offset);
}
/**
! * Creates the shared secret and returns it as a {@code SecretKey}
* object of the specified algorithm.
*
! * <p>This method resets this {@code KeyAgreement} object, so that it
* can be reused for further key agreements. Unless this key agreement is
! * reinitialized with one of the {@code init} methods, the same
* private information and algorithm parameters will be used for
* subsequent key agreements.
*
* @param algorithm the requested secret-key algorithm
*
< prev index next >