EVP_KDF-SCRYPT(7ossl)

📦
version 15.1 · 3 versions
, in freebsd 15.1

💜 EVP_KDF-SCRYPT — the scrypt vibe, explained

okay so bestie, welcome to EVP_KDF-SCRYPT(7ossl), one of the OpenSSL man pages (yes we're in the 7ossl section, it's giving documentation energy ✨). This is the whole rundown on the scrypt password-based KDF and how to drive it through the EVP_KDF API. Buckle up, it's actually so good.

🌸 NAME

EVP_KDF-SCRYPT — the scrypt implementation of the EVP_KDF family, aka the memory-hard one that makes GPU-havers cry 😭

🦋 DESCRIPTION

So basically, this is the support for computing the scrypt password-based KDF through the EVP_KDF API. That's it. That's the whole thing. 💅

The EVP_KDF-SCRYPT algorithm implements the scrypt password-based key derivation function, exactly as described in RFC 7914. It's memory-hard — like, on purpose it demands a genuinely large amount of RAM to compute efficiently. Why? Because the whole point is to make brute-forcing passwords on systems that don't have tons of main memory (hi, GPUs 👋 hi, ASICs 👋) computationally infeasible. It's a flex, honestly. 🔥

scrypt gives you three work factors you can customize: N, r and p.

  • N has to be a positive power of two, and it's the general work factor — it scales CPU time in a roughly linear way.
  • r is the block size of the internally used hash function.
  • p is the parallelization factor.

Both r and p need to be greater than zero (no zeroes, babes 🚫). And the amount of RAM scrypt needs for its computation is roughly (128 * N * r * p) bytes. Do the math before you pick numbers, fr fr.

Now for the iconic lore 🎀 — in the original paper by Colin Percival ("Stronger Key Derivation via Sequential Memory-Hard Functions", 2009), the suggested values that give a computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N = 2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5 GHz), this computation takes about 3 seconds. Iconic performance journey, honestly.

When N, r or p are not specified, they default to 1048576, 8, and 1 respectively. And the maximum amount of RAM that may be used by scrypt defaults to 1025 MiB.

⭐ Identity

"SCRYPT" is the name for this implementation — it's what you pass to the EVP_KDF_fetch() function. Name drop it with confidence. 👑

🌈 Supported parameters

The supported parameters are:

  • "pass" (OSSL_KDF_PARAM_PASSWORD) <octet string>
  • "salt" (OSSL_KDF_PARAM_SALT) <octet string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3). Standard bestie behaviour, nothing weird here.

  • "n" (OSSL_KDF_PARAM_SCRYPT_N) <unsigned integer>
  • "r" (OSSL_KDF_PARAM_SCRYPT_R) <unsigned integer>
  • "p" (OSSL_KDF_PARAM_SCRYPT_P) <unsigned integer>
  • "maxmem_bytes" (OSSL_KDF_PARAM_SCRYPT_MAXMEM) <unsigned integer>

These parameters configure the scrypt work factors N, r, maxmem and p. Pay attention, this part matters 💀 — both N and maxmem_bytes are parameters of type uint64_t. Both r and p are parameters of type uint32_t. Don't mix them up.

  • "properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

This can be used to set the property query string when fetching the fixed digest internally. NULL is used if this value is not set.

🧚 NOTES

You get a context for scrypt by calling:

EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);

The output length of an scrypt key derivation is specified via the "keylen" parameter to the EVP_KDF_derive(3) function. That's the length knob, lowkey important.

🍓 EXAMPLES

This example derives a 64-byte long test vector using scrypt with the password "password", salt "NaCl" and N = 1024, r = 8, p = 16. Copy it, run it, love it 💖

 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char out[64];
 OSSL_PARAM params[6], *p = params;

 kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);

 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD,
                                          "password", (size_t)8);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                          "NaCl", (size_t)4);
 *p++ = OSSL_PARAM_construct_uint64(OSSL_KDF_PARAM_SCRYPT_N, (uint64_t)1024);
 *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_R, (uint32_t)8);
 *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_P, (uint32_t)16);
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
     error("EVP_KDF_derive");
 }

 {
     const unsigned char expected[sizeof(out)] = {
         0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00,
         0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe,
         0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30,
         0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62,
         0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88,
         0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda,
         0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d,
         0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40
     };

     assert(!memcmp(out, expected, sizeof(out)));
 }

 EVP_KDF_CTX_free(kctx);

👑 CONFORMING TO

RFC 7914 — read it, cite it, respect it 📜

💀 SEE ALSO

EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_set_params(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3)

Go read them, they're the supporting cast and they ate 🫶

✨ HISTORY

This functionality was added in OpenSSL 3.0. New era, new KDF, periodt.

Copyright 2017-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

ngl bestie, the license is not a suggestion — no cap, read it before you ship 💅

and that's the whole page!! 💖✨🎀🦋🌸 This one's from OpenSSL 3.5.6, dated 2026-04-07, and it lives at EVP_KDF-SCRYPT(7ossl) — go forth and derive those keys, mwah 😚💜

📦 where this page comes from