Class JPAKEUtil

java.lang.Object

org.bouncycastle.crypto.agreement.jpake.JPAKEUtil

public class JPAKEUtil
extends Object

Primitives needed for a J-PAKE exchange.

The recommended way to perform a J-PAKE exchange is by using two JPAKEParticipants. Internally, those participants call these primitive operations in JPAKEUtil.

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

Constructor Summary

Constructors

Constructor	Description
JPAKEUtil()

Method Summary

Modifier and Type	Method	Description
static BigInteger	calculateA(BigInteger p, BigInteger q, BigInteger gA, BigInteger x2s)	Calculate A as done in round 2.
static BigInteger	calculateA(BigInteger p, BigInteger q, BigInteger gA, BigInteger x2s, SecureRandom random)	Calculate A as done in round 2.
static BigInteger	calculateGA(BigInteger p, BigInteger gx1, BigInteger gx3, BigInteger gx4)	Calculate ga as done in round 2.
static BigInteger	calculateGx(BigInteger p, BigInteger g, BigInteger x)	Deprecated. x is a private ephemeral value, and this method has no q to randomise the exponent with, so it falls back to a multiple of p-1 - always sound, but it grows the exponent from the size of q to the size of p.
static BigInteger	calculateGx(BigInteger p, BigInteger q, BigInteger g, BigInteger x, SecureRandom random)	Calculate g^x mod p as done in round 1.
static BigInteger	calculateKeyingMaterial(BigInteger p, BigInteger q, BigInteger gx4, BigInteger x2, BigInteger s, BigInteger B)	Calculates the keying material, which can be done after round 2 has completed.
static BigInteger	calculateKeyingMaterial(BigInteger p, BigInteger q, BigInteger gx4, BigInteger x2, BigInteger s, BigInteger B, SecureRandom random)	Calculates the keying material, which can be done after round 2 has completed.
static BigInteger	calculateMacTag(String participantId, String partnerParticipantId, BigInteger gx1, BigInteger gx2, BigInteger gx3, BigInteger gx4, BigInteger keyingMaterial, Digest digest)	Calculates the MacTag (to be used for key confirmation), as defined by NIST SP 800-56A Revision 1, Section 8.2 Unilateral Key Confirmation for Key Agreement Schemes.
static BigInteger	calculateS(char[] password)	Deprecated. Use version including the modulus instead.
static BigInteger	calculateS(BigInteger q, byte[] password)	Converts the given password to a BigInteger mod q.
static BigInteger	calculateS(BigInteger q, char[] password)	Converts the given password to a BigInteger mod q.
static BigInteger	calculateX2s(BigInteger q, BigInteger x2, BigInteger s)	Calculate x2 * s as done in round 2.
static BigInteger[]	calculateZeroKnowledgeProof(BigInteger p, BigInteger q, BigInteger g, BigInteger gx, BigInteger x, String participantId, Digest digest, SecureRandom random)	Calculate a zero knowledge proof of x using Schnorr's signature.
static BigInteger	generateX1(BigInteger q, SecureRandom random)	Return a value that can be used as x1 or x3 during round 1.
static BigInteger	generateX2(BigInteger q, SecureRandom random)	Return a value that can be used as x2 or x4 during round 1.
static void	validateGa(BigInteger ga)	Validates that ga is not 1.
static void	validateGx4(BigInteger gx4)	Validates that g^x4 is not 1.
static void	validateMacTag(String participantId, String partnerParticipantId, BigInteger gx1, BigInteger gx2, BigInteger gx3, BigInteger gx4, BigInteger keyingMaterial, Digest digest, BigInteger partnerMacTag)	Validates the MacTag received from the partner participant.
static void	validateNotNull(Object object, String description)	Validates that the given object is not null.
static void	validateParticipantIdsDiffer(String participantId1, String participantId2)	Validates that the given participant ids are not equal.
static void	validateParticipantIdsEqual(String expectedParticipantId, String actualParticipantId)	Validates that the given participant ids are equal.
static void	validateZeroKnowledgeProof(BigInteger p, BigInteger q, BigInteger g, BigInteger gx, BigInteger[] zeroKnowledgeProof, String participantId, Digest digest)	Validates the zero knowledge proof (generated by calculateZeroKnowledgeProof(BigInteger, BigInteger, BigInteger, BigInteger, BigInteger, String, Digest, SecureRandom)) is correct.

Methods inherited from class Object

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

Constructor Details

JPAKEUtil

public JPAKEUtil()

Method Details

generateX1

public static BigInteger generateX1(BigInteger q,
 SecureRandom random)

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

The returned value is a random value in the range [0, q-1].

generateX2

public static BigInteger generateX2(BigInteger q,
 SecureRandom random)

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

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

calculateS

public static BigInteger calculateS(char[] password)

Deprecated.

Use version including the modulus instead.

Converts the given password to a BigInteger for use in arithmetic calculations.

calculateS

public static BigInteger calculateS(BigInteger q,
 byte[] password)
                             throws CryptoException

Converts the given password to a BigInteger mod q.

Throws:

CryptoException

calculateS

public static BigInteger calculateS(BigInteger q,
 char[] password)
                             throws CryptoException

Converts the given password to a BigInteger mod q.

Throws:

CryptoException

calculateGx

public static BigInteger calculateGx(BigInteger p,
 BigInteger g,
 BigInteger x)

Deprecated.

x is a private ephemeral value, and this method has no q to randomise the exponent with, so it falls back to a multiple of p-1 - always sound, but it grows the exponent from the size of q to the size of p. Use calculateGx(BigInteger, BigInteger, BigInteger, BigInteger, SecureRandom) instead.

Calculate g^x mod p as done in round 1.

calculateGx

public static BigInteger calculateGx(BigInteger p,
 BigInteger q,
 BigInteger g,
 BigInteger x,
 SecureRandom random)

Calculate g^x mod p as done in round 1.

x is the participant's private ephemeral value; leaking it lets an attacker brute-force the password, so the exponent is randomised with a multiple of q before it is raised.

Parameters:

random - source of the randomisation, may be null to take the default from CryptoServicesRegistrar.

calculateGA

public static BigInteger calculateGA(BigInteger p,
 BigInteger gx1,
 BigInteger gx3,
 BigInteger gx4)

Calculate ga as done in round 2.

calculateX2s

public static BigInteger calculateX2s(BigInteger q,
 BigInteger x2,
 BigInteger s)

Calculate x2 * s as done in round 2.

calculateA

public static BigInteger calculateA(BigInteger p,
 BigInteger q,
 BigInteger gA,
 BigInteger x2s)

Calculate A as done in round 2.

calculateA

public static BigInteger calculateA(BigInteger p,
 BigInteger q,
 BigInteger gA,
 BigInteger x2s,
 SecureRandom random)

Calculate A as done in round 2.

x2s carries the password, so the exponent is randomised with a multiple of q before it is raised. gA is a product of values each checked to have order q, so it has order q too.

Parameters:

random - source of the randomisation, may be null to take the default from CryptoServicesRegistrar.

calculateZeroKnowledgeProof

public static BigInteger[] calculateZeroKnowledgeProof(BigInteger p,
 BigInteger q,
 BigInteger g,
 BigInteger gx,
 BigInteger x,
 String participantId,
 Digest digest,
 SecureRandom random)

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

validateGx4

public static void validateGx4(BigInteger gx4)
                        throws CryptoException

Validates that g^x4 is not 1.

Throws:

CryptoException - if g^x4 is 1

validateGa

public static void validateGa(BigInteger ga)
                       throws CryptoException

Validates that ga is not 1.

As described by Feng Hao...

Alice could simply check ga != 1 to ensure it is a generator. In fact, as we will explain in Section 3, (x1 + x3 + x4 ) is random over Zq even in the face of active attacks. Hence, the probability for ga = 1 is extremely small - on the order of 2^160 for 160-bit q.

Throws:

CryptoException - if ga is 1

validateZeroKnowledgeProof

public static void validateZeroKnowledgeProof(BigInteger p,
 BigInteger q,
 BigInteger g,
 BigInteger gx,
 BigInteger[] zeroKnowledgeProof,
 String participantId,
 Digest digest)
                                       throws CryptoException

Validates the zero knowledge proof (generated by calculateZeroKnowledgeProof(BigInteger, BigInteger, BigInteger, BigInteger, BigInteger, String, Digest, SecureRandom)) is correct.

Throws:

CryptoException - if the zero knowledge proof is not correct

calculateKeyingMaterial

public static BigInteger calculateKeyingMaterial(BigInteger p,
 BigInteger q,
 BigInteger gx4,
 BigInteger x2,
 BigInteger s,
 BigInteger 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 JPAKEParticipant).

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

calculateKeyingMaterial

public static BigInteger calculateKeyingMaterial(BigInteger p,
 BigInteger q,
 BigInteger gx4,
 BigInteger x2,
 BigInteger s,
 BigInteger B,
 SecureRandom random)

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 JPAKEParticipant).

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

One exponent carries the password and the other the private ephemeral x2, so both are randomised with a multiple of q before they are raised. gx4 and B have each been checked to have order q, so the product raised by the second call does too.

Parameters:

random - source of the randomisation, may be null to take the default from CryptoServicesRegistrar.

validateParticipantIdsDiffer

public static void validateParticipantIdsDiffer(String participantId1,
 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(String expectedParticipantId,
 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(Object object,
 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:

NullPointerException - if the object is null.

calculateMacTag

public static BigInteger calculateMacTag(String participantId,
 String partnerParticipantId,
 BigInteger gx1,
 BigInteger gx2,
 BigInteger gx3,
 BigInteger gx4,
 BigInteger keyingMaterial,
 Digest digest)

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

MacTag = HMAC(MacKey, MacLen, MacData)

MacKey = H(K || "JPAKE_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
MacLen = length of MacTag

validateMacTag

public static void validateMacTag(String participantId,
 String partnerParticipantId,
 BigInteger gx1,
 BigInteger gx2,
 BigInteger gx3,
 BigInteger gx4,
 BigInteger keyingMaterial,
 Digest digest,
 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.