Password authentication for web and mobile apps (e-book)

yescrypt - scalable KDF and password hashing scheme

yescrypt is a password-based key derivation function (KDF) and password hashing scheme. It builds upon Colin Percival's scrypt. This implementation is able to compute native yescrypt hashes as well as classic scrypt. For a related proof-of-work (PoW) scheme, see yespower instead.

Download the primary, full-featured implementation in C (current release notes, original release notes):

Download the light, reduced feature set implementation in Go (release notes):

These and older versions of yescrypt are also available from the Openwall file archive. The source code of yescrypt can be browsed on GitHub (C, Go).

Follow this link for information on verifying the signatures.

Please check out our presentation slides on yescrypt. (Some of the detail on the last few slides pertains to yescrypt 0.9.x and is no longer valid for yescrypt 1.0+, but overall this slide deck still applies.)

We can help you integrate yescrypt into your software or online services. Please check out our services.

Contributed resources:

yescrypt is the default password hashing scheme on recent ALT Linux, Arch Linux, Debian 11+, Fedora 35+, Kali Linux 2021.1+, and Ubuntu 22.04+. It is also supported in Fedora 29+, RHEL 9+, and Ubuntu 20.04+, and is recommended for new passwords in Fedora CoreOS.

Why yescrypt?

Like it or not, password authentication remains relevant (including as one of several authentication factors), password hash database leaks happen, the leaks are not always detected and fully dealt with right away, and even once they are many users' same or similar passwords reused elsewhere remain exposed. To mitigate these risks (as well as those present in other scenarios where password-based key derivation or password hashing is relevant), computationally expensive (bcrypt, PBKDF2, etc.) and more recently also memory-hard (scrypt, Argon2, etc.) password hashing schemes have been introduced. Unfortunately, at high target throughput and/or low target latency their memory usage is unreasonably low, up to the point where they're not obviously better than the much older bcrypt (considering attackers with pre-existing hardware). This is a primary drawback that yescrypt addresses.

Most notable for large-scale deployments is yescrypt's optional initialization and reuse of a large lookup table, typically occupying at least tens of gigabytes of RAM and essentially forming a site-specific ROM. This limits attackers' use of pre-existing hardware such as botnet nodes.

yescrypt's other changes from scrypt additionally slow down GPUs and to a lesser extent FPGAs and ASICs even when its memory usage is low and even when there's no ROM, and provide extra knobs and built-in features.

Technically, yescrypt is the most scalable password hashing scheme so far, providing near-optimal security from offline password cracking across the whole range from kilobytes to terabytes and beyond. However, the price for this is complexity, and we recognize that complexity is a major drawback of any software. Thus, at this time we focus on large-scale deployments, where the added complexity is relatively small compared to the total complexity of the authentication service setup. For smaller deployments, bcrypt with its simplicity and existing library support is a reasonable short-term choice (although we made progress towards more efficient FPGA attacks on bcrypt under a separate project). We might introduce a cut-down yescrypt-lite later or/and yescrypt might become part of more standard or popular libraries (and it is already in libxcrypt), making it more suitable for smaller deployments as well.

Performance

Please see the PERFORMANCE file inside the yescrypt distribution for example setup and benchmarks relevant to the mass user authentication use case.

The test system is a server (kindly provided by Packet) with dual Xeon Gold 5120 CPUs (2.2 GHz, turbo to up to 3.2 GHz) and 384 GiB RAM (12x DDR4-2400 ECC Reg). These CPUs have 14 cores and 6 memory channels each, for a total of 28 physical cores, 56 logical CPUs (HT is enabled), and 12 memory channels.

Some highlights: initialization of a 368 GiB ROM takes 22 seconds (to be done on server bootup), and while using the ROM we're able to compute over 21k, over 10k, or around 1200 hashes per second with per-hash RAM usage of 1.4375 MiB, 2.875 MiB, or 23 MiB, respectively.

When not using a ROM, we're able to compute over 21k, over 10k, or around 1200 hashes per second with per-hash RAM usage of 2 MiB, 4 MiB, or 32 MiB, respectively.

Comparison to scrypt and Argon2

yescrypt's advantages:

yescrypt's drawbacks:

Other observations:

A note on cryptocurrencies

For historical reasons, multiple CPU mining focused cryptocurrencies use yescrypt 0.5'ish as their proof-of-work (PoW) scheme. We currently have a separate project for the PoW use case: yespower. Thus, rather than misuse yescrypt 1.0+ for PoW, those and other projects are advised to use yespower 1.0+ instead.

Quick Comment:

248449