# Announcing the \`password-hash\` crate

**URL:** <https://users.rust-lang.org/t/announcing-the-password-hash-crate/55383>\
**Category:** announcements\
**Created:** [February 9, 2021, 11:22pm UTC](https://users.rust-lang.org/t/announcing-the-password-hash-crate/55383 "2021-02-09T23:22:24Z")\
**Posts on this page:** 10\
**Page:** 1

<div class="post-metadata">

**Author:** ![bascule](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/bascule/32/8824_2.png) [@bascule](https://users.rust-lang.org/u/bascule)\
**Post date:** [February 9, 2021, 11:22pm UTC](https://users.rust-lang.org/t/announcing-the-password-hash-crate/55383/1 "2021-02-09T23:22:25Z")

</div>

The [RustCrypto Org](https://github.com/rustcrypto/traits) has released v0.1 of the `password-hash` crate, which provides traits and types for password hashing functions:

- **repo** : [https://github.com/RustCrypto/traits/tree/master/password-hash](https://github.com/RustCrypto/traits/tree/master/password-hash)
- **crate** : [https://crates.io/crates/password-hash](https://crates.io/crates/password-hash)
- **docs** : [password\_hash - Rust](https://docs.rs/password-hash/)

It provides an implementation of the [PHC string format](https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md) as well as support for [upgrading password hashes in the legacy Modular Crypt Format (MCF)](https://docs.rs/password-hash/0.1.1/password_hash/trait.McfHasher.html).

The `password-hash` crate is used by the following RustCrypto password hashing crates:

- [`argon2`](https://docs.rs/argon2)
- [`pbkdf2`](https://docs.rs/pbkdf2)
- [`scrypt`](https://docs.rs/scrypt)

The [`PasswordHash::verify_password`](https://docs.rs/password-hash/0.1.1/password_hash/struct.PasswordHash.html#method.verify_password) function makes it possible to specify multiple algorithms to verify a password hash against, allowing you to store password hashes with multiple algorithms and verify a password against all of them:

```rust
use password_hash::PasswordHash;

use argon2::Argon2;
use pbkdf2::Pbkdf2;
use scrypt::Scrypt;

let hash_string = load_hash_string_for_user(...); // e.g. `$argon2id$...`
let input_password = read_password_from_user();

let password_hash = PasswordHash::new(&hash_string)
    .expect("invalid password hash");

// Trait objects for algorithms to support
let algs = &[Argon2::default(), Pbkdf2, Scrypt];

if password_hash.verify_password(algs, input_password).is_ok() {
    access_granted();
} else {
    access_denied();
}

```

Enjoy!

---

<div class="post-metadata">

**Author:** ![197g](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/197g/32/13699_2.png) [@197g](https://users.rust-lang.org/u/197g)\
**Post date:** [February 10, 2021, 1:44am UTC](https://users.rust-lang.org/t/announcing-the-password-hash-crate/55383/2 "2021-02-10T01:44:17Z")

</div>

A part of this announcement that deserves some emphasis: The `argon2` crate finally emerges with proper use and belonging to the right group of people after having been reserved for four years. That's a good example to consider next time a discussion of crate reservation policy comes up.

---

<div class="post-metadata">

**Author:** ![djc](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/djc/32/2544_2.png) [@djc](https://users.rust-lang.org/u/djc)\
**Post date:** [February 10, 2021, 9:10am UTC](https://users.rust-lang.org/t/announcing-the-password-hash-crate/55383/3 "2021-02-10T09:10:47Z")

</div>

Do these implementations provide any constant-time guarantees? When I looked into password hashing last year, this was one of the sticking points for getting my implementation past the CISO.

---

<div class="post-metadata">

**Author:** ![newpavlov](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/newpavlov/32/6207_2.png) [@newpavlov](https://users.rust-lang.org/u/newpavlov)\
**Post date:** [February 10, 2021, 11:20am UTC](https://users.rust-lang.org/t/announcing-the-password-hash-crate/55383/4 "2021-02-10T11:20:47Z")

</div>

Note that I (a core member of the RustCrypto org together with @bascule) have reserved `argon2` in 2017, while the first version of `argon2rs` was registered in 2016. I went on a bit of "reservation" spree after I understood that unfortunately crate owners are not always open to cooperation or it could be practically impossible to reach them. I intentionally [didn't want](https://github.com/RustCrypto/password-hashes/issues/1#issuecomment-473003766) to create a competing implementations for crates with a good traction (plus the project had other priorities at the time), but I was open to [sharing](https://github.com/bryant/argon2rs/issues/40) the reserved names. Yes, it was on a condition of joining the project, I understand that some may not like such string attached, but it has worked well in the case of `rsa` and `hkdf`.

Though, I do agree with you regarding the need for a crate reservation policy. I even drafted my own [proposal](https://internals.rust-lang.org/t/pre-rfc-crates-expropriation-policy/8668) for it.

@djc  
Comparison of values and decoding of B64 is guaranteed to be done in const time (it's done via [`subtle`](https://docs.rs/subtle/) and [`base64ct`](https://docs.rs/base64ct/) respectively). For algorithms themselves we do not make such guarantees (e.g. for PBKDF2 it depends on properties of a used hash function and they generally do not care about const time), but as far as I know, it's not required for security, since only stored hashes are considered to be secret and not input passwords.

---

<div class="post-metadata">

**Author:** ![bascule](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/bascule/32/8824_2.png) [@bascule](https://users.rust-lang.org/u/bascule)\
**Post date:** [February 10, 2021, 12:39pm UTC](https://users.rust-lang.org/t/announcing-the-password-hash-crate/55383/5 "2021-02-10T12:39:40Z")

</div>

> [@djc](#):
>
> Do these implementations provide any constant-time guarantees? When I looked into password hashing last year, this was one of the sticking points for getting my implementation past the CISO.

There are two places where side-channel attacks on password hashing algorithms matter:

- When salts are absent, easily guessable, or leaked via accidental disclosure, there is a sophisticated timing attack on short-circuiting comparisons which makes it possible to obtain a hash prefix to aid a brute force search: [GitHub - aj-code/TimingIntrusionTool5000: A tool for performing network timing attacks on plaintext and hashed password authentication.](https://github.com/aj-code/TimingIntrusionTool5000)
- In the presence of an adversary who is able to observe and potentially influence the operation of a password hashing function (e.g. cotenant on the same host), side-channel attacks are possible

The `password-hash` crate mitigates the first via a constant-time comparison of the hash, but also by making it easy to generate a large, cryptographically random salt value. Taken together this provides a belt-and-suspenders defense against such attacks, but also note that they are somewhat impractical to begin with.

The second is really a matter of algorithm design. Argon2, for example, has two main variants: Argon2d which optimizes against attackers performing time-memory tradeoffs, and Argon2i which is hardened against side-channel attacks. The Argon2id variant is a hybrid mixture thereof which doesn't provide as good of a TMTO defense as Argon2d, but includes some of the side-channel protections of Argon2i.

In either case if side-channel resistance is a concern, we have options available.

---

<div class="post-metadata">

**Author:** ![newpavlov](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/newpavlov/32/6207_2.png) [@newpavlov](https://users.rust-lang.org/u/newpavlov)\
**Post date:** [February 10, 2021, 1:00pm UTC](https://users.rust-lang.org/t/announcing-the-password-hash-crate/55383/6 "2021-02-10T13:00:59Z")

</div>

> [@bascule](#):
>
> In the presence of an adversary who is able to observe and potentially influence the operation of a password hashing function (e.g. cotenant on the same host), side-channel attacks are possible

Can you link any relevant articles about this attack scenario? If I understand it correctly, you mean that attacker will be able to reconstruct user password by observing computation timings, but I think that for password hashing it's far less important than for encryption, to the point of impracticality. If a legitimate user enters a correct password, then computation is done only once, so to accumulate enough data adversary has not only to be able to know which user logins at the moment, but also listen long enough for selected user logins which are few and far in between. And even before that, password hashing is an intentionally long computation, which uses plain text password only in the very initial computation steps, thus making recovery of a plaintext password from timings even harder.

But either way, ideally plaintext password should not leave user computer in the first place. In other words, people should use [PAKE](https://en.wikipedia.org/wiki/Password-authenticated_key_agreement) whenever possible.

---

<div class="post-metadata">

**Author:** ![bascule](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/bascule/32/8824_2.png) [@bascule](https://users.rust-lang.org/u/bascule)\
**Post date:** [February 10, 2021, 1:22pm UTC](https://users.rust-lang.org/t/announcing-the-password-hash-crate/55383/7 "2021-02-10T13:22:29Z")

</div>

> [@newpavlov](#):
>
> Can you link any relevant articles about this attack scenario?

I agree it's a somewhat impractical scenario. One of the main places it's discussed is in the Argon2 paper (see sections 2.2, 3, and 4.1, for example):

> <https://github.com/P-H-C/phc-winner-argon2/blob/master/argon2-specs.pdf>

---

<div class="post-metadata">

**Author:** ![djc](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/djc/32/2544_2.png) [@djc](https://users.rust-lang.org/u/djc)\
**Post date:** [February 10, 2021, 1:35pm UTC](https://users.rust-lang.org/t/announcing-the-password-hash-crate/55383/8 "2021-02-10T13:35:56Z")

</div>

One of the side channels they were worried about at my previous employer was leaking the existence of a named user. Obviously this goes beyond just the password hashing, but it's important to understand the performance characteristics of the password hash verification step as well.

---

<div class="post-metadata">

**Author:** ![bascule](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/bascule/32/8824_2.png) [@bascule](https://users.rust-lang.org/u/bascule)\
**Post date:** [February 10, 2021, 3:27pm UTC](https://users.rust-lang.org/t/announcing-the-password-hash-crate/55383/9 "2021-02-10T15:27:53Z")

</div>

Yeah, user enumeration attacks are rather tricky and most systems are vulnerable in some way or another.

In that case the much larger timing sidechannel will generally be whether the password hashing function was run at all or not, as opposed to the much smaller timing variability of a short-circuiting comparison of the hash.

Systems which want to avoid this attack should always run the password hashing function, substituting a placeholder/random salt in the event a user isn't found, and then ignoring the resulting hash in the event of a nonexistent user.

---

<div class="post-metadata">

**Author:** ![system](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/system/32/51372_2.png) [@system](https://users.rust-lang.org/u/system)\
**Post date:** [May 11, 2021, 3:28pm UTC](https://users.rust-lang.org/t/announcing-the-password-hash-crate/55383/10 "2021-05-11T15:28:04Z")

</div>

Closed on May 11, 2021, 3:28pm UTC

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.
