Java密码库Password4j

女爷i 2023-09-27 08:44 70阅读 0赞

Password4j 是一个 Java**用户友好的**密码库，用于使用不同的[密钥派生函数][Link 1](KDF) 和[密码哈希函数][Link 2](CHF) 对密码进行散列和检查。

可以通过**编程**方式或通过类路径中的**属性文件配置算法，请**参阅[配置部分][Link 3]。

配置主要取决于您的环境。Password4j 提供了一个工具，可以根据系统性能和所需的最大计算时间**创建一组最佳参数，**请参阅[性能部分][Link 4]。

![58405f6c02eb43469d146f33e17ac6f7.png][]

![b93c2a7f26a8437583da8c700e5bc7ea.png][]

该库完全支持**[Argon2][]**、**[bcrypt][]**、**[scrypt][]**和**[PBKDF2 ，][PBKDF2]****[并且][Link 5]**可以生成和 处理加密**[椒盐][Link 6]**。

## 文档 ##

完整的文档可以在**[这里][Link 7]**找到。为了快速开始，您可以按照`README.md`.

可以在[此处][Link 8]找到 javadoc 。

## 安装 ##

Password4j 在任何供应商的**Java 8 或更高版本上运行。****Android API 21+**也支持它。

工件被部署到[Maven Central][]。

### 马文 ###

将最新版本的依赖项添加到您的`pom.xml`：

<dependency>
        <groupId>com.password4j</groupId>
        <artifactId>password4j</artifactId>
        <version>1.6.0</version>
    </dependency>

### 摇篮 ###

添加到您的`build.gradle`模块依赖项：

repositories {
        mavenCentral()
    }
    
    dependencies {
        implementation 'com.password4j:password4j:1.6.0'
    }

### 斯卡拉 SBT ###

`build.sbt`添加到最新版本的托管依赖项：

libraryDependencies += "com.password4j" % "password4j" % "1.6.0"

## 用法 ##

Password4j 提供了三个主要功能：密码散列、散列检查和散列更新。

### 哈希密码 ###

这是使用 CHF 散列密码的最简单方法（在这种情况下为 bcrypt）

Hash hash = Password.hash(password).withBcrypt();

盐和胡椒可以选择添加到构建器中（在这种情况下为 PBKDF2）：

// PBKDF2 with salt 12 bytes long (randomly generated).
    Hash hash = Password.hash(password).addRandomSalt(12).withPBKDF2();
    
    // PBKDF2 with a chosen salt.
    Hash hash = Password.hash(password).addSalt(salt).withPBKDF2();
    
    // PBKDF2 with chosen salt and pepper.
    Hash hash = Password.hash(password).addSalt(salt).addPepper(pepper).withPBKDF2();
    
    // Custom PBKDF2 (PBKDF2 with HMAC-SHA512, 64000 iterations and 512bit length).
    Hash hash = Password.hash(password).with(PBKDF2Function.getInstance(Hmac.SHA512, 64000, 512));

其他 CHF 可以采用相同的结构，而不仅仅是 PBKDF2。

### 验证哈希 ###

您可以同样轻松地验证哈希：

boolean verified = Password.check(password, hash).withBcrypt();

盐和胡椒可以选择添加到构建器中（在这种情况下为 PBKDF2）：

// Verify with PBKDF2.
    boolean verification = Password.check(password, hash).withPBKDF2();
    
    // Verify with PBKDF2 and manually provided salt.
    boolean verification = Password.check(password, hash).addSalt(salt).withPBKDF2();
    
    // Verify with PBKDF2 and manually provided salt and pepper.
    boolean verification = Password.check(password, hash).addSalt(salt).addPepper(pepper).withPBKDF2();

其他算法可以采用相同的结构，而不仅仅是 PBKDF2。考虑到 Argon2、bcrypt 和 scrypt 将盐存储在哈希中，因此`addSalt()`不需要该方法。

// Verify with Argon2, reads the salt from the given hash.
    boolean verification = Password.check(password, hash).withArgon2();

一些算法将用于计算该哈希的参数编码到哈希中，特别是 bcrypt、scrypt 和 Argon2。检查散列时，您可以使用散列中的参数而不是 Password4j 配置的默认值。

// Verify with Argon2, reads the salt and parameters from the given hash.
    boolean verification = Password.check(password, hash)..with(Argon2Function.getInstanceFromHash(hash)));

### 更新哈希 ###

当配置被认为不再安全时，您可以使用更现代的算法刷新哈希，如下所示：

// Reads the latest configurations in your psw4j.properties
    HashUpdate update = Password.check(password, hash).update().withBcrypt();
    
    if(update.isVerified())
    {
        Hash newHash = update.getHash();
    }

或者，如果您想从 CHF 切换到另一个：

PBKDF2Function pbkdf2 = AlgorithmFinder.getPBKDF2Instance();
    HashUpdate update = Password.check(password, hash).update().withScrypt(pbkdf2);
    
    if(update.isVerified())
    {
        Hash newHash = update.getHash();
    }

### 不安全的算法 ###

许多系统可能仍然使用不安全的算法来存储密码，例如[MD5][]或[SHA-256][]。您可以使用 Password4j 轻松迁移到更强大的算法

MessageDigestFunction md = MessageDigestFunction.getInstance("SHA-256");
    HashUpdate update = Password.check(password, hash).update().withScrypt(md);
    
    if(update.isVerified())
    {
        Hash newHash = update.getHash();
    }

### 支持的算法列表 ###

<table> 
 <thead> 
  <tr> 
   <th>密钥派生函数</th> 
   <th>自从</th> 
   <th>笔记</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td style="background-color:#ffffff;">PBKDF2</td> 
   <td style="background-color:#ffffff;">1.0.0</td> 
   <td style="background-color:#ffffff;">取决于您的 JVM 提供的安全服务</td> 
  </tr> 
  <tr> 
   <td style="background-color:#ffffff;">bcrypt</td> 
   <td style="background-color:#ffffff;">1.0.0</td> 
   <td style="background-color:#ffffff;"></td> 
  </tr> 
  <tr> 
   <td style="background-color:#ffffff;">脚本</td> 
   <td style="background-color:#ffffff;">1.0.0</td> 
   <td style="background-color:#ffffff;"></td> 
  </tr> 
  <tr> 
   <td style="background-color:#ffffff;">氩气2</td> 
   <td style="background-color:#ffffff;">1.5.0</td> 
   <td style="background-color:#ffffff;"></td> 
  </tr> 
 </tbody> 
</table>

<table> 
 <thead> 
  <tr> 
   <th>加密哈希函数</th> 
   <th>自从</th> 
   <th>笔记</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td style="background-color:#ffffff;">医学博士家庭</td> 
   <td style="background-color:#ffffff;">1.4.0</td> 
   <td style="background-color:#ffffff;"></td> 
  </tr> 
  <tr> 
   <td style="background-color:#ffffff;">SHA1 系列</td> 
   <td style="background-color:#ffffff;">1.4.0</td> 
   <td style="background-color:#ffffff;"></td> 
  </tr> 
  <tr> 
   <td style="background-color:#ffffff;">SHA2 系列</td> 
   <td style="background-color:#ffffff;">1.4.0</td> 
   <td style="background-color:#ffffff;"></td> 
  </tr> 
  <tr> 
   <td style="background-color:#ffffff;">SHA3家族</td> 
   <td style="background-color:#ffffff;">1.4.0</td> 
   <td style="background-color:#ffffff;">取决于您的 JVM 提供的安全提供程序</td> 
  </tr> 
 </tbody> 
</table>

### 字符串的安全性 ###

`String`s 是不可变的对象，一旦存储在内存中，在垃圾收集之前您无法擦除它们。始终[建议][Link 9]使用`char[]`而不是`String`存储密码（如果可能 - 如果我们谈论的是 Web 应用程序，大多数 Web 容器会将密码`HttpServletRequest`以明文形式传递给对象`String`）。

能够转储内存的攻击者可以在您将密码用作 Password4j 的输入之前读取密码；即使在使用后读取，也不能保证何时发生垃圾回收：这意味着密码可能会无限期地存储在内存中，并且其值无法擦除。

出于这个原因，Password4j 提供了一个`SecureString`类来**缓解**这个问题。提供 `char[]`的内容被包裹起来，并且在此过程中`SecureString`永远不会转换为。`String`

`char[]`您可以使用方法擦除底层证券`clear()`。

SecureString secure = new SecureString(new char[]{...});
    
    Password.hash(secure).withBcrypt();
    Password.check(secure, hash).withBcrypt();
    
    secure.clear();
    // At this point the underlying char[] = {\0, \0, \0, ...}

除此之外，您可能还需要清洁原始`char[]`. 使用以下代码，即使源代码也归零：

char[] password = {...}
    SecureString secure = new SecureString(password, true);
    
    // At this point password = {\0, \0, \0, ...}

辣椒也可以表达`SecureString`。

使用`SecureString`或`char[]`不完全保护您免受攻击：垃圾收集器不断将对象从*from 空间*复制到*to 空间*，擦除原件`char[]`不会擦除其副本；此外，永远不能保证`clear()`在垃圾收集之前应用。由于这些原因，使用`SecureString`或`char[]`只是减少了攻击者的机会窗口。

### JCA ###

Password4j 与 JCA 兼容。有关更多详细信息，请参阅[此项目][Link 10]。

## 配置 ##

Password4j 提供了一种配置库的可移植方式。

使用放在类路径中的属性文件`psw4j.properties`，您可以定义所有支持的 CHF 的参数，或者只定义您需要的 CHF。或者，您可以使用系统属性指定自定义路径`-Dpsw4j.configuration`

java -Dpsw4j.configuration=/my/path/to/some.properties ...

这是一个基本配置（请不要在生产中使用它，而是在您的目标环境中启动基准会话，请参阅[性能部分][Link 4]）

### Argon2
    hash.argon2.memory=4096
    hash.argon2.iterations=20
    hash.argon2.length=128
    hash.argon2.parallelism=4
    hash.argon2.type=id
    
    
    ### bcrypt
    hash.bcrypt.minor=b
    # logarithmic cost (cost = 2^12)
    hash.bcrypt.rounds=12
    
    
    ### scrypt
    # N
    hash.scrypt.workfactor=16384
    # r
    hash.scrypt.resources=16
    # p
    hash.scrypt.parallelization=1
    # length
    hash.scrypt.derivedKeyLength=64
    
    ### PBKDF2
    # with HMAC-SHA256
    hash.pbkdf2.algorithm=SHA256
    # 64000 iterations
    hash.pbkdf2.iterations=64000
    # derived key of 256bit 
    hash.pbkdf2.length=256
    
    
    ### Legacy MessageDisgest
    # algorithm
    hash.md.algorithm=SHA-512
    # append/prepend salt
    hash.md.salt.option=append

此外，您可以在此处定义您的共享辣椒

global.pepper=AlicePepper

并像这样使用它

// Hash
    Password.hash("password").addPepper().withScrypt();
    
    // Verify
    Password.check("password", "hash").addPepper().withScrypt();

[SecureRandom][]可以被实例化并用于`SecureRandom.getInstanceStrong()`生成盐和胡椒。

global.random.strong=true

但请确保您的 JVM 支持它并且它指向一个非阻塞的熵源，否则您可能会遇到巨大的性能下降，请参阅[SecureRandom][SecureRandom 1]。

## 表现 ##

此工具必须在目标系统中使用，因为不同环境下的性能可能会有所不同。

Password4j 附带一个工具，可帮助开发人员为特定的 CHF 选择正确的参数。

该类`SystemChecker`可用于找到这些最佳值。

在 wiki 中，您可以找到如何根据您的响应要求配置[PBKDF2][PBKDF2 1]、[bcrypt][bcrypt 1]、[scrypt][scrypt 1]和[Argon2 。][Argon2 1]

## 贡献 ##

请阅读[CONTRIBUTING.md][]了解我们的行为准则的详细信息，以及向我们提交拉取请求的流程。

## 版本控制 ##

我们使用[SemVer][]进行版本控制。

有关可用版本，请参阅[此存储库上][Link 11]的版本。

## 作者 ##

*  **David Bertoldi** \-*主要维护者*\- [firaja][]

另请参阅参与此项目的[贡献者列表。][Link 12]

## 执照 ##

该项目在 Apache License 2.0 License 下获得许可 - 请参阅[LICENSE][]文件了解详细信息

## 变更日志 ##

有关每个版本的更详细说明，请参阅[CHANGELOG.md][]文件。

[Link 1]: https://en.wikipedia.org/wiki/Key_derivation_function
[Link 2]: https://en.wikipedia.org/wiki/Cryptographic_hash_function
[Link 3]: https://github.com/Password4j/password4j#Configuration
[Link 4]: https://github.com/Password4j/password4j#Performance
[58405f6c02eb43469d146f33e17ac6f7.png]: https://img-blog.csdnimg.cn/58405f6c02eb43469d146f33e17ac6f7.png
[b93c2a7f26a8437583da8c700e5bc7ea.png]: https://img-blog.csdnimg.cn/b93c2a7f26a8437583da8c700e5bc7ea.png
[Argon2]: https://en.wikipedia.org/wiki/Argon2
[bcrypt]: https://en.wikipedia.org/wiki/Bcrypt
[scrypt]: https://en.wikipedia.org/wiki/Scrypt
[PBKDF2]: https://en.wikipedia.org/wiki/PBKDF2
[Link 5]: https://en.wikipedia.org/wiki/Pepper_%28cryptography%29
[Link 6]: https://en.wikipedia.org/wiki/Salt_%28cryptography%29
[Link 7]: https://github.com/Password4j/password4j/wiki
[Link 8]: https://javadoc.io/doc/com.password4j/password4j
[Maven Central]: https://search.maven.org/
[MD5]: https://en.wikipedia.org/wiki/MD5
[SHA-256]: https://en.wikipedia.org/wiki/SHA-2
[Link 9]: https://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html#PBEEx
[Link 10]: https://github.com/Password4j/password4j-jca
[SecureRandom]: https://docs.oracle.com/javase/8/docs/api/java/security/SecureRandom.html
[SecureRandom 1]: https://docs.oracle.com/javase/8/docs/api/java/security/SecureRandom.html#getInstanceStrong--
[PBKDF2 1]: https://github.com/Password4j/password4j/wiki/Recommended-settings#responsiveness
[bcrypt 1]: https://github.com/Password4j/password4j/wiki/Recommended-settings#responsiveness-1
[scrypt 1]: https://github.com/Password4j/password4j/wiki/Recommended-settings#responsiveness-2
[Argon2 1]: https://github.com/Password4j/password4j/wiki/Recommended-settings#responsiveness-3
[CONTRIBUTING.md]: https://github.com/Password4j/password4j/blob/master/CONTRIBUTING.md
[SemVer]: http://semver.org/
[Link 11]: https://github.com/Password4j/password4j/releases
[firaja]: https://github.com/firaja
[Link 12]: https://github.com/Password4j/password4j/contributors
[LICENSE]: https://github.com/Password4j/password4j/blob/master/LICENSE
[CHANGELOG.md]: https://github.com/Password4j/password4j/blob/master/CHANGELOG.md