org.bouncycastle.crypto.agreement.owl
Class OwlClientRegistration

java.lang.Object
  org.bouncycastle.crypto.agreement.owl.OwlClientRegistration

public class OwlClientRegistration

extends java.lang.Object

A client in the Owl key exchange protocol specifically for the user registration phase.

There is one client and one server communicating between each other. An instance of OwlServerRegistration represents one server, and an instance of OwlClientRegistration represents one client. These together make up the main machine through which user registration is facilitated.

To execute the registration, construct an OwlServerRegistration on the server end, and construct an OwlClientRegistration on the client end. Each Owl registration will need a new and distinct OwlServerRegistration and OwlClientRegistration. You cannot use the same OwlServerRegistration or OwlClientRegistration for multiple exchanges.

For user login go to OwlClient and OwlServer. To execute the user registration phase, both OwlServerRegistration and OwlClientRegistration must be constructed.

The following communication between OwlServerRegistration and OwlClientRegistration, must be facilitated over a secure communications channel as the leakage of the payload sent, would allow an attacker to reconstruct the secret password.

Call the following methods in this order, the client initiates every exchange. initiateUserRegistration() - The client sends payload to the server over a secure channel. OwlServerRegistration.registerUseronServer(OwlInitialRegistration) - The server uses the payload received from the client to calculate a user credential payload that is to be safely stored on the server.

This class is stateful and NOT threadsafe. Each instance should only be used for ONE complete Owl exchange (i.e. a new OwlServerRegistration and OwlClientRegistration should be constructed for each new Owl exchange).

Field Summary

static boolean	REGISTRATION_CALLED
static boolean	REGISTRATION_NOT_CALLED

Constructor Summary

OwlClientRegistration(java.lang.String clientId, char[] password)
Convenience constructor for a new OwlClientRegistration that uses the OwlCurves.NIST_P256 elliptic curve, a SHA-256 digest, and a default SecureRandom implementation.

OwlClientRegistration(java.lang.String clientId, char[] password, OwlCurve curve)
Convenience constructor for a new OwlClientRegistration that uses a SHA-256 digest and a default SecureRandom implementation.

OwlClientRegistration(java.lang.String clientId, char[] password, OwlCurve curve, Digest digest, java.security.SecureRandom random)
Construct a new OwlClientRegistration.

Method Summary

boolean	getRegistrationState() Get the status of the user registration.
OwlInitialRegistration	initiateUserRegistration() Initiates user registration with the server.

Methods inherited from class java.lang.Object

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

Field Detail

REGISTRATION_NOT_CALLED

public static final boolean REGISTRATION_NOT_CALLED

See Also:

Constant Field Values

REGISTRATION_CALLED

public static final boolean REGISTRATION_CALLED

See Also:

Constant Field Values

Constructor Detail

OwlClientRegistration

public OwlClientRegistration(java.lang.String clientId,
                             char[] password)

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

After construction, the state will be REGISTRATION_NOT_CALLED.

Parameters:

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

password - shared secret. A defensive copy of this array is made (and cleared once initiateUserRegistration() is called). Caller should clear the input password as soon as possible.

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if password is empty

OwlClientRegistration

public OwlClientRegistration(java.lang.String clientId,
                             char[] password,
                             OwlCurve curve)

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

After construction, the state will be REGISTRATION_NOT_CALLED.

Parameters:

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

password - shared secret. A defensive copy of this array is made (and cleared once initiateUserRegistration() is called). Caller should clear the input password as soon as possible.

curve - elliptic curve See OwlCurves for standard curves.

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if password is empty

OwlClientRegistration

public OwlClientRegistration(java.lang.String clientId,
                             char[] password,
                             OwlCurve curve,
                             Digest digest,
                             java.security.SecureRandom random)

Construct a new OwlClientRegistration.

After construction, the registrationState will be REGISTRATION_NOT_CALLED.

Parameters:

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

password - shared secret. A defensive copy of this array is made (and cleared once initiateUserRegistration() is called). Caller should clear the input password as soon as possible.

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 x1 and x2, and for the zero knowledge proofs

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if password is empty

Method Detail

getRegistrationState

public boolean getRegistrationState()

Get the status of the user registration. I.E. whether or not this server has registered a user already. See the REGSITRATION_* constants for possible values.

Returns:

True if the user has been registered or false otherwise

initiateUserRegistration

public OwlInitialRegistration initiateUserRegistration()

Initiates user registration with the server. Creates the registration payload OwlInitialRegistration and sends it to the server. MUST be sent over a secure channel.

Must be called prior to OwlServerRegistration.registerUseronServer(OwlInitialRegistration)

Returns:

OwlInitialRegistration

Throws:

java.lang.IllegalStateException - if this function is called more than once