xref: /linux/crypto/drbg.c (revision 09e6b79b8ce388993aec9ac91b1cb2c181c27bd9)

/*
 * DRBG: Deterministic Random Bits Generator
 *       Implementation of the HMAC SHA-512 DRBG from NIST SP800-90A
 *
 * Copyright Stephan Mueller <smueller@chronox.de>, 2014
 * Copyright 2026 Google LLC
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, and the entire permission notice in its entirety,
 *    including the disclaimer of warranties.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote
 *    products derived from this software without specific prior
 *    written permission.
 *
 * ALTERNATIVELY, this product may be distributed under the terms of
 * the GNU General Public License, in which case the provisions of the GPL are
 * required INSTEAD OF the above restrictions.  (This clause is
 * necessary due to a potential bad interaction between the GPL and
 * the restrictions contained in a BSD-style copyright.)
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ALL OF
 * WHICH ARE HEREBY DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 * USE OF THIS SOFTWARE, EVEN IF NOT ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 *
 * DRBG Usage
 * ==========
 * The SP 800-90A DRBG allows the user to specify a personalization string
 * for initialization as well as an additional information string for each
 * random number request. The following code fragments show how a caller
 * uses the kernel crypto API to use the full functionality of the DRBG.
 *
 * Usage without any additional data
 * ---------------------------------
 * struct crypto_rng *drng;
 * int err;
 * char data[DATALEN];
 *
 * drng = crypto_alloc_rng(drng_name, 0, 0);
 * err = crypto_rng_get_bytes(drng, data, DATALEN);
 * crypto_free_rng(drng);
 *
 *
 * Usage with personalization string during initialization
 * -------------------------------------------------------
 * struct crypto_rng *drng;
 * int err;
 * char data[DATALEN];
 * char personalization[11] = "some-string";
 *
 * drng = crypto_alloc_rng(drng_name, 0, 0);
 * // The reset completely re-initializes the DRBG with the provided
 * // personalization string
 * err = crypto_rng_reset(drng, personalization, strlen(personalization));
 * err = crypto_rng_get_bytes(drng, data, DATALEN);
 * crypto_free_rng(drng);
 *
 *
 * Usage with additional information string during random number request
 * ---------------------------------------------------------------------
 * struct crypto_rng *drng;
 * int err;
 * char data[DATALEN];
 * char addtl_string[11] = "some-string";
 *
 * drng = crypto_alloc_rng(drng_name, 0, 0);
 * err = crypto_rng_generate(drng, addtl_string, strlen(addtl_string),
			     data, DATALEN);
 * crypto_free_rng(drng);
 *
 *
 * Usage with personalization and additional information strings
 * -------------------------------------------------------------
 * Just mix both scenarios above.
 */

#include <crypto/internal/rng.h>
#include <crypto/sha2.h>
#include <linux/fips.h>
#include <linux/kernel.h>
#include <linux/module.h>
#include <linux/mutex.h>
#include <linux/string_choices.h>
#include <linux/unaligned.h>

/* State length in bytes */
#define DRBG_STATE_LEN		SHA512_DIGEST_SIZE

/* Security strength in bytes */
#define DRBG_SEC_STRENGTH	(SHA512_DIGEST_SIZE / 2)

/*
 * Maximum number of requests before reseeding is forced.
 * SP800-90A allows this to be up to 2**48.  We use a lower value.
 */
#define DRBG_MAX_REQUESTS	4096

/*
 * Maximum number of random bytes that can be requested at once.
 * SP800-90A allows up to 2**19 bits, which is 2**16 bytes.
 */
#define DRBG_MAX_REQUEST_BYTES	(1 << 16)

/*
 * Maximum length of additional info and personalization strings, in bytes.
 * SP800-90A allows up to 2**35 bits, i.e. 2**32 bytes.  We use 2**32 - 2 bytes
 * so that the value never quite completely fills the range of a size_t,
 * allowing the health check to verify that larger values are rejected.
 */
#define DRBG_MAX_ADDTL_BYTES	(U32_MAX - 1)

struct drbg_state {
	struct mutex drbg_mutex;	/* lock around DRBG */
	u8 V[DRBG_STATE_LEN];		/* internal state -- 10.1.2.1 1a */
	struct hmac_sha512_key key;	/* current key -- 10.1.2.1 1b */
	/* Number of RNG requests since last reseed -- 10.1.2.1 1c */
	size_t reseed_ctr;
	bool instantiated;
	struct crypto_rng *jent;
	const u8 *test_entropy;
	size_t test_entropylen;
};

/******************************************************************
 * HMAC DRBG functions
 ******************************************************************/

/* update function of HMAC DRBG as defined in 10.1.2.2 */
static void drbg_hmac_update(struct drbg_state *drbg,
			     const u8 *data1, size_t data1_len,
			     const u8 *data2, size_t data2_len)
{
	struct hmac_sha512_ctx hmac_ctx;
	u8 new_key[DRBG_STATE_LEN];

	for (u8 i = 0; i < 2; i++) {
		/* 10.1.2.2 step 1 and 4 -- concatenation and HMAC for key */
		hmac_sha512_init(&hmac_ctx, &drbg->key);
		hmac_sha512_update(&hmac_ctx, drbg->V, DRBG_STATE_LEN);
		hmac_sha512_update(&hmac_ctx, &i, 1);
		hmac_sha512_update(&hmac_ctx, data1, data1_len);
		hmac_sha512_update(&hmac_ctx, data2, data2_len);
		hmac_sha512_final(&hmac_ctx, new_key);
		hmac_sha512_preparekey(&drbg->key, new_key, DRBG_STATE_LEN);

		/* 10.1.2.2 step 2 and 5 -- HMAC for V */
		hmac_sha512(&drbg->key, drbg->V, DRBG_STATE_LEN, drbg->V);

		/* 10.1.2.2 step 3 */
		if (data1_len == 0 && data2_len == 0)
			break;
	}
	memzero_explicit(new_key, sizeof(new_key));
}

/* generate function of HMAC DRBG as defined in 10.1.2.5 */
static void drbg_hmac_generate(struct drbg_state *drbg, u8 *out, size_t outlen,
			       const u8 *addtl1, size_t addtl1_len)
{
	u8 addtl2[32];
	size_t addtl2_len = 0;

	/*
	 * Append some bytes from get_random_bytes() to the additional input
	 * string, except when in test mode (as it would break the tests).
	 * Using a nonempty additional input string works around the forward
	 * secrecy bug in HMAC_DRBG described by Woodage & Shumow (2018)
	 * (https://eprint.iacr.org/2018/349.pdf).  Filling the string with
	 * get_random_bytes() rather than a fixed value is safer still, and in
	 * particular makes random.c reseeds be immediately reflected.
	 *
	 * Note that there's no need to pull bytes from jitterentropy here too,
	 * since FIPS doesn't require any entropy in the additional input.
	 */
	if (drbg->test_entropylen == 0) {
		get_random_bytes(addtl2, sizeof(addtl2));
		addtl2_len = sizeof(addtl2);
	}

	/* 10.1.2.5 step 2 */
	if (addtl1_len || addtl2_len)
		drbg_hmac_update(drbg, addtl1, addtl1_len, addtl2, addtl2_len);

	while (outlen) {
		size_t n = min(DRBG_STATE_LEN, outlen);

		/* 10.1.2.5 step 4.1 */
		hmac_sha512(&drbg->key, drbg->V, DRBG_STATE_LEN, drbg->V);

		/* 10.1.2.5 step 4.2 */
		memcpy(out, drbg->V, n);
		out += n;
		outlen -= n;
	}

	/* 10.1.2.5 step 6 */
	drbg_hmac_update(drbg, addtl1, addtl1_len, addtl2, addtl2_len);

	memzero_explicit(addtl2, sizeof(addtl2));
}

/*
 * Seeding or reseeding of the DRBG
 *
 * @drbg: DRBG state struct
 * @pers: personalization / additional information buffer
 * @pers_len: length of @pers in bytes
 * @reseed: false for initial seeding (instantiation), true for reseeding
 *
 * return:
 *	0 on success
 *	error value otherwise
 */
static int drbg_seed(struct drbg_state *drbg, const u8 *pers, size_t pers_len,
		     bool reseed)
	__must_hold(&drbg->drbg_mutex)
{
	int ret;
	u8 entropy_buf[(32 + 16) * 2];
	size_t entropylen;
	const u8 *entropy;

	/* 9.1 / 9.2 / 9.3.1 step 3 */
	if (pers_len > DRBG_MAX_ADDTL_BYTES) {
		pr_devel("DRBG: personalization string too long %zu\n",
			 pers_len);
		return -EINVAL;
	}

	if (drbg->test_entropylen) {
		entropy = drbg->test_entropy;
		entropylen = drbg->test_entropylen;
		pr_devel("DRBG: using test entropy\n");
	} else {
		/*
		 * Gather entropy equal to the security strength of the DRBG.
		 * With a derivation function, a nonce is required in addition
		 * to the entropy. A nonce must be at least 1/2 of the security
		 * strength of the DRBG in size. Thus, entropy + nonce is 3/2
		 * of the strength. The consideration of a nonce is only
		 * applicable during initial seeding.
		 */
		entropy = entropy_buf;
		if (!reseed)
			entropylen = ((DRBG_SEC_STRENGTH + 1) / 2) * 3;
		else
			entropylen = DRBG_SEC_STRENGTH;
		BUG_ON(entropylen * 2 > sizeof(entropy_buf));

		/* Get seed from in-kernel /dev/urandom */
		get_random_bytes(entropy_buf, entropylen);

		if (!drbg->jent) {
			pr_devel("DRBG: (re)seeding with %zu bytes of entropy\n",
				 entropylen);
		} else {
			/*
			 * Get seed from Jitter RNG, failures are
			 * fatal only in FIPS mode.
			 */
			ret = crypto_rng_get_bytes(drbg->jent,
						   &entropy_buf[entropylen],
						   entropylen);
			if (fips_enabled && ret) {
				pr_devel("DRBG: jent failed with %d\n", ret);

				/*
				 * Do not treat the transient failure of the
				 * Jitter RNG as an error that needs to be
				 * reported. The combined number of the
				 * maximum reseed threshold times the maximum
				 * number of Jitter RNG transient errors is
				 * less than the reseed threshold required by
				 * SP800-90A allowing us to treat the
				 * transient errors as such.
				 *
				 * However, we mandate that at least the first
				 * seeding operation must succeed with the
				 * Jitter RNG.
				 */
				if (!reseed || ret != -EAGAIN)
					goto out;
			}

			entropylen *= 2;
			pr_devel("DRBG: (re)seeding with %zu bytes of entropy\n",
				 entropylen);
		}
	}

	if (pers_len)
		pr_devel("DRBG: using personalization string\n");

	drbg_hmac_update(drbg, entropy, entropylen, pers, pers_len);
	drbg->reseed_ctr = 1;
	ret = 0;
out:
	memzero_explicit(entropy_buf, sizeof(entropy_buf));

	return ret;
}

/*
 * Generate random bytes from an SP800-90A DRBG.
 *
 * @drbg DRBG state handle
 * @out Buffer where to store the random bytes
 * @outlen Number of random bytes to generate
 * @addtl Optional additional input that is mixed into state
 * @addtl_len Length of @addtl in bytes, may be 0
 *
 * return: 0 when all bytes are generated; < 0 in case of an error
 */
static int drbg_generate(struct drbg_state *drbg, u8 *out, size_t outlen,
			 const u8 *addtl, size_t addtl_len)
	__must_hold(&drbg->drbg_mutex)
{
	int err;

	if (!drbg->instantiated) {
		pr_devel("DRBG: not yet instantiated\n");
		return -EINVAL;
	}
	if (out == NULL || outlen == 0) {
		pr_devel("DRBG: no output buffer provided\n");
		return -EINVAL;
	}
	if (addtl == NULL && addtl_len != 0) {
		pr_devel("DRBG: wrong format of additional information\n");
		return -EINVAL;
	}

	/* 9.3.1 step 2 */
	if (outlen > DRBG_MAX_REQUEST_BYTES) {
		pr_devel("DRBG: request length is too long %zu\n", outlen);
		return -EINVAL;
	}

	/* 9.3.1 step 3 is implicit with the chosen DRBG */

	/* 9.3.1 step 4 */
	if (addtl_len > DRBG_MAX_ADDTL_BYTES) {
		pr_devel("DRBG: additional information string too long %zu\n",
			 addtl_len);
		return -EINVAL;
	}
	/* 9.3.1 step 5 is implicit with the chosen DRBG */

	/*
	 * 9.3.1 step 6 and 9 supplemented by 9.3.2 step c is implemented
	 * here. The spec is a bit convoluted here, we make it simpler.
	 *
	 * We no longer try to detect when random.c has reseeded itself and call
	 * drbg_seed() then too, since drbg_hmac_generate() adds bytes from
	 * random.c to the additional input, which is a de facto reseed anyway.
	 */
	if (drbg->reseed_ctr > DRBG_MAX_REQUESTS) {
		pr_devel("DRBG: reseeding before generation\n");
		/* 9.3.1 steps 7.1 through 7.3 */
		err = drbg_seed(drbg, addtl, addtl_len, true);
		if (err)
			return err;
		/* 9.3.1 step 7.4 */
		addtl = NULL;
		addtl_len = 0;
	}

	/* 9.3.1 step 8 and 10 */
	drbg_hmac_generate(drbg, out, outlen, addtl, addtl_len);

	/* 10.1.2.5 step 7 */
	drbg->reseed_ctr++;

	/*
	 * Section 11.3.3 requires to re-perform self tests after some
	 * generated random numbers. The chosen value after which self
	 * test is performed is arbitrary, but it should be reasonable.
	 * However, we do not perform the self tests because of the following
	 * reasons: it is mathematically impossible that the initial self tests
	 * were successfully and the following are not. If the initial would
	 * pass and the following would not, the kernel integrity is violated.
	 * In this case, the entire kernel operation is questionable and it
	 * is unlikely that the integrity violation only affects the
	 * correct operation of the DRBG.
	 */

	return 0;
}

/***************************************************************
 * Kernel crypto API interface to DRBG
 ***************************************************************/

static int drbg_kcapi_init(struct crypto_tfm *tfm)
{
	struct drbg_state *drbg = crypto_tfm_ctx(tfm);

	mutex_init(&drbg->drbg_mutex);

	return 0;
}

/* Set test entropy in the DRBG. */
static void drbg_kcapi_set_entropy(struct crypto_rng *tfm,
				   const u8 *data, unsigned int len)
{
	struct drbg_state *drbg = crypto_rng_ctx(tfm);

	mutex_lock(&drbg->drbg_mutex);
	drbg->test_entropy = data;
	drbg->test_entropylen = len;
	mutex_unlock(&drbg->drbg_mutex);
}

/* Seed (i.e. instantiate) or re-seed the DRBG. */
static int drbg_kcapi_seed(struct crypto_rng *tfm,
			   const u8 *pers, unsigned int pers_len)
{
	static const u8 initial_key[DRBG_STATE_LEN]; /* all zeroes */
	struct drbg_state *drbg = crypto_rng_ctx(tfm);
	int ret;

	pr_devel("DRBG: Initializing DRBG\n");
	guard(mutex)(&drbg->drbg_mutex);

	if (drbg->instantiated)
		return drbg_seed(drbg, pers, pers_len, /* reseed= */ true);

	/* 9.1 step 1 is implicit with the selected DRBG type */

	/*
	 * 9.1 step 2 is implicit, as this implementation doesn't support
	 * prediction resistance
	 */

	/* 9.1 step 4 is implicit in DRBG_SEC_STRENGTH */

	memset(drbg->V, 1, DRBG_STATE_LEN);
	hmac_sha512_preparekey(&drbg->key, initial_key, DRBG_STATE_LEN);

	/* Allocate jitterentropy_rng if not in test mode. */
	if (drbg->test_entropylen == 0) {
		drbg->jent = crypto_alloc_rng("jitterentropy_rng", 0, 0);
		if (IS_ERR(drbg->jent)) {
			ret = PTR_ERR(drbg->jent);
			drbg->jent = NULL;
			if (fips_enabled)
				return ret;
			pr_info("DRBG: Continuing without Jitter RNG\n");
		}
	}

	ret = drbg_seed(drbg, pers, pers_len, /* reseed= */ false);
	if (ret) {
		crypto_free_rng(drbg->jent);
		drbg->jent = NULL;
		return ret;
	}
	drbg->instantiated = true;
	return 0;
}

/*
 * Generate random numbers invoked by the kernel crypto API:
 *
 * src is additional input supplied to the RNG.
 * slen is the length of src.
 * dst is the output buffer where random data is to be stored.
 * dlen is the length of dst.
 */
static int drbg_kcapi_generate(struct crypto_rng *tfm,
			       const u8 *src, unsigned int slen,
			       u8 *dst, unsigned int dlen)
{
	struct drbg_state *drbg = crypto_rng_ctx(tfm);

	/*
	 * Break the request into multiple requests if needed, to avoid
	 * exceeding the maximum request length of the core algorithm.
	 */
	do {
		unsigned int n = min(dlen, DRBG_MAX_REQUEST_BYTES);
		int err;

		mutex_lock(&drbg->drbg_mutex);
		err = drbg_generate(drbg, dst, n, src, slen);
		mutex_unlock(&drbg->drbg_mutex);
		if (err < 0)
			return err;
		dst += n;
		dlen -= n;
	} while (dlen);
	return 0;
}

/* Uninstantiate the DRBG. */
static void drbg_kcapi_exit(struct crypto_tfm *tfm)
{
	struct drbg_state *drbg = crypto_tfm_ctx(tfm);

	crypto_free_rng(drbg->jent);
	memzero_explicit(drbg, sizeof(*drbg));
}

/*
 * Tests as defined in 11.3.2 in addition to the cipher tests: testing
 * of the error handling.
 *
 * Note: testing of failing seed source as defined in 11.3.2 is not applicable
 * as seed source of get_random_bytes does not fail.
 *
 * Note 2: There is no sensible way of testing the reseed counter
 * enforcement, so skip it.
 */
static inline int __init drbg_healthcheck_sanity(void)
{
#define OUTBUFLEN 16
	u8 buf[OUTBUFLEN];
	struct drbg_state *drbg = NULL;
	int ret;

	/* only perform test in FIPS mode */
	if (!fips_enabled)
		return 0;

	drbg = kzalloc_obj(struct drbg_state);
	if (!drbg)
		return -ENOMEM;

	guard(mutex_init)(&drbg->drbg_mutex);
	drbg->instantiated = true;

	/*
	 * if the following tests fail, it is likely that there is a buffer
	 * overflow as buf is much smaller than the requested or provided
	 * string lengths -- in case the error handling does not succeed
	 * we may get an OOPS. And we want to get an OOPS as this is a
	 * grave bug.
	 */

	/* overflow addtllen with additional info string */
	ret = drbg_generate(drbg, buf, OUTBUFLEN, buf,
			    DRBG_MAX_ADDTL_BYTES + 1);
	BUG_ON(ret == 0);
	/* overflow max_bits */
	ret = drbg_generate(drbg, buf, DRBG_MAX_REQUEST_BYTES + 1, NULL, 0);
	BUG_ON(ret == 0);

	/* overflow max addtllen with personalization string */
	ret = drbg_seed(drbg, buf, DRBG_MAX_ADDTL_BYTES + 1, false);
	BUG_ON(ret == 0);
	/* all tests passed */

	pr_devel("DRBG: Sanity tests for failure code paths successfully "
		 "completed\n");

	kfree(drbg);
	return 0;
}

static struct rng_alg drbg_alg = {
	.base.cra_name		= "stdrng",
	.base.cra_driver_name	= "drbg_nopr_hmac_sha512",
	.base.cra_priority	= 201,
	.base.cra_ctxsize	= sizeof(struct drbg_state),
	.base.cra_module	= THIS_MODULE,
	.base.cra_init		= drbg_kcapi_init,
	.set_ent		= drbg_kcapi_set_entropy,
	.seed			= drbg_kcapi_seed,
	.generate		= drbg_kcapi_generate,
	.base.cra_exit		= drbg_kcapi_exit,
};

static int __init drbg_init(void)
{
	int ret;

	ret = drbg_healthcheck_sanity();
	if (ret)
		return ret;

	/*
	 * In FIPS mode, boost the algorithm priority to ensure that when users
	 * request "stdrng", they really get the algorithm from here.
	 */
	if (fips_enabled)
		drbg_alg.base.cra_priority += 2000;

	return crypto_register_rng(&drbg_alg);
}

static void __exit drbg_exit(void)
{
	crypto_unregister_rng(&drbg_alg);
}

module_init(drbg_init);
module_exit(drbg_exit);
MODULE_LICENSE("GPL");
MODULE_AUTHOR("Stephan Mueller <smueller@chronox.de>");
MODULE_DESCRIPTION("NIST SP800-90A Deterministic Random Bit Generator (DRBG)");
MODULE_ALIAS_CRYPTO("stdrng");
MODULE_ALIAS_CRYPTO("drbg_nopr_hmac_sha512");