password_ : Secure Password Hashing Made Simple

A lightweight and secure password hashing library based on Argon2.

Introduction
Usage
Design
Tech Stack
Directory Structure
API Reference
History

Introduction

password_ provides a simplified interface for hashing and verifying passwords using the state-of-the-art Argon2 algorithm. It abstracts away complex configuration, offering secure defaults for immediate use.

Usage

See tests/main.rs for a complete demonstration.

use aok::{OK, Void};
use log::info;

fn main() -> Void {
  let password = "test";
  // Generate a random salt and hash the password
  let (salt, hash) = password_::hash(password);
  
  info!("{salt:?} {hash:?}");

  // Verify the password against the salt and hash
  assert!(password_::verify(password, &salt, &hash));
  
  OK
}

Design

The library uses a static configuration for Argon2 to ensure consistency and security:

Algorithm: Argon2id (hybrid version, resistant to GPU and side-channel attacks).
Version: 0x13.
Memory: 64 MB (65536 KB).
Iterations: 3.
Parallelism: 1.
Output Length: 32 bytes.

The hash function generates a random 16-byte salt and computes the 32-byte hash. The verify function re-computes the hash using the provided salt and compares it with the stored hash.

Tech Stack

Language: Rust
Core Algorithm: argon2 crate
Randomness: rand crate
Initialization: static_init crate

Directory Structure

.
├── src/
│   └── lib.rs       # Core logic and API definitions
├── tests/
│   └── main.rs      # Usage demonstration and tests
├── readme/          # Documentation
└── Cargo.toml       # Project configuration

API Reference

The library exports the following from lib.rs:

Types

SALT: Alias for [u8; 16].
HASH: Alias for [u8; 32].

Functions

fn hash(password: impl AsRef<[u8]>) -> (SALT, HASH) Generates a random salt and returns the (salt, hash) tuple.
fn hash_with_salt(password: impl AsRef<[u8]>, salt: impl AsRef<[u8]>) -> HASH Computes the hash for a given password and salt.
fn verify(password: impl AsRef<[u8]>, salt: impl AsRef<[u8]>, hash: impl AsRef<[u8]>) -> bool Verifies if the password matches the provided salt and hash.

History

In 2013, the Password Hashing Competition (PHC) was launched to find a successor to aging algorithms like PBKDF2 and bcrypt, which were becoming vulnerable to GPU-based attacks. After two years of rigorous analysis, Argon2 was selected as the winner in July 2015. Designed by Alex Biryukov, Daniel Dinu, and Dmitry Khovratovich, Argon2 introduced memory-hardness properties that make it prohibitively expensive to crack using specialized hardware, setting a new standard for password security.

About

This project is an open-source component of js0.site ⋅ Refactoring the Internet Plan.

We are redefining the development paradigm of the Internet in a componentized way. Welcome to follow us:

password_ : 简单安全的密码哈希库

基于 Argon2 算法的轻量级安全密码哈希库。

简介

password_ 为密码哈希和验证提供了简化的接口，底层采用先进的 Argon2 算法。它封装了复杂的配置参数，提供安全的默认设置，开箱即用。

使用演示

完整演示请参考 tests/main.rs。

use aok::{OK, Void};
use log::info;

fn main() -> Void {
  let password = "test";
  // 生成随机盐并计算哈希
  let (salt, hash) = password_::hash(password);
  
  info!("{salt:?} {hash:?}");

  // 验证密码是否匹配
  assert!(password_::verify(password, &salt, &hash));
  
  OK
}

设计思路

本库采用静态的 Argon2 配置以确保一致性和安全性：

算法: Argon2id (混合版本，抗 GPU 和侧信道攻击)。
版本: 0x13。
内存: 64 MB (65536 KB)。
迭代次数: 3。
并行度: 1。
输出长度: 32 字节。

hash 函数生成一个随机的 16 字节盐值并计算 32 字节哈希值。verify 函数使用提供的盐值重新计算哈希，并与存储的哈希值进行比对。

技术堆栈

语言: Rust
核心算法: argon2 crate
随机数: rand crate
初始化: static_init crate

目录结构

.
├── src/
│   └── lib.rs       # 核心逻辑与 API 定义
├── tests/
│   └── main.rs      # 使用演示与测试
├── readme/          # 文档
└── Cargo.toml       # 项目配置

API 参考

lib.rs 导出以下内容：

类型

SALT: [u8; 16] 的别名。
HASH: [u8; 32] 的别名。

函数

fn hash(password: impl AsRef<[u8]>) -> (SALT, HASH) 生成随机盐并返回 (salt, hash) 元组。
fn hash_with_salt(password: impl AsRef<[u8]>, salt: impl AsRef<[u8]>) -> HASH 使用给定的盐计算密码哈希。
fn verify(password: impl AsRef<[u8]>, salt: impl AsRef<[u8]>, hash: impl AsRef<[u8]>) -> bool 验证密码是否与提供的盐和哈希匹配。

历史轶事

2013 年，为了寻找 PBKDF2 和 bcrypt 等老旧算法的继任者（这些算法在 GPU 攻击面前日益脆弱），密码哈希竞赛 (PHC) 正式启动。经过两年的严格分析，Argon2 于 2015 年 7 月脱颖而出夺得桂冠。Argon2 由 Alex Biryukov、Daniel Dinu 和 Dmitry Khovratovich 设计，引入了内存硬化 (memory-hardness) 特性，使得使用专用硬件破解密码的成本极其高昂，从而树立了密码安全的新标准。

关于

本项目为 js0.site ⋅ 重构互联网计划的开源组件。

我们正在以组件化的方式重新定义互联网的开发范式，欢迎关注：

password_ 0.1.1