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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `REGISTRATION_CALLED`
    `static boolean` | `REGISTRATION_NOT_CALLED`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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