Class OwlServer

java.lang.Object

org.bouncycastle.crypto.agreement.owl.OwlServer

public class OwlServer
extends Object

A server in the Elliptic Curve Owl key exchange protocol.

See OwlClient for more details about Owl.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	STATE_INITIALISED
static final int	STATE_KC_INITIALISED
static final int	STATE_KC_VALIDATED
static final int	STATE_KEY_CALCULATED
static final int	STATE_LOGIN_FINISHED
static final int	STATE_LOGIN_INITIALISED

Constructor Summary

Constructors

Constructor	Description
OwlServer(String serverId)	Convenience constructor for a new OwlServer that uses the OwlCurves.NIST_P256 elliptic curve, a SHA-256 digest, and a default SecureRandom implementation.
OwlServer(String serverId, OwlCurve curve)	Convenience constructor for a new OwlServer that uses a SHA-256 digest and a default SecureRandom implementation.
OwlServer(String serverId, OwlCurve curve, Digest digest, SecureRandom random)	Construct a new OwlServer.

Method Summary

Modifier and Type	Method	Description
void	authenticationServerEnd(OwlAuthenticationFinish authenticationFinish)	Validates the payload received from the client during the third pass of the Owl protocol.
OwlAuthenticationServerResponse	authenticationServerResponse(OwlAuthenticationInitiate authenticationInitiate, OwlFinishRegistration userLoginCredentials)	Validates the payload sent by OwlClient.authenticationInitiate() by OwlClient, and then creates a new OwlAuthenticationServerResponse payload and sends it to the OwlClient.
BigInteger	calculateKeyingMaterial()	Calculates and returns the key material.
int	getState()	Gets the current state of this server.
OwlKeyConfirmation	initiateKeyConfirmation(BigInteger keyingMaterial)	Creates and returns the payload to send to the client as part of Key Confirmation.
void	validateKeyConfirmation(OwlKeyConfirmation keyConfirmationPayload, BigInteger keyingMaterial)	Validates the payload received from the client as part of Key Confirmation.

Methods inherited from class Object

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

Field Details

STATE_INITIALISED

public static final int STATE_INITIALISED

See Also:

• Constant Field Values

STATE_LOGIN_INITIALISED

public static final int STATE_LOGIN_INITIALISED

See Also:

• Constant Field Values

STATE_LOGIN_FINISHED

public static final int STATE_LOGIN_FINISHED

See Also:

• Constant Field Values

STATE_KEY_CALCULATED

public static final int STATE_KEY_CALCULATED

See Also:

• Constant Field Values

STATE_KC_INITIALISED

public static final int STATE_KC_INITIALISED

See Also:

• Constant Field Values

STATE_KC_VALIDATED

public static final int STATE_KC_VALIDATED

See Also:

• Constant Field Values

Constructor Details

OwlServer

public OwlServer(String serverId)

Convenience constructor for a new OwlServer that uses the OwlCurves.NIST_P256 elliptic curve, a SHA-256 digest, and a default SecureRandom implementation.

After construction, the state will be STATE_INITIALISED.

Parameters:

serverId - unique identifier of this server. The server and client in the exchange must NOT share the same id.

Throws:

NullPointerException - if any argument is null

OwlServer

public OwlServer(String serverId,
 OwlCurve curve)

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

After construction, the state will be STATE_INITIALISED.

Parameters:

serverId - unique identifier of this server. The server and client in the exchange must NOT share the same id.

curve - elliptic curve See OwlCurves for standard curves.

Throws:

NullPointerException - if any argument is null

OwlServer

public OwlServer(String serverId,
 OwlCurve curve,
 Digest digest,
 SecureRandom random)

Construct a new OwlServer.

After construction, the state will be STATE_INITIALISED.

Parameters:

serverId - unique identifier of this server. The client and server in the exchange must NOT share the same id.

curve - elliptic curve See OwlCurves for standard curves

digest - digest to use during zero knowledge proofs and key confirmation (SHA-256 or stronger preferred)

random - source of secure random data for x3 and x4, and for the zero knowledge proofs

Throws:

NullPointerException - if any argument is null

Method Details

getState

public int getState()

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

Returns:

The state of the server

authenticationServerResponse

public OwlAuthenticationServerResponse authenticationServerResponse(OwlAuthenticationInitiate authenticationInitiate,
 OwlFinishRegistration userLoginCredentials)
                                                             throws CryptoException

Validates the payload sent by OwlClient.authenticationInitiate() by OwlClient, and then creates a new OwlAuthenticationServerResponse payload and sends it to the OwlClient.

Must be called prior to authenticationServerEnd(OwlAuthenticationFinish).

After execution, the state will be STATE_LOGIN_INITIALISED.

Parameters:

authenticationInitiate - payload sent by OwlClient.authenticationInitiate() to be validated and used for further calculation.

userLoginCredentials - comes from the server where it stored the user login credentials as part of the user login registration.

Returns:

OwlAuthenticationServerResponse

Throws:

CryptoException - if validation fails.

IllegalStateException - if called multiple times.

authenticationServerEnd

public void authenticationServerEnd(OwlAuthenticationFinish authenticationFinish)
                             throws CryptoException

Validates the payload received from the client during the third pass of the Owl protocol. Must be called prior to calculateKeyingMaterial().

After execution, the state will be STATE_LOGIN_FINISHED.

Parameters:

authenticationFinish - payload sent by OwlClient.authenticationFinish(OwlAuthenticationServerResponse) to be validated.

Throws:

CryptoException - if validation fails.

IllegalStateException - if called prior to authenticationServerResponse(OwlAuthenticationInitiate, OwlFinishRegistration), or multiple times

calculateKeyingMaterial

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

The keying material will be identical for client and server if and only if the login password is the same as the password stored by the server. i.e. If the client and server do not share the same password, then each will derive a different key. Rememeber, the server does not explicitly hold the password, but a secret value derived from the password sent to the server by the client during user registration. Therefore, if you immediately start using a key derived from the keying material, then you must handle detection of incorrect keys. Validation of the r value also detects if passwords are different between user registration and user login. If you want to check the equality of the key materials derived at the two sides explicitly, you can perform explicit key confirmation. See OwlServer for details on how to execute key confirmation.

authenticationServerEnd(OwlAuthenticationFinish) must be called prior to this method.

After execution, the state will be STATE_KEY_CALCULATED.

Returns:

The raw key material produced by the Owl key exchange process

Throws:

IllegalStateException - if called prior to authenticationServerEnd(OwlAuthenticationFinish), or if called multiple times.

initiateKeyConfirmation

public OwlKeyConfirmation initiateKeyConfirmation(BigInteger keyingMaterial)

Creates and returns the payload to send to the client as part of Key Confirmation.

See OwlClient for more details on Key Confirmation.

After execution, the state will be STATE_KC_INITIALISED.

Parameters:

keyingMaterial - The keying material as returned from calculateKeyingMaterial().

Returns:

OwlKeyConfirmation

Throws:

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

validateKeyConfirmation

public void validateKeyConfirmation(OwlKeyConfirmation keyConfirmationPayload,
 BigInteger keyingMaterial)
                             throws CryptoException

Validates the payload received from the client as part of Key Confirmation.

See OwlClient for more details on Key Confirmation.

After execution, the state will be STATE_KC_VALIDATED.

Parameters:

keyConfirmationPayload - The key confirmation payload received from the client..

keyingMaterial - The keying material as returned from calculateKeyingMaterial().

Throws:

CryptoException - if validation fails.

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