org.bouncycastle.crypto.agreement.ecjpake

## Class ECJPAKEUtil

- java.lang.Object
- - org.bouncycastle.crypto.agreement.ecjpake.ECJPAKEUtil

-     public class ECJPAKEUtil
      extends java.lang.Object

  Primitives needed for a EC J-PAKE exchange.

  The recommended way to perform an EC J-PAKE exchange is by using two `ECJPAKEParticipant`s. Internally, those participants call these primitive operations in `ECJPAKEUtil`.

  The primitives, however, can be used without a `ECJPAKEParticipant` if needed.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ECJPAKEUtil()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static ECPoint` | `calculateA(ECPoint gA, java.math.BigInteger x2s)` Calculate A as done in round 2.
    `static ECPoint` | `calculateGA(ECPoint gx1, ECPoint gx3, ECPoint gx4)` Calculate ga as done in round 2.
    `static ECPoint` | `calculateGx(ECPoint g, java.math.BigInteger x)` Calculate g^x as done in round 1.
    `static java.math.BigInteger` | `calculateKeyingMaterial(java.math.BigInteger n, ECPoint gx4, java.math.BigInteger x2, java.math.BigInteger s, ECPoint B)` Calculates the keying material, which can be done after round 2 has completed.
    `static java.math.BigInteger` | `calculateMacTag(java.lang.String participantId, java.lang.String partnerParticipantId, ECPoint gx1, ECPoint gx2, ECPoint gx3, ECPoint gx4, java.math.BigInteger keyingMaterial, Digest digest)` Calculates the MacTag (to be used for key confirmation), as defined by NIST SP 800-56A Revision 3, Section 5.9.1 Unilateral Key Confirmation for Key Agreement Schemes.
    `static java.math.BigInteger` | `calculateS(java.math.BigInteger n, byte[] password)` Converts the given password to a `BigInteger` mod n.
    `static java.math.BigInteger` | `calculateS(java.math.BigInteger n, char[] password)` Converts the given password to a `BigInteger` mod n.
    `static java.math.BigInteger` | `calculateX2s(java.math.BigInteger n, java.math.BigInteger x2, java.math.BigInteger s)` Calculate x2 * s as done in round 2.
    `static ECSchnorrZKP` | `calculateZeroKnowledgeProof(ECPoint generator, java.math.BigInteger n, java.math.BigInteger x, ECPoint X, Digest digest, java.lang.String userID, java.security.SecureRandom random)` Calculate a zero knowledge proof of x using Schnorr's signature.
    `static java.math.BigInteger` | `generateX1(java.math.BigInteger n, java.security.SecureRandom random)` Return a value that can be used as x1, x2, x3 or x4 during round 1.
    `static void` | `validateMacTag(java.lang.String participantId, java.lang.String partnerParticipantId, ECPoint gx1, ECPoint gx2, ECPoint gx3, ECPoint gx4, java.math.BigInteger keyingMaterial, Digest digest, java.math.BigInteger partnerMacTag)` Validates the MacTag received from the partner participant.
    `static void` | `validateNotNull(java.lang.Object object, java.lang.String description)` Validates that the given object is not null.
    `static void` | `validateParticipantIdsDiffer(java.lang.String participantId1, java.lang.String participantId2)` Validates that the given participant ids are not equal.
    `static void` | `validateParticipantIdsEqual(java.lang.String expectedParticipantId, java.lang.String actualParticipantId)` Validates that the given participant ids are equal.
    `static void` | `validateZeroKnowledgeProof(ECPoint generator, ECPoint X, ECSchnorrZKP zkp, java.math.BigInteger q, java.math.BigInteger n, ECCurve curve, java.math.BigInteger coFactor, java.lang.String userID, Digest digest)` Validates the zero knowledge proof (generated by `calculateZeroKnowledgeProof(ECPoint, BigInteger, BigInteger, ECPoint, Digest, String, SecureRandom)`) is correct.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ECJPAKEUtil

          public ECJPAKEUtil()

  - ### Method Detail

    - #### generateX1

          public static java.math.BigInteger generateX1(java.math.BigInteger n,
                                                        java.security.SecureRandom random)

      Return a value that can be used as x1, x2, x3 or x4 during round 1.

      The returned value is a random value in the range `[1, n-1]`.

    - #### calculateS

          public static java.math.BigInteger calculateS(java.math.BigInteger n,
                                                        byte[] password)
                                                 throws CryptoException

      Converts the given password to a `BigInteger` mod n.
      Throws:
        `CryptoException`

    - #### calculateS

          public static java.math.BigInteger calculateS(java.math.BigInteger n,
                                                        char[] password)
                                                 throws CryptoException

      Converts the given password to a `BigInteger` mod n.
      Throws:
        `CryptoException`

    - #### calculateGx

          public static ECPoint calculateGx(ECPoint g,
                                            java.math.BigInteger x)

      Calculate g^x as done in round 1.

    - #### calculateGA

          public static ECPoint calculateGA(ECPoint gx1,
                                            ECPoint gx3,
                                            ECPoint gx4)

      Calculate ga as done in round 2.

    - #### calculateX2s

          public static java.math.BigInteger calculateX2s(java.math.BigInteger n,
                                                          java.math.BigInteger x2,
                                                          java.math.BigInteger s)

      Calculate x2 * s as done in round 2.

    - #### calculateA

          public static ECPoint calculateA(ECPoint gA,
                                           java.math.BigInteger x2s)

      Calculate A as done in round 2.

    - #### calculateZeroKnowledgeProof

          public static ECSchnorrZKP calculateZeroKnowledgeProof(ECPoint generator,
                                                                 java.math.BigInteger n,
                                                                 java.math.BigInteger x,
                                                                 ECPoint X,
                                                                 Digest digest,
                                                                 java.lang.String userID,
                                                                 java.security.SecureRandom random)

      Calculate a zero knowledge proof of x using Schnorr's signature. The returned object has two fields {g^v, r = v-x*h} for x.

    - #### validateZeroKnowledgeProof

          public static void validateZeroKnowledgeProof(ECPoint generator,
                                                        ECPoint X,
                                                        ECSchnorrZKP zkp,
                                                        java.math.BigInteger q,
                                                        java.math.BigInteger n,
                                                        ECCurve curve,
                                                        java.math.BigInteger coFactor,
                                                        java.lang.String userID,
                                                        Digest digest)
                                                 throws CryptoException

      Validates the zero knowledge proof (generated by `calculateZeroKnowledgeProof(ECPoint, BigInteger, BigInteger, ECPoint, Digest, String, SecureRandom)`) is correct.
      Throws:
        `CryptoException` - if the zero knowledge proof is not correct

    - #### validateParticipantIdsDiffer

          public static void validateParticipantIdsDiffer(java.lang.String participantId1,
                                                          java.lang.String participantId2)
                                                   throws CryptoException

      Validates that the given participant ids are not equal. (For the J-PAKE exchange, each participant must use a unique id.)
      Throws:
        `CryptoException` - if the participantId strings are equal.

    - #### validateParticipantIdsEqual

          public static void validateParticipantIdsEqual(java.lang.String expectedParticipantId,
                                                         java.lang.String actualParticipantId)
                                                  throws CryptoException

      Validates that the given participant ids are equal. This is used to ensure that the payloads received from each round all come from the same participant.
      Throws:
        `CryptoException` - if the participantId strings are equal.

    - #### validateNotNull

          public static void validateNotNull(java.lang.Object object,
                                             java.lang.String description)

      Validates that the given object is not null.
      Parameters:
        `object` - object in question
        `description` - name of the object (to be used in exception message)
      Throws:
        `java.lang.NullPointerException` - if the object is null.

    - #### calculateKeyingMaterial

          public static java.math.BigInteger calculateKeyingMaterial(java.math.BigInteger n,
                                                                     ECPoint gx4,
                                                                     java.math.BigInteger x2,
                                                                     java.math.BigInteger s,
                                                                     ECPoint B)

      Calculates the keying material, which can be done after round 2 has completed. 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 `ECJPAKEParticipant`).

           KeyingMaterial = (B/g^{x2*x4*s})^x2

    - #### calculateMacTag

          public static java.math.BigInteger calculateMacTag(java.lang.String participantId,
                                                             java.lang.String partnerParticipantId,
                                                             ECPoint gx1,
                                                             ECPoint gx2,
                                                             ECPoint gx3,
                                                             ECPoint gx4,
                                                             java.math.BigInteger keyingMaterial,
                                                             Digest digest)

      Calculates the MacTag (to be used for key confirmation), as defined by NIST SP 800-56A Revision 3, Section 5.9.1 Unilateral Key Confirmation for Key Agreement Schemes.

           MacTag = HMAC(MacKey, MacLen, MacData)

           MacKey = H(K || "ECJPAKE_KC")

           MacData = "KC_1_U" || participantId || partnerParticipantId || gx1 || gx2 || gx3 || gx4

           Note that both participants use "KC_1_U" because the sender of the round 3 message
           is always the initiator for key confirmation.

           HMAC = HMac used with the given Digest
           H = The given Digest
           MacOutputBits = MacTagBits, hence truncation function omitted.
           MacLen = length of MacTag

    - #### validateMacTag

          public static void validateMacTag(java.lang.String participantId,
                                            java.lang.String partnerParticipantId,
                                            ECPoint gx1,
                                            ECPoint gx2,
                                            ECPoint gx3,
                                            ECPoint gx4,
                                            java.math.BigInteger keyingMaterial,
                                            Digest digest,
                                            java.math.BigInteger partnerMacTag)
                                     throws CryptoException

      Validates the MacTag received from the partner participant.
      Parameters:
        `partnerMacTag` - the MacTag received from the partner.
      Throws:
        `CryptoException` - if the participantId strings are equal.