Passwap

https://github.com/zitadel/passwap
Admin
Passwap provides a unified implementation for various password hashing algorithms in Go, allowing...
Tokens:3,330
Snippets:13
Trust Score:9.5
License:BSD-3-Clause
Update:1 year ago
Show doc for...
Tokens:
Raw
### PBKDF2 Modular Crypt Format Example

Source: https://github.com/zitadel/passwap/blob/main/README.md

An example of a Modular Crypt Format (MCF) string generated by the PBKDF2 hashing algorithm. It illustrates the different components: algorithm identifier, cost parameter, salt, and hash output.

```plaintext
$pbkdf2-sha256$12$cmFuZG9tc2FsdGlzaGFyZA$OFvEcLOIPFd/oq8egf10i.qJLI7A8nDjPLnolCWarQY
```

--------------------------------

### MD5 Plain Hashing Verification

Source: https://github.com/zitadel/passwap/blob/main/README.md

Explains that MD5 Plain uses hex-encoded digests without salt and is supported for verification purposes only due to its insecurity. Provides examples of how it might be generated in Linux, PHP, and Python.

```Python
import hashlib

password = b"password"

# MD5 Plain hash (hex encoded, no salt)
md5_plain_hash = hashlib.md5(password).hexdigest()
print(f"MD5 Plain Hash: {md5_plain_hash}")

# Example output:
# MD5 Plain Hash: 5f4dcc3b5aa4698c089e1f261155c750
```

--------------------------------

### Bcrypt Hashing Format

Source: https://github.com/zitadel/passwap/blob/main/README.md

Explains the Modular Crypt Format for Bcrypt, including the identifier, cost parameter, salt, and hash. It notes that the Go package 'golang.org/x/crypto/bcrypt' handles the implementation.

```Go
package main

import (
	"fmt"
	"golang.org/x/crypto/bcrypt"
)

func main() {
	password := []byte("mysecretpassword")

	// Hash the password
	hashedPassword, err := bcrypt.GenerateFromPassword(password, bcrypt.DefaultCost)
	if err != nil {
		fmt.Println("Error hashing password:", err)
		return
	}

	fmt.Printf("Bcrypt Hash: %s\n", hashedPassword)

	// Example of the expected format:
	// $2a$12$aLYFkieuqJyeynvptPTxpehSViui5WeAPuR2Xw1wui9CPHEaacmFq
}
```

--------------------------------

### Hash Password with Bcrypt

Source: https://github.com/zitadel/passwap/blob/main/README.md

Initializes a Swapper with bcrypt using the default cost and hashes a given password. The resulting encoded string includes the algorithm identifier, cost, salt, and the hashed password.

```Go
passwords := passwap.NewSwapper(
    bcrypt.New(bcrypt.DefaultCost),
)

encoded, err := passwords.Hash("good_password")
if err != nil {
    panic(err)
}
fmt.Println(encoded)
// $2a$10$eS.mS5Zc5YAJFlImXCpLMu9TxXwKUhgQxsbghlvyVwvwYO/17E2qy
```

--------------------------------

### Scrypt Hashing Format

Source: https://github.com/zitadel/passwap/blob/main/README.md

Details the Scrypt hashing format, which uses standard raw Base64 encoding. It covers the identifier, cost parameters (memory, block size, parallelism), salt, and the Scrypt hash output.

```N/A
-- Example of Scrypt format:
-- $scrypt$ln=16,r=8,p=1$cmFuZG9tc2FsdGlzaGFyZA$Rh+NnJNo1I6nRwaNqbDm6kmADswD1+7FTKZ7Ln9D8nQ
-- (1) Identifier: always 'scrypt'
-- (2) Cost parameters: ln (memory/CPU cost), r (block size), p (parallelism)
-- (3) Salt: Base64-encoded salt
-- (4) Hash: Base64-encoded Scrypt hash output
```

--------------------------------

### MD5 Crypt Hashing Format

Source: https://github.com/zitadel/passwap/blob/main/README.md

Describes the Modular Crypt Format for MD5 Crypt, detailing the identifier, salt, and hash. It mentions that MD5 Crypt is provided for verification and migration due to its insecurity.

```N/A
-- Example of MD5 Crypt format:
-- $1$kJ4QkJaQ$3EbD/pJddrq5HW3mpZ4KZ1
-- (1) Identifier: always '1'
-- (2) Salt: Base64-like-encoded
-- (3) Hash: Base64-like-encoded MD5 hash output
```

--------------------------------

### Verify Password and Migrate from Bcrypt to Argon2id

Source: https://github.com/zitadel/passwap/blob/main/README.md

Creates a new Swapper configured for argon2id hashing while also including a bcrypt verifier to handle existing bcrypt-hashed passwords. When verifying a password, if the original hash was created with bcrypt, the library automatically returns an updated hash generated with argon2id.

```Go
passwords = passwap.NewSwapper(
    argon2.NewArgon2id(argon2.RecommendedIDParams),
    bcrypt.Verifier,
)
if updated, err := passwords.Verify(encoded, "good_password"); err != nil {
    panic(err)
} else if updated != "" {
    encoded = updated // store in "DB"
}
fmt.Println(encoded)
```

--------------------------------

### Argon2 Hashing Format

Source: https://github.com/zitadel/passwap/blob/main/README.md

Demonstrates the Modular Crypt Format for Argon2 hashing, including the identifier, cost parameters (memory, time, parallelism), base64 encoded salt, and the final hash output. This format is used for storing and verifying password hashes.

```Go
$argon2i$v=19$m=4096,t=3,p=1$cmFuZG9tc2FsdGlzaGFyZA$YMvo8AUoNtnKYGqeODruCjHdiEbl1pKL2MsYy9VgU/E
```

--------------------------------

### PHPass Hashing Format

Source: https://github.com/zitadel/passwap/blob/main/README.md

Describes the PHPass hashing format, commonly used in PHP applications like WordPress. It outlines the identifier ('P' or 'H'), rounds, salt length, and the MDF hash output.

```PHP
<?php

// Example of PHPass format:
// $P$8ohUJ.1sdFw09/bMaAQPTGDNi2BIUt1
// (1) Identifier: 'P' (or 'H' for phpBB3)
// (2) Rounds: Single character representing rounds
// (3) Salt: 8 characters long
// (4) Hash: Base64-like-encoded MDF hash output

// Note: Actual PHPass generation requires a library like PassLib or a direct implementation.
// This is a representation of the format.
?>

```

--------------------------------

### Update Argon2id Parameters

Source: https://github.com/zitadel/passwap/blob/main/README.md

Demonstrates updating the parameters for the argon2id hashing algorithm, specifically increasing the 'Time' parameter to enhance security with improved hardware. It includes the bcrypt verifier to maintain compatibility with older hashes.

```Go
passwords = passwap.NewSwapper(
    argon2.NewArgon2id(argon2.Params{
        Time:    2,
        Memory:  64 * 1024,
        Threads: 4,
        KeyLen:  32,
        SaltLen: 16,
    }),
    bcrypt.Verifier,
)
if updated, err := passwords.Verify(encoded, "good_password"); err != nil {
    panic(err)
} else if updated != "" {
    encoded = updated
}
```

--------------------------------

### MD5 Salted Hashing Format

Source: https://github.com/zitadel/passwap/blob/main/README.md

Details the MD5 Salted format, which uses base64 encoding for the digest of password and salt. It specifies the identifier, salt string, and the combined hash output.

```N/A
-- Example of MD5 Salted format:
-- $md5salted-suffix$kJ4QkJaQ$3EbD/pJddrq5HW3mpZ4KZ1
-- (1) Identifier: md5salted-suffix or md5salted-prefix
-- (2) Salt: Salt string to be added to the password
-- (3) Hash: Base64-like-encoded MD5 hash output
```

--------------------------------

### SHA2 Crypt Hashing Format

Source: https://github.com/zitadel/passwap/blob/main/README.md

Explains the SHA2 Crypt format, which is similar to MD5 Crypt but uses SHA-256 or SHA-512. It details the identifier ('5' or '6'), the optional rounds parameter, salt, and hash.

```N/A
-- Example of SHA2 Crypt format (SHA-256):
-- $5$rounds=5000$RPvilwjD1ebXJfzg$5B8vYYiY.CVt1RlTTf8KbXBH3hsxY/GNooZaBBGWEc5
-- (1) Identifier: '5' (SHA-256) or '6' (SHA-512)
-- (2) Rounds: Cost parameter (e.g., 5000)
-- (3) Salt: Base64-like-encoded salt
-- (4) Hash: Base64-like-encoded SHA-256/512 hash output
```

--------------------------------

### Verify Password with Argon2id (No Migration)

Source: https://github.com/zitadel/passwap/blob/main/README.md

Verifies a password against an argon2id-hashed string. If the hash was created using the same algorithm and parameters, the 'updated' variable returned by Verify will be empty, indicating no migration occurred.

```Go
if updated, err := passwords.Verify(encoded, "good_password"); err != nil {
    panic(err)
} else if updated != "" { // updated is empty, nothing is stored
    encoded = updated
}
fmt.Println(encoded)
```
Tokens:
Raw