README.ja.md

zxcvbn4j

zxcvbn4j は、JavaScriptのパスワード強度ジェネレータであるzxcvbnをJavaにポーティングしたものです。

関連記事:

• 真のパスワード強度を測定する5つのアルゴリズム

目次

• 更新
• 特別な機能
  • 内部辞書とキーボードのカスタマイズ
  • フィードバックメッセージのローカライズ
  • デフォルトで様々な言語をサポート
  • JISキーボードに対応
  • パスワードの引数はStringだけでなくCharSequenceも受付可能
• インストール
• 開発
• 使い方
  • 基本
  • 強度の情報
• 辞書とキーボードのカスタマイズ
  • クラスパスから取得したリソースを使用する
  • HTTPを介して取得したリソースを使用する
  • クラスパス以外のファイルのリソースを使用する
  • 全てのデフォルトリソースを使用する
  • デフォルトリソースから選択して使用する
• フィードバックメッセージのローカライズ
  • リソースバンドルを指定してローカライズする
  • リソースバンドルのセットを使ってローカライズする
• 要件
• このライブラリを使用
• バグ報告やご意見
• ライセンス

更新

Ported Version	Original zxcvbn Version
1.2.3 - latest	4.4.2
1.2.1 - 1.2.2	4.4.1
1.1.0 - 1.2.0	4.4.0
1.0.0 - 1.0.2	4.2.0

特別な機能

内部辞書とキーボードのカスタマイズ

• 測定アルゴリズムが使用する辞書とキーボードレイアウトをカスタマイズできます。

フィードバックメッセージのローカライズ

• フィードバックメッセージを任意の言語にローカライズできます。

デフォルトで様々な言語をサポート

測定結果のフィードバックメッセージに対応する言語

• English (default)
• Japanese (ja)
• Dutch (nl)
• German (de)
• French (fr)
• Italian (it)
• Spanish (es)
• Portuguese (pt)

JISキーボードに対応

• 隣接したキー配列の照合処理にJISキーボードを対応

パスワードの引数はStringだけでなくCharSequenceも受付可能

• これによりパスワードのフォーマットを柔軟に変更可能。
• センシティブな中間オブジェクトにも文字列を使用しない。

インストール

https://mvnrepository.com/artifact/com.nulab-inc/zxcvbn/1.9.0

Gradle:

compile 'com.nulab-inc:zxcvbn:1.9.0'

Maven:

<dependency>
  <groupId>com.nulab-inc</groupId>
  <artifactId>zxcvbn</artifactId>
  <version>1.9.0</version>
</dependency>

開発

$ git clone https://github.com/nulab/zxcvbn4j.git
$ cd ./zxcvbn4j
$ ./gradlew build    # build
$ ./gradlew test     # test
$ ./gradlew jmh      # benchmark

使い方

基本

基本的な使い方です。Androidも同じようにご利用できます。

Zxcvbn zxcvbn = new Zxcvbn();
Strength strength = zxcvbn.measure("This is password");

独自の辞書を追加したい場合は、第二引数にリスト<文字列>のタイプのキーワード一覧を渡します。

List<String> sanitizedInputs = new ArrayList();
sanitizedInputs.add("nulab");
sanitizedInputs.add("backlog");
sanitizedInputs.add("cacoo");
sanitizedInputs.add("typetalk");

Zxcvbn zxcvbn = new Zxcvbn();
Strength strength = zxcvbn.measure("This is password", sanitizedInputs);

強度の情報

返却する結果は、"Strength"インスタンスです。zxcvbn が返却する結果とほぼ同じものです。

# パスワードの「乱雑さ」「複雑さ」を表す指標
strength.guesses
strength.guessesLog10

# いくつかのシナリオに基づいたクラック時間の推測
strength.crackTimeSeconds
{
  # オンライン攻撃でパスワード認証に回数制限が有る場合
  onlineThrottling100PerHour

  # オンライン攻撃でパスワード認証に回数制限が無い場合
  onlineNoThrottling10PerSecond

  # オフライン攻撃で、bcrypt、scrypt、PBKDF2等を使ってハッシュ化している場合
  offlineSlowHashing1e4PerSecond

  # オフライン攻撃で、SHA-1、SHA-256またはMD5等を使ってハッシュ化している場合
  offlineFastHashing1e10PerSecond
}

# strength.crackTimeSecondsを表示するために文字列化した値(秒未満、3時間、世紀 等)
strength.crackTimeDisplay


# 0から4の整数
# 0 弱い      （guesses < 10^3 + 5）
# 1 やや弱い   （guesses < 10^6 + 5）
# 2 普通      （guesses < 10^8 + 5）
# 3 強い      （guesses < 10^10 + 5）
# 4 とても強い （guesses >= 10^10 + 5）
strength.score

# 安全なパスワード作成に役立つフィードバック。(score <= 2 のみ表示)
{
  # 警告文
  warning

  # 提案
  suggestions
}

# 測定に用いたパターンのリスト
strength.sequence

# 測定にかかった時間
strength.calc_time

辞書とキーボードのカスタマイズ

ZxcvbnBuilderを使って測定処理で使用する辞書とキーボードをカスタマイズできます。

クラスパスから取得したリソースを使用する

クラスパス上の独自の辞書ファイルやキーボードファイルをClasspathResourceを使って取得できます。 辞書ファイルはDictionaryLoaderを使ってロードします。 キーボードファイルはSlantedKeyboardLoaderかAlignedKeyboardLoaderを使ってロードします。

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())
        .keyboard(new AlignedKeyboardLoader("keypad", new ClasspathResource("/com/nulabinc/zxcvbn/matchers/keyboards/keypad.txt")).load())
        .build();

HTTPを介して取得したリソースを使用する

Resource interfaceを実装するとクラスパス以外の辞書・キーボードファイルも取得できます。 以下のコードはHTTP(s)を使ってファイルを取得してロードしています。

URL dictionaryURL = new URL("https://example.com/foo/dictionary.txt");
Resource myDictionaryResource = new MyResourceOverHTTP(dictionaryURL);

URL keyboardURL = new URL("https://example.com/bar/keyboard.txt");
Resource myKeyboardURLResource = new MyResourceOverHTTP(keyboardURL);

Zxcvbn zxcvbn = new ZxcvbnBuilder()
        .dictionary(new DictionaryLoader("my_dictionary", myDictionaryResource).load())
        .keyboard(new SlantedKeyboardLoader("my_keyboard", myKeyboardURLResource).load())
        .build();

public class MyResourceOverHTTP implements Resource {

    private URL url;

    public MyResourceOverHTTP(URL url) {
        this.url = url;
    }

    @Override
    public InputStream getInputStream() throws IOException {
        HttpURLConnection conn = (HttpURLConnection) this.url.openConnection();
        return conn.getInputStream();
    }
}

クラスパス以外のファイルのリソースを使用する

以下のコードはクラスパス以外の他のディレクトリのファイルを取得してロードしています。

File dictionaryFile = new File("/home/foo/dictionary.txt");
Resource myDictionaryResource = new MyResourceFromFile(dictionaryFile);

File keyboardFile = new File("/home/bar/keyboard.txt");
Resource myKeyboardURLResource = new MyResourceFromFile(keyboardFile);

Zxcvbn zxcvbn = new ZxcvbnBuilder()
    .dictionary(new DictionaryLoader("my_dictionary", myDictionaryResource).load())
    .keyboard(new SlantedKeyboardLoader("my_keyboard", myKeyboardURLResource).load())
    .build();

public class MyResourceFromFile implements Resource {

    private File file;

    public MyResourceFromFile(File file) {
        this.file = file;
    }

    @Override
    public InputStream getInputStream() throws IOException {
        return new FileInputStream(this.file);
    }
}

全てのデフォルトリソースを使用する

StandardDictionariesを使ってデフォルトの辞書ファイルやキーボードをロードできます。 StandardDictionaries.loadAllDictionaries()はデフォルトの全ての辞書ファイルをロードします。 StandardDictionaries.loadAllKeyboards()はデフォルトの全てのキーボードファイルをロードします。

Zxcvbn zxcvbn = new Zxcvbn();

or

Zxcvbn zxcvbn = new ZxcvbnBuilder()
    .dictionaries(StandardDictionaries.loadAllDictionaries())
    .keyboards(StandardKeyboards.loadAllKeyboards())
    .build();

デフォルトリソースから選択して使用する

デフォルトの辞書ファイルやキーボードから一部を選択してロードできます。

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();

フィードバックメッセージのローカライズ

zxcvbn4jは英語で返却されるフィードバックメッセージを他の言語に変更可能です。

リソースバンドルを指定してローカライズする

// パスワード強度を測定して Strength を取得します。
Zxcvbn zxcvbn = new Zxcvbn();
Strength strength = zxcvbn.measure("This is password");

// 事前に用意したプロパティファイル(※)の名前とロケールを指定して、ResourceBundle を取得します。
ResourceBundle resourceBundle = ResourceBundle.getBundle("This is bundle name", Locale.JAPAN);

// FeedbackにResourceBundleを渡して、ローカライズされたFeedbackを生成します。
Feedback feedback = strength.getFeedback();
Feedback localizedFeedback = feedback.withResourceBundle(resourceBundle);

// getSuggestions()、getWarning()で取得するフィードバックメッセージはローカライズ済みです。
List<String> localizedSuggestions = localizedFeedback.getSuggestions();
String localizedWarning = localizedFeedback.getWarning();

プロパティファイルに定義するキーとメッセージは、messages.properties を参考に作成してください。

• http://www.opensource.org/licenses/mit-license.php

リソースバンドルのセットを使ってローカライズする

Strength strength = zxcvbn.measure(password);
Feedback feedback = strength.getFeedback();

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

要件

• Java 1.7以上

このライブラリを使用

• Backlog
• Cacoo
• Typetalk
• JetBrains Hub
• Cryptomator
• And many Open Source Software
  • https://github.com/search?q=com.nulab-inc+zxcvbn&type=code
  • https://mvnrepository.com/artifact/com.nulab-inc/zxcvbn/usages

バグ報告やご意見

バグ報告, ご意見、ご質問等は Github Issues にお願い致します。

ライセンス

MIT License