Top Description Fields Constructors Methods
org.bouncycastle.crypto.agreement.ecjpake

public Class ECJPAKEUtil

extends Object
Class Inheritance
Imports
java.math.BigInteger, java.security.SecureRandom, org.bouncycastle.crypto.CryptoException, .Digest, .Mac, org.bouncycastle.crypto.macs.HMac, org.bouncycastle.crypto.params.KeyParameter, org.bouncycastle.math.ec.ECCurve, .ECPoint, org.bouncycastle.util.Arrays, .BigIntegers, .Strings
Primitives needed for a EC J-PAKE exchange.

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

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

Field Summary

Modifier and TypeField and Description
pack-priv static final BigInteger
ONE

pack-priv static final BigInteger
ZERO

Constructor Summary

AccessConstructor and Description
public
ECJPAKEUtil()

Method Summary

Modifier and TypeMethod and Description
public static ECPoint
calculateA(ECPoint gA, BigInteger x2s)

Calculate A as done in round 2.

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

Calculate ga as done in round 2.

public static ECPoint
calculateGx(ECPoint g, BigInteger x)

Calculate g^x as done in round 1.

private static BigInteger
calculateHashForZeroKnowledgeProof(ECPoint g, ECPoint v, ECPoint x, String participantId, Digest digest)

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

Calculates the keying material, which can be done after round 2 has completed.

private static byte[]
calculateMacKey(BigInteger keyingMaterial, Digest digest)

Calculates the MacKey (i.e. the key to use when calculating the MagTag for key confirmation).

public static BigInteger
calculateMacTag(String participantId, String partnerParticipantId, ECPoint gx1, ECPoint gx2, ECPoint gx3, ECPoint gx4, 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.

public static BigInteger
calculateS(BigInteger n, byte[] password)

Converts the given password to a BigInteger mod n.

public static BigInteger
calculateS(BigInteger n, char[] password)

Converts the given password to a BigInteger mod n.

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

Calculate x2 * s as done in round 2.

public static ECSchnorrZKP
calculateZeroKnowledgeProof(ECPoint generator, BigInteger n, BigInteger x, ECPoint X, Digest digest, String userID, SecureRandom random)

Calculate a zero knowledge proof of x using Schnorr's signature.

public static BigInteger
generateX1(BigInteger n, SecureRandom random)

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

private static byte[]
intToByteArray(int value)

private static void
updateDigest(Digest digest, ECPoint ecPoint)

private static void
updateDigest(Digest digest, String string)

private static void
updateDigest(Digest digest, BigInteger bigInteger)

private static void
updateDigestIncludingSize(Digest digest, ECPoint ecPoint)

private static void
updateDigestIncludingSize(Digest digest, String string)

private static void
updateMac(Mac mac, ECPoint ecPoint)

private static void
updateMac(Mac mac, String string)

public static void
validateMacTag(String participantId, String partnerParticipantId, ECPoint gx1, ECPoint gx2, ECPoint gx3, ECPoint gx4, BigInteger keyingMaterial, Digest digest, BigInteger
the MacTag received from the partner.
partnerMacTag)

Validates the MacTag received from the partner participant.

public static void
validateNotNull(Object
object in question
object, String
name of the object (to be used in exception message)
description)

Validates that the given object is not null.

public static void
validateParticipantIdsDiffer(String participantId1, String participantId2)

Validates that the given participant ids are not equal.

public static void
validateParticipantIdsEqual(String expectedParticipantId, String actualParticipantId)

Validates that the given participant ids are equal.

public static void
validateZeroKnowledgeProof(ECPoint generator, ECPoint X, ECSchnorrZKP zkp, BigInteger q, BigInteger n, ECCurve curve, BigInteger coFactor, String userID, Digest digest)

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

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

ONEback to summary
pack-priv static final BigInteger ONE
ZEROback to summary
pack-priv static final BigInteger ZERO

Constructor Detail

ECJPAKEUtilback to summary
public ECJPAKEUtil()

Method Detail

calculateAback to summary
public static ECPoint calculateA(ECPoint gA, BigInteger x2s)

Calculate A as done in round 2.

calculateGAback to summary
public static ECPoint calculateGA(ECPoint gx1, ECPoint gx3, ECPoint gx4)

Calculate ga as done in round 2.

calculateGxback to summary
public static ECPoint calculateGx(ECPoint g, BigInteger x)

Calculate g^x as done in round 1.

calculateHashForZeroKnowledgeProofback to summary
private static BigInteger calculateHashForZeroKnowledgeProof(ECPoint g, ECPoint v, ECPoint x, String participantId, Digest digest)
calculateKeyingMaterialback to summary
public static BigInteger calculateKeyingMaterial(BigInteger n, ECPoint gx4, BigInteger x2, 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
calculateMacKeyback to summary
private static byte[] calculateMacKey(BigInteger keyingMaterial, Digest digest)

Calculates the MacKey (i.e. the key to use when calculating the MagTag for key confirmation). 

MacKey = H(K || "ECJPAKE_KC")
calculateMacTagback to summary
public static BigInteger calculateMacTag(String participantId, String partnerParticipantId, ECPoint gx1, ECPoint gx2, ECPoint gx3, ECPoint gx4, 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
calculateSback to summary
public static BigInteger calculateS(BigInteger n, byte[] password) throws CryptoException

Converts the given password to a BigInteger mod n.

calculateSback to summary
public static BigInteger calculateS(BigInteger n, char[] password) throws CryptoException

Converts the given password to a BigInteger mod n.

calculateX2sback to summary
public static BigInteger calculateX2s(BigInteger n, BigInteger x2, BigInteger s)

Calculate x2 * s as done in round 2.

calculateZeroKnowledgeProofback to summary
public static ECSchnorrZKP calculateZeroKnowledgeProof(ECPoint generator, BigInteger n, BigInteger x, ECPoint X, Digest digest, String userID, 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.

generateX1back to summary
public static BigInteger generateX1(BigInteger n, 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].

intToByteArrayback to summary
private static byte[] intToByteArray(int value)
updateDigestback to summary
private static void updateDigest(Digest digest, ECPoint ecPoint)
updateDigestback to summary
private static void updateDigest(Digest digest, String string)
updateDigestback to summary
private static void updateDigest(Digest digest, BigInteger bigInteger)
updateDigestIncludingSizeback to summary
private static void updateDigestIncludingSize(Digest digest, ECPoint ecPoint)
updateDigestIncludingSizeback to summary
private static void updateDigestIncludingSize(Digest digest, String string)
updateMacback to summary
private static void updateMac(Mac mac, ECPoint ecPoint)
updateMacback to summary
private static void updateMac(Mac mac, String string)
validateMacTagback to summary
public static void validateMacTag(String participantId, String partnerParticipantId, ECPoint gx1, ECPoint gx2, ECPoint gx3, ECPoint gx4, BigInteger keyingMaterial, Digest digest, BigInteger partnerMacTag) throws CryptoException

Validates the MacTag received from the partner participant.

Parameters
partnerMacTag:BigInteger

the MacTag received from the partner.

Exceptions
CryptoException:
if the participantId strings are equal.
validateNotNullback to summary
public static void validateNotNull(Object object, String description)

Validates that the given object is not null.

Parameters
object:Object

object in question

description:String

name of the object (to be used in exception message)

Exceptions
NullPointerException:
if the object is null.
validateParticipantIdsDifferback to summary
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.)

Exceptions
CryptoException:
if the participantId strings are equal.
validateParticipantIdsEqualback to summary
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.

Exceptions
CryptoException:
if the participantId strings are equal.
validateZeroKnowledgeProofback to summary
public static void validateZeroKnowledgeProof(ECPoint generator, ECPoint X, ECSchnorrZKP zkp, BigInteger q, BigInteger n, ECCurve curve, BigInteger coFactor, String userID, Digest digest) throws CryptoException

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

Exceptions
CryptoException:
if the zero knowledge proof is not correct