# java-recaptcha-password-check-helpers

**Repository Path**: mirrors_GoogleCloudPlatform/java-recaptcha-password-check-helpers

## Basic Information

- **Project Name**: java-recaptcha-password-check-helpers
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-04-21
- **Last Updated**: 2026-02-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# reCAPTCHA Password Check

Java client library for reCAPTCHA's
[private password check API](https://cloud.google.com/recaptcha-enterprise/docs/check-passwords).
It exposes functionality to make password leak check requests in a private
manner (i.e credentials are sent encrypted and the server cannot—and doesn't
need to—decrypt them).

## Usage

1.  Import [dependency](https://central.sonatype.com/artifact/com.google.cloud/recaptcha-password-check-helpers/1.0.2) in your `pom.xml`:

    ```
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>recaptcha-password-check-helpers</artifactId>
      <version>1.0.2</version>
    </dependency>
    ```

1.  Create a verifier instance:

    > **IMPORTANT**
    > `PasswordCheckVerifier` uses an
    > [ExecutorService](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html)
    > to execute the cryptographic functions to generate the request parameters.
    > If no `ExecutorService` is passed when creating a new instance, the
    > constructor will create a new one, so you may want to keep a single instance
    > of `PasswordCheckVerifier` for all your password leak check requests.

    ```java
    PasswordCheckVerifier passwordLeak = new PasswordCheckVerifier();
    ```

1.  Create a verification with some user credentials and extract the parameters
    generated

    ```java
    PasswordCheckVerification verification = passwordLeak.createVerification(username, password).get();

    byte[] lookupHashPrefix = verification.getLookupHashPrefix();
    byte[] encryptedUserCredentialsHash = verification.getEncryptedUserCredentialsHash();
    ```

1.  Next, use the parameters generated to include in your reCAPTCHA
    [assessment request](https://cloud.google.com/recaptcha-enterprise/docs/create-assessment)

1.  Then, extract the `reEncryptedUserCredentialsHash` and
    `encryptedLeakMatchPrefixes` from the response of the assessment request and
    use them to verify them:

    ```java
    PasswordCheckResult result = passwordLeak.verify(verification, reEncryptedUserCredentialsHash, encryptedLeakMatchPrefixes);
    ```

1.  Finally, use the result to determine whether the user credentials are leaked
    or not:

    ```java
    boolean leaked = result.areCredentialsLeaked();
    ```

## Example

The following example assumes non-blocking execution (recommended for
asynchronous services) using a generic reCAPTCHA client.

```java
// Generic reCAPTCHA client
RecaptchaCustomClient reCaptchaCustomClient = createCustomClient();
PasswordCheckVerifier passwordLeakVerifier = new PasswordCheckVerifier();

CompletableFuture<PasswordCheckVerification> verificationFuture =
  passwordLeakVerifier.createVerification(username, password);

CompletableFuture<PasswordCheckResult> = verificationFuture
  // Create an assessment using the parameters generated by the verifier
  .thenCompose(verification -> {
    CustomAssessment assessment = createAssessment();
    CustomPasswordCheckRequest request = createPasswordCheckRequest();
    request.setLookupHashPrefix(verification.getLookupHashPrefix());
    request.setEncryptedLookupHash(
            verification.getEncryptedUserCredentialsHash());
    assessment.setPasswordCheckRequest(lookup);

    // Assuming that the reCAPTCHA client returns a CompletableFuture
    return reCaptchaCustomClient.createAssessment(assessment);
  })
  // Verify the result of the assessemnt and builds a PasswordCheckResult
  .thenCompose(result ->
    passwordLeakVerifier.verify(verification, result.getReEncryptedUserCredentials(), result.getEncryptedLeakMatchPrefixes());
  )
  // Detemine if the credentials are leaked or not
  .thenApply(result ->
    System.out.println("Credentials are leaked? " + result.areCredentialsLeaked());
  );
```