--- a/src/java.base/share/classes/javax/crypto/KeyAgreement.java Tue Oct 30 10:32:54 2018 -0700
+++ b/src/java.base/share/classes/javax/crypto/KeyAgreement.java Tue Oct 30 13:48:19 2018 -0400
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -582,16 +582,22 @@
/**
* 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.
+ * <p>This method resets this {@code KeyAgreement} object to the state that
+ * it was in after the most recent call to one of the {@code init} methods.
+ * After a call to {@code generateSecret}, the object can be reused for
+ * further key agreement operations by calling {@code doPhase} to supply
+ * new keys, and then calling {@code generateSecret} to produce a new
+ * secret. In this case, the private information and algorithm parameters
+ * supplied to {@code init} will be used for multiple key agreement
+ * operations. The {@code init} method can be called after
+ * {@code generateSecret} to change the private information used in
+ * subsequent operations.
*
* @return the new buffer with the shared secret
*
* @exception IllegalStateException if this key agreement has not been
- * completed yet
+ * initialized or if {@code doPhase} has not been called to supply the
+ * keys for all parties in the agreement
*/
public final byte[] generateSecret() throws IllegalStateException {
chooseFirstProvider();
@@ -606,11 +612,16 @@
* 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.
+ * <p>This method resets this {@code KeyAgreement} object to the state that
+ * it was in after the most recent call to one of the {@code init} methods.
+ * After a call to {@code generateSecret}, the object can be reused for
+ * further key agreement operations by calling {@code doPhase} to supply
+ * new keys, and then calling {@code generateSecret} to produce a new
+ * secret. In this case, the private information and algorithm parameters
+ * supplied to {@code init} will be used for multiple key agreement
+ * operations. The {@code init} method can be called after
+ * {@code generateSecret} to change the private information used in
+ * subsequent operations.
*
* @param sharedSecret the buffer for the shared secret
* @param offset the offset in {@code sharedSecret} where the
@@ -619,7 +630,8 @@
* @return the number of bytes placed into {@code sharedSecret}
*
* @exception IllegalStateException if this key agreement has not been
- * completed yet
+ * initialized or if {@code doPhase} has not been called to supply the
+ * keys for all parties in the agreement
* @exception ShortBufferException if the given output buffer is too small
* to hold the secret
*/
@@ -634,18 +646,24 @@
* 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.
+ * <p>This method resets this {@code KeyAgreement} object to the state that
+ * it was in after the most recent call to one of the {@code init} methods.
+ * After a call to {@code generateSecret}, the object can be reused for
+ * further key agreement operations by calling {@code doPhase} to supply
+ * new keys, and then calling {@code generateSecret} to produce a new
+ * secret. In this case, the private information and algorithm parameters
+ * supplied to {@code init} will be used for multiple key agreement
+ * operations. The {@code init} method can be called after
+ * {@code generateSecret} to change the private information used in
+ * subsequent operations.
*
* @param algorithm the requested secret-key algorithm
*
* @return the shared secret key
*
* @exception IllegalStateException if this key agreement has not been
- * completed yet
+ * initialized or if {@code doPhase} has not been called to supply the
+ * keys for all parties in the agreement
* @exception NoSuchAlgorithmException if the specified secret-key
* algorithm is not available
* @exception InvalidKeyException if the shared secret-key material cannot