org.bouncycastle.crypto.agreement.owl

## Class OwlServer

- java.lang.Object
- - org.bouncycastle.crypto.agreement.owl.OwlServer

-     public class OwlServer
      extends java.lang.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 and Description
    --- | ---
    `static int` | `STATE_INITIALISED`
    `static int` | `STATE_KC_INITIALISED`
    `static int` | `STATE_KC_VALIDATED`
    `static int` | `STATE_KEY_CALCULATED`
    `static int` | `STATE_LOGIN_FINISHED`
    `static int` | `STATE_LOGIN_INITIALISED`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `OwlServer(java.lang.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(java.lang.String serverId, OwlCurve curve)` Convenience constructor for a new `OwlServer` that uses a SHA-256 digest and a default `SecureRandom` implementation.
    `OwlServer(java.lang.String serverId, OwlCurve curve, Digest digest, java.security.SecureRandom random)` Construct a new `OwlServer`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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`.
    `java.math.BigInteger` | `calculateKeyingMaterial()` Calculates and returns the key material.
    `int` | `getState()` Gets the current state of this server.
    `OwlKeyConfirmation` | `initiateKeyConfirmation(java.math.BigInteger keyingMaterial)` Creates and returns the payload to send to the client as part of Key Confirmation.
    `void` | `validateKeyConfirmation(OwlKeyConfirmation keyConfirmationPayload, java.math.BigInteger keyingMaterial)` Validates the payload received from the client as part of Key Confirmation.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### 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 Detail

    - #### OwlServer

          public OwlServer(java.lang.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:
        `java.lang.NullPointerException` - if any argument is null

    - #### OwlServer

          public OwlServer(java.lang.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:
        `java.lang.NullPointerException` - if any argument is null

    - #### OwlServer

          public OwlServer(java.lang.String serverId,
                           OwlCurve curve,
                           Digest digest,
                           java.security.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:
        `java.lang.NullPointerException` - if any argument is null

  - ### Method Detail

    - #### 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.
        `java.lang.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.
        `java.lang.IllegalStateException` - if called prior to `authenticationServerResponse(OwlAuthenticationInitiate, OwlFinishRegistration)`, or multiple times

    - #### calculateKeyingMaterial

          public java.math.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:
        `java.lang.IllegalStateException` - if called prior to `authenticationServerEnd(OwlAuthenticationFinish)`, or if called multiple times.

    - #### initiateKeyConfirmation

          public OwlKeyConfirmation initiateKeyConfirmation(java.math.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:
        `java.lang.IllegalStateException` - if called prior to `calculateKeyingMaterial()`, or multiple times

    - #### validateKeyConfirmation

          public void validateKeyConfirmation(OwlKeyConfirmation keyConfirmationPayload,
                                              java.math.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.
        `java.lang.IllegalStateException` - if called prior to `calculateKeyingMaterial()`, or multiple times