Bouncy Castle Cryptography Library 1.80 · org.bouncycastle.crypto.agreement.jpake.JPAKEParticipant

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 "Password Authenticated Key Exchange by Juggling, 2008."

The J-PAKE protocol is symmetric. There is no notion of a client or server, but rather just two participants. 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 NIST SP 800-56A Revision 1, 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).

Field Summary

Modifier and Type	Field and Description
private BigInteger	b Alice's B or Bob's A.
private final Digest	digest Digest to use during calculations.
private final BigInteger	g
private BigInteger	gx1 Alice's g^x1 or Bob's g^x3.
private BigInteger	gx2 Alice's g^x2 or Bob's g^x4.
private BigInteger	gx3 Alice's g^x3 or Bob's g^x1.
private BigInteger	gx4 Alice's g^x4 or Bob's g^x2.
private final BigInteger	p
private final String	participantId Unique identifier of this participant.
private String	partnerParticipantId The participantId of the other participant in this exchange.
private char[]	password Shared secret.
private final BigInteger	q
private final SecureRandom	random Source of secure random data.
private int	state The current state.
public static final int	STATE_INITIALIZED
public static final int	STATE_KEY_CALCULATED
public static final int	STATE_ROUND_1_CREATED
public static final int	STATE_ROUND_1_VALIDATED
public static final int	STATE_ROUND_2_CREATED
public static final int	STATE_ROUND_2_VALIDATED
public static final int	STATE_ROUND_3_CREATED
public static final int	STATE_ROUND_3_VALIDATED
private BigInteger	x1 Alice's x1 or Bob's x3.
private BigInteger	x2 Alice's x2 or Bob's x4.

Constructor Summary

Access	Constructor and Description
public	JPAKEParticipant(String unique identifier of this participant. The two participants in the exchange must NOT share the same id. participantId, char[] 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. password) Convenience constructor for a new `JPAKEParticipant` that uses the `JPAKEPrimeOrderGroups#NIST_3072` prime order group, a SHA-256 digest, and a default `SecureRandom` implementation.
public	JPAKEParticipant(String unique identifier of this participant. The two participants in the exchange must NOT share the same id. participantId, char[] 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. password, JPAKEPrimeOrderGroup prime order group. See `JPAKEPrimeOrderGroups` for standard groups group) Convenience constructor for a new `JPAKEParticipant` that uses a SHA-256 digest and a default `SecureRandom` implementation.
public	JPAKEParticipant(String unique identifier of this participant. The two participants in the exchange must NOT share the same id. participantId, char[] 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. password, JPAKEPrimeOrderGroup prime order group. See `JPAKEPrimeOrderGroups` for standard groups group, Digest digest to use during zero knowledge proofs and key confirmation (SHA-256 or stronger preferred) digest, SecureRandom source of secure random data for x1 and x2, and for the zero knowledge proofs random) Construct a new `JPAKEParticipant`.

Method Summary

Modifier and Type	Method and Description
public BigInteger	calculateKeyingMaterial() Calculates and returns the key material.
private BigInteger	calculateS()
public JPAKERound1Payload	createRound1PayloadToSend() Creates and returns the payload to send to the other participant during round 1.
public JPAKERound2Payload	createRound2PayloadToSend() Creates and returns the payload to send to the other participant during round 2.
public JPAKERound3Payload	createRound3PayloadToSend(BigInteger The keying material as returned from `calculateKeyingMaterial()`. keyingMaterial) Creates and returns the payload to send to the other participant during round 3.
public int	getState() Gets the current state of this participant.
public void	validateRound1PayloadReceived(JPAKERound1Payload round1PayloadReceived) Validates the payload received from the other participant during round 1.
public void	validateRound2PayloadReceived(JPAKERound2Payload round2PayloadReceived) Validates the payload received from the other participant during round 2.
public void	validateRound3PayloadReceived(JPAKERound3Payload The round 3 payload received from the other participant. round3PayloadReceived, BigInteger The keying material as returned from `calculateKeyingMaterial()`. keyingMaterial) Validates the payload received from the other participant during round 3.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

b	back to summary
private BigInteger b Alice's B or Bob's A.

digest	back to summary
private final Digest digest Digest to use during calculations.

g	back to summary
private final BigInteger g

gx1	back to summary
private BigInteger gx1 Alice's g^x1 or Bob's g^x3.

gx2	back to summary
private BigInteger gx2 Alice's g^x2 or Bob's g^x4.

gx3	back to summary
private BigInteger gx3 Alice's g^x3 or Bob's g^x1.

gx4	back to summary
private BigInteger gx4 Alice's g^x4 or Bob's g^x2.

p	back to summary
private final BigInteger p

participantId	back to summary
private final String participantId Unique identifier of this participant. The two participants in the exchange must NOT share the same id.

partnerParticipantId	back to summary
private String partnerParticipantId The participantId of the other participant in this exchange.

password back to summary

password	back to summary
private char[] password 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

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.

q	back to summary
private final BigInteger q

random	back to summary
private final SecureRandom random Source of secure random data.

state	back to summary
private int state The current state. See the `STATE_*` constants for possible values.

STATE_INITIALIZED	back to summary
public static final int STATE_INITIALIZED

STATE_KEY_CALCULATED	back to summary
public static final int STATE_KEY_CALCULATED

STATE_ROUND_1_CREATED	back to summary
public static final int STATE_ROUND_1_CREATED

STATE_ROUND_1_VALIDATED	back to summary
public static final int STATE_ROUND_1_VALIDATED

STATE_ROUND_2_CREATED	back to summary
public static final int STATE_ROUND_2_CREATED

STATE_ROUND_2_VALIDATED	back to summary
public static final int STATE_ROUND_2_VALIDATED

STATE_ROUND_3_CREATED	back to summary
public static final int STATE_ROUND_3_CREATED

STATE_ROUND_3_VALIDATED	back to summary
public static final int STATE_ROUND_3_VALIDATED

x1	back to summary
private BigInteger x1 Alice's x1 or Bob's x3.

x2	back to summary
private BigInteger x2 Alice's x2 or Bob's x4.

Constructor Detail

JPAKEParticipant back to summary

JPAKEParticipant	back to summary
public JPAKEParticipant(String participantId, char[] password) 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` will be `STATE_INITIALIZED`. Parameters participantId:String unique identifier of this participant. The two participants in the exchange must NOT share the same id. password:char[] 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. Exceptions NullPointerException: if any argument is null IllegalArgumentException: if password is empty

public JPAKEParticipant(String participantId, char[] password)

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 will be STATE_INITIALIZED.

Parameters

participantId:String: unique identifier of this participant. The two participants in the exchange must NOT share the same id.
password:char[]: 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.

Exceptions

NullPointerException:: if any argument is null
IllegalArgumentException:: if password is empty

JPAKEParticipant back to summary

JPAKEParticipant	back to summary
public JPAKEParticipant(String participantId, char[] password, JPAKEPrimeOrderGroup group) Convenience constructor for a new `JPAKEParticipant` that uses a SHA-256 digest and a default `SecureRandom` implementation. After construction, the `state` will be `STATE_INITIALIZED`. Parameters participantId:String unique identifier of this participant. The two participants in the exchange must NOT share the same id. password:char[] 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. group:JPAKEPrimeOrderGroup prime order group. See `JPAKEPrimeOrderGroups` for standard groups Exceptions NullPointerException: if any argument is null IllegalArgumentException: if password is empty

public JPAKEParticipant(String participantId, char[] password, JPAKEPrimeOrderGroup group)

Convenience constructor for a new JPAKEParticipant that uses a SHA-256 digest and a default SecureRandom implementation.

After construction, the state will be STATE_INITIALIZED.

Parameters

participantId:String: unique identifier of this participant. The two participants in the exchange must NOT share the same id.
password:char[]: 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.
group:JPAKEPrimeOrderGroup: prime order group. See JPAKEPrimeOrderGroups for standard groups

Exceptions

NullPointerException:: if any argument is null
IllegalArgumentException:: if password is empty

JPAKEParticipant back to summary

JPAKEParticipant	back to summary
public JPAKEParticipant(String participantId, char[] password, JPAKEPrimeOrderGroup group, Digest digest, SecureRandom random) Construct a new `JPAKEParticipant`. After construction, the `state` will be `STATE_INITIALIZED`. Parameters participantId:String unique identifier of this participant. The two participants in the exchange must NOT share the same id. password:char[] 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. group:JPAKEPrimeOrderGroup prime order group. See `JPAKEPrimeOrderGroups` for standard groups digest:Digest digest to use during zero knowledge proofs and key confirmation (SHA-256 or stronger preferred) random:SecureRandom source of secure random data for x1 and x2, and for the zero knowledge proofs Exceptions NullPointerException: if any argument is null IllegalArgumentException: if password is empty

public JPAKEParticipant(String participantId, char[] password, JPAKEPrimeOrderGroup group, Digest digest, SecureRandom random)

Construct a new JPAKEParticipant.

After construction, the state will be STATE_INITIALIZED.

Parameters

participantId:String: unique identifier of this participant. The two participants in the exchange must NOT share the same id.
password:char[]: 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.
group:JPAKEPrimeOrderGroup: prime order group. See JPAKEPrimeOrderGroups for standard groups
digest:Digest: digest to use during zero knowledge proofs and key confirmation (SHA-256 or stronger preferred)
random:SecureRandom: source of secure random data for x1 and x2, and for the zero knowledge proofs

Exceptions

NullPointerException:: if any argument is null
IllegalArgumentException:: if password is empty

Method Detail

calculateKeyingMaterial back to summary

calculateKeyingMaterial	back to summary
public BigInteger calculateKeyingMaterial() 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 `[0, p-1]`. `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` will be `STATE_KEY_CALCULATED`. Exceptions IllegalStateException: if called prior to `validateRound2PayloadReceived(JPAKERound2Payload)`, or if called multiple times.

public BigInteger calculateKeyingMaterial()

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 [0, p-1].

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 will be STATE_KEY_CALCULATED.

Exceptions

IllegalStateException:: if called prior to validateRound2PayloadReceived(JPAKERound2Payload), or if called multiple times.

calculateS	back to summary
private BigInteger calculateS()

createRound1PayloadToSend back to summary

createRound1PayloadToSend	back to summary
public JPAKERound1Payload createRound1PayloadToSend() Creates and returns the payload to send to the other participant during round 1. After execution, the `state` will be `STATE_ROUND_1_CREATED`.

public JPAKERound1Payload createRound1PayloadToSend()

Creates and returns the payload to send to the other participant during round 1.

After execution, the state will be STATE_ROUND_1_CREATED.

createRound2PayloadToSend back to summary

createRound2PayloadToSend	back to summary
public JPAKERound2Payload createRound2PayloadToSend() 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` will be `STATE_ROUND_2_CREATED`. Exceptions IllegalStateException: if called prior to `validateRound1PayloadReceived(JPAKERound1Payload)`, or multiple times

public JPAKERound2Payload createRound2PayloadToSend()

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 will be STATE_ROUND_2_CREATED.

Exceptions

IllegalStateException:: if called prior to validateRound1PayloadReceived(JPAKERound1Payload), or multiple times

createRound3PayloadToSend back to summary

createRound3PayloadToSend	back to summary
public JPAKERound3Payload createRound3PayloadToSend(BigInteger keyingMaterial) 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` will be `STATE_ROUND_3_CREATED`. Parameters keyingMaterial:BigInteger The keying material as returned from `calculateKeyingMaterial()`. Exceptions IllegalStateException: if called prior to `calculateKeyingMaterial()`, or multiple times

public JPAKERound3Payload createRound3PayloadToSend(BigInteger keyingMaterial)

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 will be STATE_ROUND_3_CREATED.

Parameters

keyingMaterial:BigInteger: The keying material as returned from calculateKeyingMaterial().

Exceptions

IllegalStateException:: if called prior to calculateKeyingMaterial(), or multiple times

getState	back to summary
public int getState() Gets the current state of this participant. See the `STATE_*` constants for possible values.

validateRound1PayloadReceived back to summary

validateRound1PayloadReceived	back to summary
public void validateRound1PayloadReceived(JPAKERound1Payload round1PayloadReceived) throws CryptoException Validates the payload received from the other participant during round 1. Must be called prior to `createRound2PayloadToSend()`. After execution, the `state` will be `STATE_ROUND_1_VALIDATED`. Exceptions CryptoException: if validation fails. IllegalStateException: if called multiple times.

public void validateRound1PayloadReceived(JPAKERound1Payload round1PayloadReceived) throws CryptoException

Validates the payload received from the other participant during round 1.

Must be called prior to createRound2PayloadToSend().

After execution, the state will be STATE_ROUND_1_VALIDATED.

Exceptions

CryptoException:: if validation fails.
IllegalStateException:: if called multiple times.

validateRound2PayloadReceived back to summary

validateRound2PayloadReceived	back to summary
public void validateRound2PayloadReceived(JPAKERound2Payload round2PayloadReceived) throws CryptoException 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` will be `STATE_ROUND_2_VALIDATED`. Exceptions CryptoException: if validation fails. IllegalStateException: if called prior to `validateRound1PayloadReceived(JPAKERound1Payload)`, or multiple times

public void validateRound2PayloadReceived(JPAKERound2Payload round2PayloadReceived) throws CryptoException

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 will be STATE_ROUND_2_VALIDATED.

Exceptions

CryptoException:: if validation fails.
IllegalStateException:: if called prior to validateRound1PayloadReceived(JPAKERound1Payload), or multiple times

validateRound3PayloadReceived back to summary

validateRound3PayloadReceived	back to summary
public void validateRound3PayloadReceived(JPAKERound3Payload round3PayloadReceived, BigInteger keyingMaterial) throws CryptoException Validates the payload received from the other participant during round 3. See `JPAKEParticipant` for more details on round 3. After execution, the `state` will be `STATE_ROUND_3_VALIDATED`. Parameters round3PayloadReceived:JPAKERound3Payload The round 3 payload received from the other participant. keyingMaterial:BigInteger The keying material as returned from `calculateKeyingMaterial()`. Exceptions CryptoException: if validation fails. IllegalStateException: if called prior to `calculateKeyingMaterial()`, or multiple times

public void validateRound3PayloadReceived(JPAKERound3Payload round3PayloadReceived, BigInteger keyingMaterial) throws CryptoException

Validates the payload received from the other participant during round 3.

See JPAKEParticipant for more details on round 3.

After execution, the state will be STATE_ROUND_3_VALIDATED.

Parameters

round3PayloadReceived:JPAKERound3Payload: The round 3 payload received from the other participant.
keyingMaterial:BigInteger: The keying material as returned from calculateKeyingMaterial().

Exceptions

CryptoException:: if validation fails.
IllegalStateException:: if called prior to calculateKeyingMaterial(), or multiple times

public Class JPAKEParticipant

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail