zxcvbn4j

By default, zxcvbn4j returns feedback messages in English. You can localize these messages (such as warnings and suggestions) into other languages using ResourceBundle.

Option 1: Localize a single Feedback instance

Use Feedback.withResourceBundle(ResourceBundle) to create a new Feedback instance where getSuggestions() and getWarning() return localized strings based on the provided bundle.

Option 2: Localize using a Map of Locales

Use Feedback.replaceResourceBundle(Map<Locale, ResourceBundle>) to provide a mapping of multiple locales to their respective bundles. This allows the feedback to adapt based on the locale provided.

When creating your property files, refer to the existing messages.properties in the repository for the required key/message structure.

// Option 1: Localize a single Feedback instance
Zxcvbn zxcvbn = new Zxcvbn();
Strength strength = zxcvbn.measure("This is password");
ResourceBundle resourceBundle = ResourceBundle.getBundle("This is bundle name", Locale.JAPAN);

Feedback feedback = strength.getFeedback();
Feedback localizedFeedback = feedback.withResourceBundle(resourceBundle);

List<String> localizedSuggestions = localizedFeedback.getSuggestions();
String localizedWarning = localizedFeedback.getWarning();

// Option 2: Localize using a Map of Locales
Map<Locale, ResourceBundle> messages = new HashMap<>();
messages.put(Locale.JAPANESE, ResourceBundle.getBundle("This is bundle name", Locale.JAPANESE));
messages.put(Locale.ITALIAN, ResourceBundle.getBundle("This is bundle name", Locale.ITALIAN));
Feedback replacedFeedback = feedback.replaceResourceBundle(messages);

Use ZxcvbnBuilder to customize the internal dictionaries and keyboards used during measurement. You can load resources from the classpath, from files, or via HTTP by implementing the Resource interface.

Load from Classpath

Use ClasspathResource with DictionaryLoader, SlantedKeyboardLoader, or AlignedKeyboardLoader.

Load from Files

Implement the Resource interface to wrap a File or URL and provide an InputStream via getInputStream().

Use Default Resources

• StandardDictionaries.loadAllDictionaries(): Loads all default dictionaries.
• StandardKeyboards.loadAllKeyboards(): Loads all default keyboards.
• You can also select specific loaders like StandardDictionaries.ENGLISH_WIKIPEDIA_LOADER.load().

// Example: Loading custom resources from classpath
Zxcvbn zxcvbn = new ZxcvbnBuilder()
        .dictionary(new DictionaryLoader("us_tv_and_film", new ClasspathResource("/com/nulabinc/zxcvbn/matchers/dictionarys/us_tv_and_film.txt")).load())
        .keyboard(new SlantedKeyboardLoader("qwerty", new ClasspathResource("/com/nulabinc/zxcvbn/matchers/keyboards/qwerty.txt")).load())
        .build();

// Example: Using specific default resources
Zxcvbn zxcvbn = new ZxcvbnBuilder()
    .dictionary(StandardDictionaries.ENGLISH_WIKIPEDIA_LOADER.load())
    .dictionary(StandardDictionaries.PASSWORDS_LOADER.load())
    .keyboard(StandardKeyboards.QWERTY_LOADER.load())
    .build();

You can translate the English feedback messages (warnings and suggestions) into other languages using Java ResourceBundle.

Localize a single feedback instance

1. Get the Strength object.
2. Get the Feedback object from strength.getFeedback().
3. Create a ResourceBundle for your target Locale.
4. Call feedback.withResourceBundle(resourceBundle) to get a new Feedback instance with localized strings.

Localize multiple locales at once

Use feedback.replaceResourceBundle(Map<Locale, ResourceBundle> messages) to replace the feedback with a map of pre-loaded bundles for different locales.

// Localize a single feedback
Zxcvbn zxcvbn = new Zxcvbn();
Strength strength = zxcvbn.measure("This is password");
ResourceBundle resourceBundle = ResourceBundle.getBundle("This is bundle name", Locale.JAPAN);

Feedback feedback = strength.getFeedback();
Feedback localizedFeedback = feedback.withResourceBundle(resourceBundle);

List<String> localizedSuggestions = localizedFeedback.getSuggestions();
String localizedWarning = localizedFeedback.getWarning();

// Replace multiple locales
Map<Locale, ResourceBundle> messages = new HashMap<>();
messages.put(Locale.JAPANESE, ResourceBundle.getBundle("This is bundle name", Locale.JAPANESE));
messages.put(Locale.ITALIAN, ResourceBundle.getBundle("This is bundle name", Locale.ITALIAN));
Feedback replacedFeedback = feedback.replaceResourceBundle(messages);

Use ZxcvbnBuilder to customize the dictionaries and keyboard layouts used by the measurement engine. You can load resources from the classpath, local files, or via HTTP by implementing the Resource interface.

Loading from Classpath

Use ClasspathResource with DictionaryLoader, SlantedKeyboardLoader, or AlignedKeyboardLoader.

Loading from Files

Implement a Resource that returns an InputStream from a File or URL.

Using Default Resources

• To use all default resources: new Zxcvbn() or use StandardDictionaries.loadAllDictionaries() and StandardKeyboards.loadAllKeyboards() with the builder.
• To select specific defaults: Use loaders like StandardDictionaries.ENGLISH_WIKIPEDIA_LOADER.load() or StandardKeyboards.QWERTY_LOADER.load().

// Example: Loading from Classpath
Zxcvbn zxcvbn = new ZxcvbnBuilder()
        .dictionary(new DictionaryLoader("us_tv_and_film", new ClasspathResource("/com/nulabinc/zxcvbn/matchers/dictionarys/us_tv_and_film.txt")).load())
        .keyboard(new SlantedKeyboardLoader("qwerty", new ClasspathResource("/com/nulabinc/zxcvbn/matchers/keyboards/qwerty.txt")).load())
        .build();

// Example: Selecting specific default resources
Zxcvbn zxcvbn = new ZxcvbnBuilder()
    .dictionary(StandardDictionaries.ENGLISH_WIKIPEDIA_LOADER.load())
    .dictionary(StandardDictionaries.PASSWORDS_LOADER.load())
    .keyboard(StandardKeyboards.QWERTY_LOADER.load())
    .keyboard(StandardKeyboards.DVORAK_LOADER.load())
    .build();

The measure method returns a Strength object containing detailed metrics about the password's security. Key properties include:

• guesses: Estimated guesses needed to crack the password.
• guessesLog10: Order of magnitude of guesses.
• crackTimeSeconds: A dictionary of crack time estimations in seconds for different scenarios:
  • onlineThrottling100PerHour: Online attack with rate limiting.
  • onlineNoThrottling10PerSecond: Online attack without rate limiting.
  • offlineSlowHashing1e4PerSecond: Offline attack with moderate work factor (e.g., bcrypt).
  • offlineFastHashing1e10PerSecond: Offline attack with fast hash functions (e.g., MD5, SHA-1).
• crackTimeDisplay: Human-readable strings for crack times (e.g., "3 hours", "centuries").
• score: An integer from 0-4 used for strength bars:
  • 0: Weak
  • 1: Fair
  • 2: Good
  • 3: Strong
  • 4: Very strong
• feedback: Contains warning (string) and suggestions (list of strings) to help users improve passwords. Usually provided when score <= 2.
• sequence: The list of patterns used for the calculation.
• calc_time: Time taken for calculation in milliseconds.

The measure method returns a Strength instance containing detailed metrics about the password's security. Key fields include:

• guesses: Number of guesses required to crack the password.
• guessesLog10: Log10 of the number of guesses.
• crackTimeSeconds: A map containing estimated crack times for different scenarios:
  • onlineThrottling100PerHour: Online attack with 100 attempts/hour limit.
  • onlineNoThrottling10PerSecond: Online attack with 10 attempts/second limit.
  • offlineSlowHashing1e4PerSecond: Offline attack using slow hashing (e.g., bcrypt, scrypt, PBKDF2) at 10,000/sec.
  • offlineFastHashing1e10PerSecond: Offline attack using fast hashing (e.g., SHA-1, SHA-256, MD5) at 10,000,000,000/sec.
• crackTimeDisplay: A human-readable string of the crack time (e.g., "3 hours", "a century").
• score: An integer from 0 to 4 representing strength:
  • 0: Weak (guesses < 10^3 + 5)
  • 1: Somewhat weak (guesses < 10^6 + 5)
  • 2: Normal (guesses < 10^8 + 5)
  • 3: Strong (guesses < 10^10 + 5)
  • 4: Very strong (guesses >= 10^10 + 5)
• warning: A warning message (only populated if score <= 2).
• suggestions: A list of suggestions to improve the password (only populated if score <= 2).
• sequence: A list of patterns detected during measurement.
• calc_time: Time taken to perform the calculation.

The FeedbackFactory class provides static methods to generate Feedback objects based on password strength matches. This is useful for translating internal match data (like dictionary hits or keyboard patterns) into human-readable warnings and suggestions.

Key methods:

• createMatchFeedback(Match match, boolean isSoleMatch): The primary entry point. It inspects the Match object's pattern (e.g., Dictionary, Spatial, Repeat, Sequence, Regex, Date) and returns a Feedback object containing appropriate warnings and suggestions.
• getFeedbackWithoutWarnings(String... suggestions): Creates a Feedback object that contains only the provided suggestions and no warning message.
• getEmptyFeedback(): Returns a Feedback object with no warnings and no suggestions.

// Note: FeedbackFactory is package-private in the source, 
// but its static methods are the intended way to generate feedback 
// from Match objects in the zxcvbn4j workflow.

Feedback feedback = FeedbackFactory.createMatchFeedback(match, isSoleMatch);
String warning = feedback.getWarning();
List<String> suggestions = feedback.getSuggestions();