cleaned up commenting a bit

2 files changed, 263 insertions, 316 deletions

diff --git a/crypto/src/crypto/agreement/jpake/JPAKEParticipant.cs b/crypto/src/crypto/agreement/jpake/JPAKEParticipant.cs
index f36069262..bd18765b4 100755
--- a/crypto/src/crypto/agreement/jpake/JPAKEParticipant.cs
+++ b/crypto/src/crypto/agreement/jpake/JPAKEParticipant.cs
@@ -5,62 +5,57 @@ using Org.BouncyCastle.Crypto.Digests;
 using Org.BouncyCastle.Math;
 using Org.BouncyCastle.Security;
 
-/**
- * A participant in a Password Authenticated Key Exchange by Juggling (J-PAKE) exchange.
- * <p>
- * The J-PAKE exchange is defined by Feng Hao and Peter Ryan in the paper
- * <a href="http://grouper.ieee.org/groups/1363/Research/contributions/hao-ryan-2008.pdf">
- * "Password Authenticated Key Exchange by Juggling, 2008."</a>
- * <p>
- * The J-PAKE protocol is symmetric.
- * There is no notion of a <i>client</i> or <i>server</i>, but rather just two <i>participants</i>.
- * An instance of {@link JPAKEParticipant} represents one participant, and
- * is the primary interface for executing the exchange.
- * <p>
- * To execute an exchange, construct a {@link JPAKEParticipant} on each end,
- * and call the following 7 methods
- * (once and only once, in the given order, for each participant, sending messages between them as described):
- * <ol>
- * <li>{@link #createRound1PayloadToSend()} - and send the payload to the other participant</li>
- * <li>{@link #validateRound1PayloadReceived(JPAKERound1Payload)} - use the payload received from the other participant</li>
- * <li>{@link #createRound2PayloadToSend()} - and send the payload to the other participant</li>
- * <li>{@link #validateRound2PayloadReceived(JPAKERound2Payload)} - use the payload received from the other participant</li>
- * <li>{@link #calculateKeyingMaterial()}</li>
- * <li>{@link #createRound3PayloadToSend(BigInteger)} - and send the payload to the other participant</li>
- * <li>{@link #validateRound3PayloadReceived(JPAKERound3Payload, BigInteger)} - use the payload received from the other participant</li>
- * </ol>
- * <p>
- * Each side should derive a session key from the keying material returned by {@link #calculateKeyingMaterial()}.
- * The caller is responsible for deriving the session key using a secure key derivation function (KDF).
- * <p>
- * Round 3 is an optional key confirmation process.
- * If you do not execute round 3, then there is no assurance that both participants are using the same key.
- * (i.e. if the participants used different passwords, then their session keys will differ.)
- * <p>
- * If the round 3 validation succeeds, then the keys are guaranteed to be the same on both sides.
- * <p>
- * The symmetric design can easily support the asymmetric cases when one party initiates the communication.
- * e.g. Sometimes the round1 payload and round2 payload may be sent in one pass.
- * Also, in some cases, the key confirmation payload can be sent together with the round2 payload.
- * These are the trivial techniques to optimize the communication.
- * <p>
- * The key confirmation process is implemented as specified in
- * <a href="http://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdf">NIST SP 800-56A Revision 1</a>,
- * Section 8.2 Unilateral Key Confirmation for Key Agreement Schemes.
- * <p>
- * This class is stateful and NOT threadsafe.
- * Each instance should only be used for ONE complete J-PAKE exchange
- * (i.e. a new {@link JPAKEParticipant} should be constructed for each new J-PAKE exchange).
- * <p>
- */
 namespace Org.BouncyCastle.Crypto.Agreement.Jpake
 {
+    /// <summary>
+    /// A participant in a Password Authenticated Key Exchange by Juggling (J-PAKE) exchange.
+    ///
+    /// The J-PAKE exchange is defined by Feng Hao and Peter Ryan in the paper
+    /// <a href="http://grouper.ieee.org/groups/1363/Research/contributions/hao-ryan-2008.pdf">
+    /// "Password Authenticated Key Exchange by Juggling, 2008."</a>
+    ///
+    /// The J-PAKE protocol is symmetric.
+    /// There is no notion of a <i>client</i> or <i>server</i>, but rather just two <i>participants</i>.
+    /// An instance of JPAKEParticipant represents one participant, and
+    /// is the primary interface for executing the exchange.
+    ///
+    /// To execute an exchange, construct a JPAKEParticipant on each end,
+    /// and call the following 7 methods
+    /// (once and only once, in the given order, for each participant, sending messages between them as described):
+    ///
+    /// CreateRound1PayloadToSend() - and send the payload to the other participant
+    /// ValidateRound1PayloadReceived(JPAKERound1Payload) - use the payload received from the other participant
+    /// CreateRound2PayloadToSend() - and send the payload to the other participant
+    /// ValidateRound2PayloadReceived(JPAKERound2Payload) - use the payload received from the other participant
+    /// CalculateKeyingMaterial()
+    /// CreateRound3PayloadToSend(BigInteger) - and send the payload to the other participant
+    /// ValidateRound3PayloadReceived(JPAKERound3Payload, BigInteger) - use the payload received from the other participant
+    ///
+    /// Each side should derive a session key from the keying material returned by CalculateKeyingMaterial().
+    /// The caller is responsible for deriving the session key using a secure key derivation function (KDF).
+    ///
+    /// Round 3 is an optional key confirmation process.
+    /// If you do not execute round 3, then there is no assurance that both participants are using the same key.
+    /// (i.e. if the participants used different passwords, then their session keys will differ.)
+    ///
+    /// If the round 3 validation succeeds, then the keys are guaranteed to be the same on both sides.
+    ///
+    /// The symmetric design can easily support the asymmetric cases when one party initiates the communication.
+    /// e.g. Sometimes the round1 payload and round2 payload may be sent in one pass.
+    /// Also, in some cases, the key confirmation payload can be sent together with the round2 payload.
+    /// These are the trivial techniques to optimize the communication.
+    ///
+    /// The key confirmation process is implemented as specified in
+    /// <a href="http://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdf">NIST SP 800-56A Revision 1</a>,
+    /// Section 8.2 Unilateral Key Confirmation for Key Agreement Schemes.
+    ///
+    /// This class is stateful and NOT threadsafe.
+    /// Each instance should only be used for ONE complete J-PAKE exchange
+    /// (i.e. a new JPAKEParticipant should be constructed for each new J-PAKE exchange).
+    /// </summary>
     public class JPAKEParticipant
     {
-        /*
-         * Possible internal states.  Used for state checking.
-         */
-
+        // Possible internal states.  Used for state checking.
         public static readonly int STATE_INITIALIZED = 0;
         public static readonly int STATE_ROUND_1_CREATED = 10;
         public static readonly int STATE_ROUND_1_VALIDATED = 20;
@@ -70,131 +65,103 @@ namespace Org.BouncyCastle.Crypto.Agreement.Jpake
         public static readonly int STATE_ROUND_3_CREATED = 60;
         public static readonly int STATE_ROUND_3_VALIDATED = 70;
 
-        /**
-         * Unique identifier of this participant.
-         * The two participants in the exchange must NOT share the same id.
-         */
+        // Unique identifier of this participant.
+        // The two participants in the exchange must NOT share the same id.
         private string participantId;
 
-        /**
-         * Shared secret.  This only contains the secret between construction
-         * and the call to {@link #calculateKeyingMaterial()}.
-         * <p>
-         * i.e. When {@link #calculateKeyingMaterial()} is called, this buffer overwritten with 0's,
-         * and the field is set to null.
-         * </p>
-         */
+        // Shared secret.  This only contains the secret between construction
+        // and the call to CalculateKeyingMaterial().
+        //
+        // i.e. When CalculateKeyingMaterial() is called, this buffer overwritten with 0's,
+        // and the field is set to null.
         private char[] password;
 
-        /**
-         * Digest to use during calculations.
-         */
+        // Digest to use during calculations.
         private IDigest digest;
         
-        /**
-         * Source of secure random data.
-         */
+        // Source of secure random data.
         private readonly SecureRandom random;
 
         private readonly BigInteger p;
         private readonly BigInteger q;
         private readonly BigInteger g;
 
-        /**
-         * The participantId of the other participant in this exchange.
-         */
+        // The participantId of the other participant in this exchange.
         private string partnerParticipantId;
 
-        /**
-         * Alice's x1 or Bob's x3.
-         */
+        // Alice's x1 or Bob's x3.
         private BigInteger x1;
-        /**
-         * Alice's x2 or Bob's x4.
-         */
+        // Alice's x2 or Bob's x4.
         private BigInteger x2;
-        /**
-         * Alice's g^x1 or Bob's g^x3.
-         */
+        // Alice's g^x1 or Bob's g^x3.
         private BigInteger gx1;
-        /**
-         * Alice's g^x2 or Bob's g^x4.
-         */
+        // Alice's g^x2 or Bob's g^x4.
         private BigInteger gx2;
-        /**
-         * Alice's g^x3 or Bob's g^x1.
-         */
+        // Alice's g^x3 or Bob's g^x1.
         private BigInteger gx3;
-        /**
-         * Alice's g^x4 or Bob's g^x2.
-         */
+        // Alice's g^x4 or Bob's g^x2.
         private BigInteger gx4;
-        /**
-         * Alice's B or Bob's A.
-         */
+        // Alice's B or Bob's A.
         private BigInteger b;
 
-        /**
-         * The current state.
-         * See the <tt>STATE_*</tt> constants for possible values.
-         */
+        // The current state.
+        // See the <tt>STATE_*</tt> constants for possible values.
         private int state;
 
-        /**
-         * Convenience constructor for a new {@link JPAKEParticipant} that uses
-         * the {@link JPAKEPrimeOrderGroups#NIST_3072} prime order group,
-         * a SHA-256 digest, and a default {@link SecureRandom} implementation.
-         * <p>
-         * After construction, the {@link #getState() state} will be  {@link #STATE_INITIALIZED}.
-         *
-         * @param participantId unique identifier of this participant.
-         *                      The two participants in the exchange must NOT share the same id.
-         * @param password      shared secret.
-         *                      A defensive copy of this array is made (and cleared once {@link #calculateKeyingMaterial()} is called).
-         *                      Caller should clear the input password as soon as possible.
-         * @throws NullReferenceException if any argument is null
-         * @throws ArgumentException if password is empty
-         */
+        /// Convenience constructor for a new JPAKEParticipant that uses
+        /// the JPAKEPrimeOrderGroups#NIST_3072 prime order group,
+        /// a SHA-256 digest, and a default SecureRandom implementation.
+        ///
+        /// After construction, the State state will be STATE_INITIALIZED.
+        /// 
+        /// Throws NullReferenceException if any argument is null. Throws
+        /// ArgumentException if password is empty.
+        /// </summary>
+        /// <param name="participantId">Unique identifier of this participant.
+        ///      The two participants in the exchange must NOT share the same id.</param>
+        /// <param name="password">Shared secret.
+        ///      A defensive copy of this array is made (and cleared once CalculateKeyingMaterial() is called).
+        ///      Caller should clear the input password as soon as possible.</param>
         public JPAKEParticipant(string participantId, char[] password)
             : this(participantId, password, JPAKEPrimeOrderGroups.NIST_3072) { }
 
-        /**
-         * Convenience constructor for a new {@link JPAKEParticipant} that uses
-         * a SHA-256 digest and a default {@link SecureRandom} implementation.
-         * <p>
-         * After construction, the {@link #getState() state} will be  {@link #STATE_INITIALIZED}.
-         *
-         * @param participantId unique identifier of this participant.
-         *                      The two participants in the exchange must NOT share the same id.
-         * @param password      shared secret.
-         *                      A defensive copy of this array is made (and cleared once {@link #calculateKeyingMaterial()} is called).
-         *                      Caller should clear the input password as soon as possible.
-         * @param group         prime order group.
-         *                      See {@link JPAKEPrimeOrderGroups} for standard groups
-         * @throws NullReferenceException if any argument is null
-         * @throws ArgumentException if password is empty
-         */
+        /// Convenience constructor for a new JPAKEParticipant that uses
+        /// the JPAKEPrimeOrderGroups#NIST_3072 prime order group,
+        /// a SHA-256 digest, and a default SecureRandom implementation.
+        ///
+        /// After construction, the State state will be STATE_INITIALIZED.
+        /// 
+        /// Throws NullReferenceException if any argument is null. Throws
+        /// ArgumentException if password is empty.
+        /// </summary>
+        /// <param name="participantId">Unique identifier of this participant.
+        ///      The two participants in the exchange must NOT share the same id.</param>
+        /// <param name="password">Shared secret.
+        ///      A defensive copy of this array is made (and cleared once CalculateKeyingMaterial() is called).
+        ///      Caller should clear the input password as soon as possible.</param>
+        /// <param name="group">Prime order group. See JPAKEPrimeOrderGroups for standard groups.</param>
         public JPAKEParticipant(string participantId, char[] password, JPAKEPrimeOrderGroup group)
             : this(participantId, password, group, new Sha256Digest(), new SecureRandom()) { }
 
 
-        /**
-         * Construct a new {@link JPAKEParticipant}.
-         * <p>
-         * After construction, the {@link #getState() state} will be  {@link #STATE_INITIALIZED}.
-         *
-         * @param participantId unique identifier of this participant.
-         *                      The two participants in the exchange must NOT share the same id.
-         * @param password      shared secret.
-         *                      A defensive copy of this array is made (and cleared once {@link #calculateKeyingMaterial()} is called).
-         *                      Caller should clear the input password as soon as possible.
-         * @param group         prime order group.
-         *                      See {@link JPAKEPrimeOrderGroups} for standard groups
-         * @param digest        digest to use during zero knowledge proofs and key confirmation (SHA-256 or stronger preferred)
-         * @param random        source of secure random data for x1 and x2, and for the zero knowledge proofs
-         * @throws NullReferenceException if any argument is null
-         * @throws IllegalArgumentException if password is empty
-         */
+        /// Convenience constructor for a new JPAKEParticipant that uses
+        /// the JPAKEPrimeOrderGroups#NIST_3072 prime order group,
+        /// a SHA-256 digest, and a default SecureRandom implementation.
+        ///
+        /// After construction, the State state will be STATE_INITIALIZED.
+        /// 
+        /// Throws NullReferenceException if any argument is null. Throws
+        /// ArgumentException if password is empty.
+        /// </summary>
+        /// <param name="participantId">Unique identifier of this participant.
+        ///      The two participants in the exchange must NOT share the same id.</param>
+        /// <param name="password">Shared secret.
+        ///      A defensive copy of this array is made (and cleared once CalculateKeyingMaterial() is called).
+        ///      Caller should clear the input password as soon as possible.</param>
+        /// <param name="group">Prime order group. See JPAKEPrimeOrderGroups for standard groups.</param>
+        /// <param name="digest">Digest to use during zero knowledge proofs and key confirmation
+        ///     (SHA-256 or stronger preferred).</param>
+        /// <param name="random">Source of secure random data for x1 and x2, and for the zero knowledge proofs.</param>
         public JPAKEParticipant(string participantId, char[] password, JPAKEPrimeOrderGroup group, IDigest digest, SecureRandom random)
         {
             JPAKEUtil.ValidateNotNull(participantId, "participantId");
@@ -210,18 +177,16 @@ namespace Org.BouncyCastle.Crypto.Agreement.Jpake
 
             this.participantId = participantId;
 
-            /*
-             * Create a defensive copy so as to fully encapsulate the password.
-             * 
-             * This array will contain the password for the lifetime of this
-             * participant BEFORE {@link #calculateKeyingMaterial()} is called.
-             * 
-             * i.e. When {@link #calculateKeyingMaterial()} is called, the array will be cleared
-             * in order to remove the password from memory.
-             * 
-             * The caller is responsible for clearing the original password array
-             * given as input to this constructor.
-             */
+            // Create a defensive copy so as to fully encapsulate the password.
+            // 
+            // This array will contain the password for the lifetime of this
+            // participant BEFORE CalculateKeyingMaterial() is called.
+            // 
+            // i.e. When CalculateKeyingMaterial() is called, the array will be cleared
+            // in order to remove the password from memory.
+            // 
+            // The caller is responsible for clearing the original password array
+            // given as input to this constructor.
             this.password = new char[password.Length];
             Array.Copy(password, this.password, password.Length);
 
@@ -235,21 +200,21 @@ namespace Org.BouncyCastle.Crypto.Agreement.Jpake
             this.state = STATE_INITIALIZED;
         }
 
-        /**
-         * Gets the current state of this participant.
-         * See the <tt>STATE_*</tt> constants for possible values.
-         */
+        /// <summary>
+        /// Gets the current state of this participant.
+        /// See the <tt>STATE_*</tt> constants for possible values.
+        /// </summary>
         public int State
         {
             get { return state; }
         }
 
 
-        /**
-         * Creates and returns the payload to send to the other participant during round 1.
-         * <p>
-         * After execution, the {@link #getState() state} will be  {@link #STATE_ROUND_1_CREATED}.
-         */
+        /// <summary>
+        /// Creates and returns the payload to send to the other participant during round 1.
+        ///
+        /// After execution, the State state} will be STATE_ROUND_1_CREATED}.
+        /// </summary>
         public JPAKERound1Payload CreateRound1PayloadToSend()
         {
             if (this.state >= STATE_ROUND_1_CREATED)
@@ -270,16 +235,15 @@ namespace Org.BouncyCastle.Crypto.Agreement.Jpake
             return new JPAKERound1Payload(participantId, gx1, gx2, knowledgeProofForX1, knowledgeProofForX2);
         }
 
-        /**
-         * Validates the payload received from the other participant during round 1.
-         * <p>
-         * Must be called prior to {@link #createRound2PayloadToSend()}.
-         * <p>
-         * After execution, the {@link #getState() state} will be  {@link #STATE_ROUND_1_VALIDATED}.
-         *
-         * @throws CryptoException if validation fails.
-         * @throws InvalidOperationException if called multiple times.
-         */
+        /// <summary>
+        /// Validates the payload received from the other participant during round 1.
+        ///
+        /// Must be called prior to CreateRound2PayloadToSend().
+        ///
+        /// After execution, the State state will be  STATE_ROUND_1_VALIDATED.
+        /// Throws CryptoException if validation fails. Throws InvalidOperationException
+        /// if called multiple times.
+        /// </summary>
         public void ValidateRound1PayloadReceived(JPAKERound1Payload round1PayloadReceived)
         {
             if (this.state >= STATE_ROUND_1_VALIDATED)
@@ -297,20 +261,19 @@ namespace Org.BouncyCastle.Crypto.Agreement.Jpake
             JPAKEUtil.ValidateParticipantIdsDiffer(participantId, round1PayloadReceived.ParticipantId);
             JPAKEUtil.ValidateGx4(gx4);
             JPAKEUtil.ValidateZeroKnowledgeProof(p, q, g, gx3, knowledgeProofForX3, round1PayloadReceived.ParticipantId, digest);
-            JPAKEUtil.ValidateZeroKnowledgeProof(p, q, g, gx4, knowledgeProofForX4, round1PayloadReceived.ParticipantId, digest);
-
+            JPAKEUtil.ValidateZeroKnowledgeProof(p, q, g, gx4, knowledgeProofForX4, round1PayloadReceived.ParticipantId, digest); 
             this.state = STATE_ROUND_1_VALIDATED;
         }
 
-        /**
-         * Creates and returns the payload to send to the other participant during round 2.
-         * <p>
-         * {@link #validateRound1PayloadReceived(JPAKERound1Payload)} must be called prior to this method.
-         * <p>
-         * After execution, the {@link #getState() state} will be  {@link #STATE_ROUND_2_CREATED}.
-         *
-         * @throws InvalidOperationException if called prior to {@link #validateRound1PayloadReceived(JPAKERound1Payload)}, or multiple times
-         */
+        /// <summary>
+        /// Creates and returns the payload to send to the other participant during round 2.
+        ///
+        /// ValidateRound1PayloadReceived(JPAKERound1Payload)} must be called prior to this method.
+        ///
+        //// After execution, the State state will be  STATE_ROUND_2_CREATED.
+        ///
+        /// Throws InvalidOperationException if called prior to ValidateRound1PayloadReceived(JPAKERound1Payload)}, or multiple times
+        /// </summary>
         public JPAKERound2Payload CreateRound2PayloadToSend()
         {
             if (this.state >= STATE_ROUND_2_CREATED)
@@ -333,20 +296,19 @@ namespace Org.BouncyCastle.Crypto.Agreement.Jpake
             return new JPAKERound2Payload(participantId, A, knowledgeProofForX2s);
         }
 
-        /**
-         * Validates the payload received from the other participant during round 2.
-         * <p>
-         * Note that this DOES NOT detect a non-common password.
-         * The only indication of a non-common password is through derivation
-         * of different keys (which can be detected explicitly by executing round 3 and round 4)
-         * <p>
-         * Must be called prior to {@link #calculateKeyingMaterial()}.
-         * <p>
-         * After execution, the {@link #getState() state} will be  {@link #STATE_ROUND_2_VALIDATED}.
-         *
-         * @throws CryptoException if validation fails.
-         * @throws InvalidOperationException if called prior to {@link #validateRound1PayloadReceived(JPAKERound1Payload)}, or multiple times
-         */
+        /// <summary>
+        /// Validates the payload received from the other participant during round 2.
+        /// Note that this DOES NOT detect a non-common password.
+        /// The only indication of a non-common password is through derivation
+        /// of different keys (which can be detected explicitly by executing round 3 and round 4)
+        ///
+        /// Must be called prior to CalculateKeyingMaterial().
+        ///
+        /// After execution, the State state will be  STATE_ROUND_2_VALIDATED.
+        ///
+        /// Throws CryptoException if validation fails. Throws
+        /// InvalidOperationException if called prior to ValidateRound1PayloadReceived(JPAKERound1Payload), or multiple times
+        /// </summary>
         public void ValidateRound2PayloadReceived(JPAKERound2Payload round2PayloadReceived)
         {
             if (this.state >= STATE_ROUND_2_VALIDATED)
@@ -370,31 +332,31 @@ namespace Org.BouncyCastle.Crypto.Agreement.Jpake
             this.state = STATE_ROUND_2_VALIDATED;
         }
 
-        /**
-         * Calculates and returns the key material.
-         * A session key must be derived from this key material using a secure key derivation function (KDF).
-         * The KDF used to derive the key is handled externally (i.e. not by {@link JPAKEParticipant}).
-         * <p>
-         * The keying material will be identical for each participant if and only if
-         * each participant's password is the same.  i.e. If the participants do not
-         * share the same password, then each participant will derive a different key.
-         * Therefore, if you immediately start using a key derived from
-         * the keying material, then you must handle detection of incorrect keys.
-         * If you want to handle this detection explicitly, you can optionally perform
-         * rounds 3 and 4.  See {@link JPAKEParticipant} for details on how to execute
-         * rounds 3 and 4.
-         * <p>
-         * The keying material will be in the range <tt>[0, p-1]</tt>.
-         * <p>
-         * {@link #validateRound2PayloadReceived(JPAKERound2Payload)} must be called prior to this method.
-         * <p>
-         * As a side effect, the internal {@link #password} array is cleared, since it is no longer needed.
-         * <p>
-         * After execution, the {@link #getState() state} will be  {@link #STATE_KEY_CALCULATED}.
-         *
-         * @throws InvalidOperationException if called prior to {@link #validateRound2PayloadReceived(JPAKERound2Payload)},
-         * or if called multiple times.
-         */
+        /// <summary>
+        /// Calculates and returns the key material.
+        /// A session key must be derived from this key material using a secure key derivation function (KDF).
+        /// The KDF used to derive the key is handled externally (i.e. not by JPAKEParticipant).
+        ///
+        /// The keying material will be identical for each participant if and only if
+        /// each participant's password is the same.  i.e. If the participants do not
+        /// share the same password, then each participant will derive a different key.
+        /// Therefore, if you immediately start using a key derived from
+        /// the keying material, then you must handle detection of incorrect keys.
+        /// If you want to handle this detection explicitly, you can optionally perform
+        /// rounds 3 and 4.  See JPAKEParticipant for details on how to execute
+        /// rounds 3 and 4.
+        ///
+        /// The keying material will be in the range <tt>[0, p-1]</tt>.
+        ///
+        /// ValidateRound2PayloadReceived(JPAKERound2Payload) must be called prior to this method.
+        /// 
+        /// As a side effect, the internal password array is cleared, since it is no longer needed.
+        ///
+        /// After execution, the State state will be STATE_KEY_CALCULATED.
+        ///
+        /// Throws InvalidOperationException if called prior to ValidateRound2PayloadReceived(JPAKERound2Payload),
+        /// or if called multiple times.
+        /// </summary>
         public BigInteger CalculateKeyingMaterial()
         {
             if (this.state >= STATE_KEY_CALCULATED)
@@ -408,47 +370,40 @@ namespace Org.BouncyCastle.Crypto.Agreement.Jpake
 
             BigInteger s = JPAKEUtil.CalculateS(password);
 
-            /*
-             * Clear the password array from memory, since we don't need it anymore.
-             * 
-             * Also set the field to null as a flag to indicate that the key has already been calculated.
-             */
+            // Clear the password array from memory, since we don't need it anymore.
+            // Also set the field to null as a flag to indicate that the key has already been calculated.
             Array.Clear(password, 0, password.Length);
             this.password = null;
 
             BigInteger keyingMaterial = JPAKEUtil.CalculateKeyingMaterial(p, q, gx4, x2, s, b);
 
-            /*
-             * Clear the ephemeral private key fields as well.
-             * Note that we're relying on the garbage collector to do its job to clean these up.
-             * The old objects will hang around in memory until the garbage collector destroys them.
-             * 
-             * If the ephemeral private keys x1 and x2 are leaked,
-             * the attacker might be able to brute-force the password.
-             */
+            // Clear the ephemeral private key fields as well.
+            // Note that we're relying on the garbage collector to do its job to clean these up.
+            // The old objects will hang around in memory until the garbage collector destroys them.
+            // 
+            // If the ephemeral private keys x1 and x2 are leaked,
+            // the attacker might be able to brute-force the password.
             this.x1 = null;
             this.x2 = null;
             this.b = null;
 
-            /* 
-             * Do not clear gx* yet, since those are needed by round 3.
-             */
+            // Do not clear gx* yet, since those are needed by round 3.
 
             this.state = STATE_KEY_CALCULATED;
 
             return keyingMaterial;
         }
 
-        /**
-         * Creates and returns the payload to send to the other participant during round 3.
-         * <p>
-         * See {@link JPAKEParticipant} for more details on round 3.
-         * <p>
-         * After execution, the {@link #getState() state} will be  {@link #STATE_ROUND_3_CREATED}.
-         *
-         * @param keyingMaterial The keying material as returned from {@link #calculateKeyingMaterial()}.
-         * @throws InvalidOperationException if called prior to {@link #calculateKeyingMaterial()}, or multiple times
-         */
+        /// <summary>
+        /// Creates and returns the payload to send to the other participant during round 3.
+        ///
+        /// See JPAKEParticipant for more details on round 3.
+        ///
+        /// After execution, the State state} will be  STATE_ROUND_3_CREATED.
+        /// Throws InvalidOperationException if called prior to CalculateKeyingMaterial, or multiple
+        /// times.
+        /// </summary>
+        /// <param name="keyingMaterial">The keying material as returned from CalculateKeyingMaterial().</param> 
         public JPAKERound3Payload CreateRound3PayloadToSend(BigInteger keyingMaterial)
         {
             if (this.state >= STATE_ROUND_3_CREATED)
@@ -475,17 +430,16 @@ namespace Org.BouncyCastle.Crypto.Agreement.Jpake
             return new JPAKERound3Payload(participantId, macTag);
         }
 
-        /**
-         * Validates the payload received from the other participant during round 3.
-         * <p>
-         * See {@link JPAKEParticipant} for more details on round 3.
-         * <p>
-         * After execution, the {@link #getState() state} will be {@link #STATE_ROUND_3_VALIDATED}.
-         *
-         * @param keyingMaterial The keying material as returned from {@link #calculateKeyingMaterial()}.
-         * @throws CryptoException if validation fails.
-         * @throws InvalidOperationException if called prior to {@link #calculateKeyingMaterial()}, or multiple times
-         */
+        /// <summary>
+        /// Validates the payload received from the other participant during round 3.
+        ///
+        /// See JPAKEParticipant for more details on round 3.
+        ///
+        /// After execution, the State state will be STATE_ROUND_3_VALIDATED.
+        /// Throws CryptoException if validation fails. Throws InvalidOperationException if called prior to
+        /// CalculateKeyingMaterial or multiple times
+        /// </summary>
+        /// <param name="keyingMaterial">The keying material as returned from CalculateKeyingMaterial().</param> 
         public void ValidateRound3PayloadReceived(JPAKERound3Payload round3PayloadReceived, BigInteger keyingMaterial)
         {
             if (this.state >= STATE_ROUND_3_VALIDATED)
@@ -511,9 +465,7 @@ namespace Org.BouncyCastle.Crypto.Agreement.Jpake
                 this.digest,
                 round3PayloadReceived.MacTag);
 
-            /*
-             * Clear the rest of the fields.
-             */
+            // Clear the rest of the fields.
             this.gx1 = null;
             this.gx2 = null;
             this.gx3 = null;
diff --git a/crypto/src/crypto/agreement/jpake/JPAKEPrimeOrderGroup.cs b/crypto/src/crypto/agreement/jpake/JPAKEPrimeOrderGroup.cs
index 1b0c514bb..3a142f713 100755
--- a/crypto/src/crypto/agreement/jpake/JPAKEPrimeOrderGroup.cs
+++ b/crypto/src/crypto/agreement/jpake/JPAKEPrimeOrderGroup.cs
@@ -4,62 +4,59 @@ using Org.BouncyCastle.Math;
 
 namespace Org.BouncyCastle.Crypto.Agreement.Jpake
 {
-    /**
-     * A pre-computed prime order group for use during a J-PAKE exchange.
-     * <p>
-     * Typically a Schnorr group is used.  In general, J-PAKE can use any prime order group
-     * that is suitable for public key cryptography, including elliptic curve cryptography.
-     * <p>
-     * See {@link JPAKEPrimeOrderGroups} for convenient standard groups.
-     * <p>
-     * NIST <a href="http://csrc.nist.gov/groups/ST/toolkit/documents/Examples/DSA2_All.pdf">publishes</a>
-     * many groups that can be used for the desired level of security.
-     */
+    /// <summary>
+    /// A pre-computed prime order group for use during a J-PAKE exchange.
+    ///
+    /// Typically a Schnorr group is used.  In general, J-PAKE can use any prime order group
+    /// that is suitable for public key cryptography, including elliptic curve cryptography.
+    ///
+    /// See JPAKEPrimeOrderGroups for convenient standard groups.
+    ///
+    /// NIST <a href="http://csrc.nist.gov/groups/ST/toolkit/documents/Examples/DSA2_All.pdf">publishes</a>
+    /// many groups that can be used for the desired level of security.
+    /// </summary>
     public class JPAKEPrimeOrderGroup
     {
         private readonly BigInteger p;
         private readonly BigInteger q;
         private readonly BigInteger g;
 
-        /**
-         * Constructs a new {@link JPAKEPrimeOrderGroup}.
-         * <p>
-         * In general, you should use one of the pre-approved groups from
-         * {@link JPAKEPrimeOrderGroups}, rather than manually constructing one.
-         * <p>
-         * The following basic checks are performed:
-         * <ul>
-         * <li>p-1 must be evenly divisible by q</li>
-         * <li>g must be in [2, p-1]</li>
-         * <li>g^q mod p must equal 1</li>
-         * <li>p must be prime (within reasonably certainty)</li>
-         * <li>q must be prime (within reasonably certainty)</li>
-         * </ul>
-         * <p>
-         * The prime checks are performed using {@link BigInteger#isProbablePrime(int)},
-         * and are therefore subject to the same probability guarantees.
-         * <p>
-         * These checks prevent trivial mistakes.
-         * However, due to the small uncertainties if p and q are not prime,
-         * advanced attacks are not prevented.
-         * Use it at your own risk.
-         *
-         * @throws NullReferenceException if any argument is null
-         * @throws InvalidOperationException if any of the above validations fail
-         */
+        /// <summary>
+        /// Constructs a new JPAKEPrimeOrderGroup.
+        ///
+        /// In general, you should use one of the pre-approved groups from
+        /// JPAKEPrimeOrderGroups, rather than manually constructing one.
+        ///
+        /// The following basic checks are performed:
+        ///
+        /// p-1 must be evenly divisible by q
+        /// g must be in [2, p-1]
+        /// g^q mod p must equal 1
+        /// p must be prime (within reasonably certainty)
+        /// q must be prime (within reasonably certainty)
+        ///
+        /// The prime checks are performed using BigInteger#isProbablePrime(int),
+        /// and are therefore subject to the same probability guarantees.
+        ///
+        /// These checks prevent trivial mistakes.
+        /// However, due to the small uncertainties if p and q are not prime,
+        /// advanced attacks are not prevented.
+        /// Use it at your own risk.
+        /// 
+        /// Throws NullReferenceException if any argument is null. Throws
+        /// InvalidOperationException is any of the above validations fail.
+        /// </summary>
         public JPAKEPrimeOrderGroup(BigInteger p, BigInteger q, BigInteger g)
             : this(p, q, g, false)
         {
-            /*
-             * Don't skip the checks on user-specified groups.
-             */
+             // Don't skip the checks on user-specified groups.
         }
 
-        /**
-         * Internal package-private constructor used by the pre-approved
-         * groups in {@link JPAKEPrimeOrderGroups}.
-         * These pre-approved groups can avoid the expensive checks.
-         */
+        /// <summary>
+        /// Constructor used by the pre-approved groups in JPAKEPrimeOrderGroups.
+        /// These pre-approved groups can avoid the expensive checks.
+        /// User-specified groups should not use this constructor.
+        /// </summary>
         public JPAKEPrimeOrderGroup(BigInteger p, BigInteger q, BigInteger g, bool skipChecks)
         {
             JPAKEUtil.ValidateNotNull(p, "p");
@@ -80,10 +77,8 @@ namespace Org.BouncyCastle.Crypto.Agreement.Jpake
                 {
                     throw new ArgumentException("g^q mod p must equal 1");
                 }
-                /*
-                 * Note these checks do not guarantee that p and q are prime.
-                 * We just have reasonable certainty that they are prime.
-                 */
+                // Note these checks do not guarantee that p and q are prime.
+                // We just have reasonable certainty that they are prime.
                 if (!p.IsProbablePrime(20))
                 {
                     throw new ArgumentException("p must be prime");