# gopasshash

**Repository Path**: muleiwu/gopasshash

## Basic Information

- **Project Name**: gopasshash
- **Description**: No description available
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-09
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gopasshash

中文文档 | [English](README.md)

[![Go Version](https://img.shields.io/badge/Go-1.25+-blue.svg)](https://golang.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

gopasshash 是一个可插拔的 Go 密码哈希和密码演进库。根包只提供面向调用方的 `Hasher` 和算法接口，具体算法放在独立子包里，由调用方显式装配。

这是纯插件模式：没有全局默认 hasher，也没有零配置的 `gopasshash.Hash` 或 `gopasshash.Verify`。

## 特性

- 根包 `gopasshash` 提供 hash、verify、inspect 和登录时升级入口
- 可插拔的 `argon2id`、`bcrypt`、`pbkdf2` 算法包
- 在已配置算法中根据 hash 前缀自动分发校验
- 使用 `VerifyAndUpgrade` 在登录成功后迁移旧 hash
- KDF 插件和 Bitwarden/Vaultwarden 兼容 helper 拆到独立包
- 对不支持的算法和错误格式返回明确错误

## 安装

```bash
go get github.com/muleiwu/gopasshash
```

## 快速开始

```go
package main

import (
	"fmt"

	gopasshash "github.com/muleiwu/gopasshash"
	"github.com/muleiwu/gopasshash/argon2id"
	"github.com/muleiwu/gopasshash/bcrypt"
	"github.com/muleiwu/gopasshash/pbkdf2"
)

func main() {
	hasher, err := gopasshash.New(
		argon2id.Default(),
		gopasshash.WithVerifiers(
			pbkdf2.Default(),
			bcrypt.Default(),
		),
	)
	if err != nil {
		panic(err)
	}

	encodedHash, err := hasher.Hash("correct horse battery staple")
	if err != nil {
		panic(err)
	}

	match, err := hasher.Verify("correct horse battery staple", encodedHash)
	if err != nil {
		panic(err)
	}

	fmt.Println(match)
}
```

## 支持算法

按需导入和配置算法包：

| 算法 | 标识符 | 安全 |
| --- | --- | --- |
| [argon2id](https://pkg.go.dev/github.com/muleiwu/gopasshash/argon2id) | `argon2id`（`$argon2id$`） | ✔️ |
| [bcrypt](https://pkg.go.dev/github.com/muleiwu/gopasshash/bcrypt) | `2a`、`2b`、`2y`（`$2a$`、`$2b$`、`$2y$`） | ✔️ |
| [pbkdf2](https://pkg.go.dev/github.com/muleiwu/gopasshash/pbkdf2) | `pbkdf2`、`pbkdf2-sha224`、`pbkdf2-sha256`、`pbkdf2-sha384`、`pbkdf2-sha512` | ✔️ |

Argon2id 默认参数：

```text
m=65536,t=3,p=2,salt=16,key=32
```

Argon2id hash 格式：

```text
$argon2id$v=19$m=65536,t=3,p=2$<salt>$<hash>
```

PBKDF2 hash 格式：

```text
$pbkdf2-sha256$i=600000,l=32$<salt>$<hash>
```

其他 PBKDF2 variants 使用相同格式，只替换 identifier。

## 自定义目标策略

```go
target, err := argon2id.New(argon2id.Params{
	Memory:      64 * 1024,
	Iterations:  3,
	Parallelism: 2,
	SaltLength:  16,
	KeyLength:   32,
})
if err != nil {
	panic(err)
}

legacyPBKDF2, err := pbkdf2.New(pbkdf2.Params{
	Digest:     pbkdf2.DigestSHA256,
	Iterations: 600000,
	SaltLength: 32,
	KeyLength:  32,
})
if err != nil {
	panic(err)
}

hasher, err := gopasshash.New(target, gopasshash.WithVerifiers(legacyPBKDF2, bcrypt.Default()))
if err != nil {
	panic(err)
}
```

## 登录时升级

```go
result, err := hasher.VerifyAndUpgrade(password, storedHash)
if err != nil {
	return err
}
if !result.Match {
	return nil
}
if result.NeedsRehash {
	// 将 result.NewHash 保存到当前用户。
}
```

`VerifyAndUpgrade` 只会在密码校验成功后生成新 hash。如果源算法或参数和目标算法不一致，`NeedsRehash` 为 true，`NewHash` 包含升级后的 hash。

## Inspect

```go
info, err := hasher.Inspect(storedHash)
if err != nil {
	panic(err)
}
fmt.Println(info.Algorithm, info.Params)
```

## KDF 和兼容 Helper

```go
kdf, err := pbkdf2.NewKDF(pbkdf2.KDFParams{
	Digest:     pbkdf2.DigestSHA256,
	Iterations: 600000,
	KeyLength:  32,
})
if err != nil {
	panic(err)
}

key, err := kdf.Derive([]byte("password"), []byte("salt"))
```

Bitwarden helper 在 `github.com/muleiwu/gopasshash/bitwarden` 包中。Vaultwarden 风格的服务端 PBKDF2 helper 在 `github.com/muleiwu/gopasshash/vaultwarden` 包中。

## 说明

- 本库保存的是单向密码哈希，不是可逆密码加密。
- 密码强度、最小长度、锁定策略、注册和登录业务规则由调用方负责。
- Bitwarden/Vaultwarden helper 不实现 vault item 加密或数据重加密。
- 不支持的 hash 前缀会返回 `ErrUnsupportedAlgorithm`。