README.md

reCAPTCHA Password Check

Java client library for reCAPTCHA's private password check API. 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 in your pom.xml:

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

2. Create a verifier instance:

   [!IMPORTANT] PasswordCheckVerifier uses an ExecutorService 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.

   PasswordCheckVerifier passwordLeak = new PasswordCheckVerifier();

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

   PasswordCheckVerification verification = passwordLeak.createPasswordCheckVerification(username, password).get();
   
   byte[] lookupHashPrefix = verification.getLookupHashPrefix();
   byte[] encryptedUserCredentialsHash = verification.getEncryptedUserCredentialsHash();

4. Next, use the parameters generated to include in your reCAPTCHA assessment request

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

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

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

   boolean leaked = result.areCredentialsLeaked();

Example

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

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

CompletableFuture<PasswordCheckVerification> verificationFuture =
  passwordLeakVerifier.createPasswordCheckVerification(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());
  );