Class OwlClient

java.lang.Object
org.bouncycastle.crypto.agreement.owl.OwlClient
public class OwlClient extends Object
A client in the Elliptic Curve Owl key exchange protocol.

Owl is an augmented password-authenticated key exchange (PAKE) protocol, defined by Feng Hao, Samiran Bag, Liqun Chen, and Paul C. van Oorschot in the paper "Owl: An Augmented Password-Authenticated Key Exchange Scheme". Owl builds on the same idea as J-PAKE (using Schnorr zero-knowledge proofs to enforce participants to follow the protocol specification honestly), but it is augmented to provide additional protection against server compromise. While J-PAKE is symmetric, Owl is asymmetric. Like J-PAKE, Owl can be implemented in either elliptic curve (EC) or finite field (FF) settings. This implementation is done in the elliptic curve setting. Any elliptic curve that is suitable for cryptography can be used for Owl (same for J-PAKE).

Owl is an academic protocol — not (yet) an IETF standard. Callers who need a standardised PAKE should prefer the existing J-PAKE in org.bouncycastle.crypto.agreement.jpake / org.bouncycastle.crypto.agreement.ecjpake.

In Owl, there is one client and one server communicating between each other. An instance of OwlServer represents one server, and an instance of OwlClient represents one client. These together make up the main machine through which the protocol is facilitated.

There are two distinct phases that can be taken in Owl: user registration - where the client registers as a new user on the server; login - where an existing user (client) attempts to log in and establish a shared session key with the server based on password authentication. Using the session key, the user (client) can perform further actions (e.g., password update) over a secure channel, but these actions are outside the scope of this key exchange program.

The user registration phase involves only one pass of communication from the client to the server. It's assumed that the following communication is done over a secure channel (e.g., using an out-of-band method).

  1. OwlClientRegistration.initiateUserRegistration() - The client sends payload to the server.
After receiving the payload, the server calls OwlServerRegistration.registerUseronServer(OwlInitialRegistration) to generate a user credential file OwlFinishRegistration and safely store it on the server. The login phase involves three passes of communication between the client and the server. The following communications do not have to be sent via secure channels. Call the following methods in this order, with the client initiating every key exchange process.
  1. authenticationInitiate() - The client sends payload to the server
  2. OwlServer.authenticationServerResponse(OwlAuthenticationInitiate, OwlFinishRegistration) - The server validates the payload received from the client, retrieves the user credentials stored in the server from user registration, and sends the payload generated to the client.
  3. authenticationFinish(OwlAuthenticationServerResponse) - The client validates the payload from the server, and sends next payload generated by this function back to the server.

After the third pass, the client has completed client-to-server authentication. At this point, both the client and the server can compute a shared key. They call the following methods to compute a raw keying material and do key confirmation.

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

The explicit key confirmation process is optional but highly recommended. It does not affect the round efficiency and adds a negligible computational cost. The client-to-server key confirmation string can be piggybacked in the third pass along with OwlAuthenticationFinish. The server-to-client key confirmation string can be sent in the next pass together with encrypted data. If you do not execute key confirmation, then there is no assurance that both client and server have actually derived the same key, and the ensuing secure communication may fail. If the key confirmation succeeds, then the keys are guaranteed to be the same on both sides.

The key confirmation process is implemented as specified in NIST SP 800-56A Revision 3, Section 5.9.1 Unilateral Key Confirmation for Key Agreement Schemes.

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