Yescrypt Save

What is yescrypt?

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.

As of this writing, 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're making 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 standard or popular libraries, making it more suitable for smaller deployments as well.

Parameter selection.

Please refer to PARAMETERS for guidelines on parameter selection and the currently recommended parameter sets by use case (password hashing with or without a ROM, and KDF).

Performance.

Please refer to PERFORMANCE for example setup and benchmarks relevant to the mass user authentication use case.

The test system is a server (kindly provided by Packet.net) 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:

• Greater resistance to offline attacks
• Extra optional built-in features
• Cryptographic security provided by NIST-approved primitives
• SHA-256, HMAC, PBKDF2, and scrypt are usable from the same codebase

yescrypt's drawbacks:

• Complex
• Cache-timing unsafe (like scrypt and Argon2d, but unlike Argon2i)
• Not the PHC winner (Argon2 is), but is merely a "special recognition"
• Supported in fewer third-party projects

Please refer to COMPARISON for a lot more detail and 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. The yespower homepage is:

https://www.openwall.com/yespower/


How to test yescrypt for proper operation.

On a Unix-like system, invoke "make check". This will build and run a program called "tests", and check its output against the supplied file TESTS-OK. It will also build a program called "phc-test", and if a file called PHC-TEST-OK-SHA256 is present will run that program and check its output against that file's contents. If everything matches, each of these two sets of tests prints one word "PASSED", so there will be two such lines among "make check" output, one of them being the final line of output.

We do most of our testing on Linux systems with gcc. The supplied Makefile assumes that you use gcc.

ROM in SysV shared memory demo and benchmark.

Also included with this version of yescrypt are "initrom" and "userom" demo programs. They're built by simply typing "make". Please refer to PERFORMANCE for their usage.

Alternate code versions and make targets.

Two implementations of yescrypt are included: reference and optimized. By default, the optimized implementation is built. Internally, the optimized implementation uses conditional compilation to choose between usage of various SIMD instruction sets where supported and scalar code.

The reference implementation is unoptimized and is very slow, but it has simpler and shorter source code. Its purpose is to provide a simple human- and machine-readable specification that implementations intended for actual use should be tested against. It is deliberately mostly not optimized, and it is not meant to be used in production.

Similarly to "make check", there's "make check-ref" to build and test the reference implementation. There's also "make ref" to build the reference implementation and have the "initrom" and "userom" programs use it.

"make clean" may need to be run between making different builds.

Development status.

This yescrypt distribution is a work-in-progress. Its interfaces other than crypto_scrypt() are subject to change in future revisions, however no incompatible changes to the yescrypt algorithm are expected.

Credits.

scrypt has been designed by Colin Percival. yescrypt has been designed by Solar Designer building upon scrypt.

The following other people and projects have also indirectly helped make yescrypt what it is:

• Bill Cox

• Rich Felker

• Anthony Ferrara

• Christian Forler

• Taylor Hornby

• Dmitry Khovratovich

• Samuel Neves

• Marcos Simplicio

• Ken T Takusagawa

• Jakob Wenzel

• Christian Winnerlein

• DARPA Cyber Fast Track

• Password Hashing Competition

  Contact info.

First, please check the yescrypt homepage for new versions, etc.:

https://www.openwall.com/yescrypt/

If you have anything valuable to add or a non-trivial question to ask, you may join and post to the yescrypt mailing list (referenced on the yescrypt homepage above) or contact the maintainer of yescrypt at:

Solar Designer <solar at openwall.com>