From bfb31d1b80e89b62e79a710ee2ec3c7836df6ce1 Mon Sep 17 00:00:00 2001 From: Gautier DI FOLCO Date: Sat, 4 Oct 2025 23:42:59 +0200 Subject: [PATCH 1/2] Add documentation about the `password-cli` (#83) --- README.md | 2 ++ password/README.md | 4 +++- password/src/Data/Password/Argon2.hs | 9 +++++++++ password/src/Data/Password/Bcrypt.hs | 9 +++++++++ password/src/Data/Password/PBKDF2.hs | 9 +++++++++ password/src/Data/Password/Scrypt.hs | 9 +++++++++ 6 files changed, 41 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4316013..cc25c30 100644 --- a/README.md +++ b/README.md @@ -29,3 +29,5 @@ and In general, if you are writing a web application and need to handle passwords, you should use the `password` package together with `password-instances`. + +This project also provides [password-cli](./password-cli) a CLI to test and use `password`. diff --git a/password/README.md b/password/README.md index 48ad4bc..f568592 100644 --- a/password/README.md +++ b/password/README.md @@ -8,7 +8,7 @@ This library provides functions for working with passwords and password hashes in Haskell. -Currently supports the following algorithms: +It currently supports the following algorithms: * `PBKDF2` * `bcrypt` @@ -17,3 +17,5 @@ Currently supports the following algorithms: Also, see the [password-instances](https://hackage.haskell.org/package/password-instances) package for instances for common typeclasses. + +To quickly test and use `password`, you can use [password-cli](https://github.com/cdepillabout/password/tree/master/password-cli). diff --git a/password/src/Data/Password/Argon2.hs b/password/src/Data/Password/Argon2.hs index 0f02d46..6917478 100644 --- a/password/src/Data/Password/Argon2.hs +++ b/password/src/Data/Password/Argon2.hs @@ -33,6 +33,15 @@ being the newest algorithm out there. It is, however, recommended over @'Data.Password.Scrypt.Scrypt'@ most of the time, and it also seems like it might become the go-to password algorithm if no vulnarabilities are discovered within the next couple of years. + +== Testing + +You can use [password-cli](https://github.com/cdepillabout/password/tree/master/password-cli) to test it: + +> $ password-cli check argon2 --hash 'SOME-HASH' + +> $ password-cli hash argon2 --password-file password.txt + -} -- I think the portability is broadened to diff --git a/password/src/Data/Password/Bcrypt.hs b/password/src/Data/Password/Bcrypt.hs index 426d41f..5de4d5b 100644 --- a/password/src/Data/Password/Bcrypt.hs +++ b/password/src/Data/Password/Bcrypt.hs @@ -42,6 +42,15 @@ Now while the very first version of @bcrypt@ would have hashes that were 59 char because of the 1 character-long "$2$" version prefix, @bcrypt@ has had a version increase shortly after release, turning the prefix into a 2 character-long one like "$2a$" pretty much from the very beginning. + +== Testing + +You can use [password-cli](https://github.com/cdepillabout/password/tree/master/password-cli) to test it: + +> $ password-cli check bcrypt --hash 'SOME-HASH' + +> $ password-cli hash bcrypt --password-file password.txt + -} module Data.Password.Bcrypt ( diff --git a/password/src/Data/Password/PBKDF2.hs b/password/src/Data/Password/PBKDF2.hs index ad46238..709c375 100644 --- a/password/src/Data/Password/PBKDF2.hs +++ b/password/src/Data/Password/PBKDF2.hs @@ -35,6 +35,15 @@ When unsure, @'Data.Password.Bcrypt.Bcrypt'@ would probably be the safest option, as it has no memory cost which could become a problem if not properly calibrated to the machine doing the password verifications. + +== Testing + +You can use [password-cli](https://github.com/cdepillabout/password/tree/master/password-cli) to test it: + +> $ password-cli check pbkdf2 --hash 'SOME-HASH' + +> $ password-cli hash pbkdf2 --password-file password.txt + -} module Data.Password.PBKDF2 ( diff --git a/password/src/Data/Password/Scrypt.hs b/password/src/Data/Password/Scrypt.hs index ec80569..6e80be9 100644 --- a/password/src/Data/Password/Scrypt.hs +++ b/password/src/Data/Password/Scrypt.hs @@ -30,6 +30,15 @@ thus is fine for protection against brute-force attacks. Because of the memory cost, it is generally advised to use @'Data.Password.Bcrypt.Bcrypt'@ if you're not sure this might be a problem on your system. + +== Testing + +You can use [password-cli](https://github.com/cdepillabout/password/tree/master/password-cli) to test it: + +> $ password-cli check scrypt --hash 'SOME-HASH' + +> $ password-cli hash scrypt --password-file password.txt + -} module Data.Password.Scrypt ( From 00ea6ccdf7394b6e44d9de53a4dfbdca6b8e49fa Mon Sep 17 00:00:00 2001 From: Gautier DI FOLCO Date: Tue, 7 Oct 2025 22:11:27 +0200 Subject: [PATCH 2/2] Use simple quotes in examples --- password-cli/README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/password-cli/README.md b/password-cli/README.md index 83dbef7..eb61df1 100644 --- a/password-cli/README.md +++ b/password-cli/README.md @@ -70,7 +70,7 @@ Just like when hashing a password, you can input the password manually, through by providing a `--password-file`. ```console $ # Interactively check password -$ password-cli check argon2 --hash "SOME-HASH" +$ password-cli check argon2 --hash 'SOME-HASH' Enter password: Password matches provided hash $ echo $? @@ -80,14 +80,18 @@ If the provided hash doesn't match the password, `Password does not match provid will be shown and the exit code will be `1` to indicate a failed match. ```console $ # Pipe in the password. -$ cat password.txt | password-cli check argon2 --hash "SOME-HASH" --quiet +$ cat password.txt | password-cli check argon2 --hash 'SOME-HASH' --quiet $ echo $? 0 $ # Give the WRONG password file. -$ password-cli check argon2 --hash "SOME-HASH" --password-file password.txt.wrong --quiet +$ password-cli check argon2 --hash 'SOME-HASH' --password-file password.txt.wrong --quiet $ echo $? 1 ``` +NOTE: When giving literal hashes as arguments in the terminal, +it is advised to use single quotes (`'`) instead of double quotes (`"`) +to prevent any accidental interpolation as some hashes use +dollar signs (`$`) in the format. You can also provide the hash from file contents by providing the path to the `--hash-file` option. Just like the default of the `--password-file` option, this will only read up to the