Class JPakeParticipant

Namespace

Org.BouncyCastle.Crypto.Agreement.JPake

Assembly

BouncyCastle.Cryptography.dll

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

public class JPakeParticipant

Inheritance

object

JPakeParticipant

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

JPakeParticipant(string, char[])

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.

public JPakeParticipant(string participantId, char[] password)

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.

JPakeParticipant(string, char[], JPakePrimeOrderGroup)

Convenience constructor for a new JPakeParticipant that uses 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.

public JPakeParticipant(string participantId, char[] password, JPakePrimeOrderGroup group)

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.

JPakeParticipant(string, char[], JPakePrimeOrderGroup, IDigest, SecureRandom)

Constructor for a new JPakeParticipant.

After construction, the State state will be STATE_INITIALIZED.

Throws NullReferenceException if any argument is null. Throws ArgumentException if password is empty.

public JPakeParticipant(string participantId, char[] password, JPakePrimeOrderGroup group, IDigest digest, SecureRandom random)

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 IDigest

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.

Fields

STATE_INITIALIZED

public static readonly int STATE_INITIALIZED

Field Value

int

STATE_KEY_CALCULATED

public static readonly int STATE_KEY_CALCULATED

Field Value

int

STATE_ROUND_1_CREATED

public static readonly int STATE_ROUND_1_CREATED

Field Value

int

STATE_ROUND_1_VALIDATED

public static readonly int STATE_ROUND_1_VALIDATED

Field Value

int

STATE_ROUND_2_CREATED

public static readonly int STATE_ROUND_2_CREATED

Field Value

int

STATE_ROUND_2_VALIDATED

public static readonly int STATE_ROUND_2_VALIDATED

Field Value

int

STATE_ROUND_3_CREATED

public static readonly int STATE_ROUND_3_CREATED

Field Value

int

STATE_ROUND_3_VALIDATED

public static readonly int STATE_ROUND_3_VALIDATED

Field Value

int

Properties

State

Gets the current state of this participant. See the STATE_* constants for possible values.

public virtual int State { get; }

Property Value

int

Methods

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

Throws InvalidOperationException if called prior to ValidateRound2PayloadReceived(JPakeRound2Payload), or if called multiple times.

public virtual BigInteger CalculateKeyingMaterial()

Returns

BigInteger

CreateRound1PayloadToSend()

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}.

public virtual JPakeRound1Payload CreateRound1PayloadToSend()

Returns

JPakeRound1Payload

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

Throws InvalidOperationException if called prior to ValidateRound1PayloadReceived(JPakeRound1Payload), or multiple times

public virtual JPakeRound2Payload CreateRound2PayloadToSend()

Returns

JPakeRound2Payload

CreateRound3PayloadToSend(BigInteger)

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.

public virtual JPakeRound3Payload CreateRound3PayloadToSend(BigInteger keyingMaterial)

Parameters

keyingMaterial BigInteger

The keying material as returned from CalculateKeyingMaterial().

Returns

JPakeRound3Payload

ValidateRound1PayloadReceived(JPakeRound1Payload)

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.

public virtual void ValidateRound1PayloadReceived(JPakeRound1Payload round1PayloadReceived)

Parameters

round1PayloadReceived JPakeRound1Payload

ValidateRound2PayloadReceived(JPakeRound2Payload)

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

public virtual void ValidateRound2PayloadReceived(JPakeRound2Payload round2PayloadReceived)

Parameters

round2PayloadReceived JPakeRound2Payload

ValidateRound3PayloadReceived(JPakeRound3Payload, BigInteger)

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

public virtual void ValidateRound3PayloadReceived(JPakeRound3Payload round3PayloadReceived, BigInteger keyingMaterial)

Parameters

round3PayloadReceived JPakeRound3Payload

The round 3 payload received from the other participant.

keyingMaterial BigInteger

The keying material as returned from CalculateKeyingMaterial().