include/crypto/rng.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002 /*
0003  * RNG: Random Number Generator  algorithms under the crypto API
0004  *
0005  * Copyright (c) 2008 Neil Horman <nhorman@tuxdriver.com>
0006  * Copyright (c) 2015 Herbert Xu <herbert@gondor.apana.org.au>
0007  */
0008
0009 #ifndef _CRYPTO_RNG_H
0010 #define _CRYPTO_RNG_H
0011
0012 #include <linux/crypto.h>
0013
0014 struct crypto_rng;
0015
0016 /**
0017  * struct rng_alg - random number generator definition
0018  *
0019  * @generate:   The function defined by this variable obtains a
0020  *      random number. The random number generator transform
0021  *      must generate the random number out of the context
0022  *      provided with this call, plus any additional data
0023  *      if provided to the call.
0024  * @seed:   Seed or reseed the random number generator.  With the
0025  *      invocation of this function call, the random number
0026  *      generator shall become ready for generation.  If the
0027  *      random number generator requires a seed for setting
0028  *      up a new state, the seed must be provided by the
0029  *      consumer while invoking this function. The required
0030  *      size of the seed is defined with @seedsize .
0031  * @set_ent:    Set entropy that would otherwise be obtained from
0032  *      entropy source.  Internal use only.
0033  * @seedsize:   The seed size required for a random number generator
0034  *      initialization defined with this variable. Some
0035  *      random number generators does not require a seed
0036  *      as the seeding is implemented internally without
0037  *      the need of support by the consumer. In this case,
0038  *      the seed size is set to zero.
0039  * @base:   Common crypto API algorithm data structure.
0040  */
0041 struct rng_alg {
0042     int (*generate)(struct crypto_rng *tfm,
0043             const u8 *src, unsigned int slen,
0044             u8 *dst, unsigned int dlen);
0045     int (*seed)(struct crypto_rng *tfm, const u8 *seed, unsigned int slen);
0046     void (*set_ent)(struct crypto_rng *tfm, const u8 *data,
0047             unsigned int len);
0048
0049     unsigned int seedsize;
0050
0051     struct crypto_alg base;
0052 };
0053
0054 struct crypto_rng {
0055     struct crypto_tfm base;
0056 };
0057
0058 extern struct crypto_rng *crypto_default_rng;
0059
0060 int crypto_get_default_rng(void);
0061 void crypto_put_default_rng(void);
0062
0063 /**
0064  * DOC: Random number generator API
0065  *
0066  * The random number generator API is used with the ciphers of type
0067  * CRYPTO_ALG_TYPE_RNG (listed as type "rng" in /proc/crypto)
0068  */
0069
0070 /**
0071  * crypto_alloc_rng() -- allocate RNG handle
0072  * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
0073  *        message digest cipher
0074  * @type: specifies the type of the cipher
0075  * @mask: specifies the mask for the cipher
0076  *
0077  * Allocate a cipher handle for a random number generator. The returned struct
0078  * crypto_rng is the cipher handle that is required for any subsequent
0079  * API invocation for that random number generator.
0080  *
0081  * For all random number generators, this call creates a new private copy of
0082  * the random number generator that does not share a state with other
0083  * instances. The only exception is the "krng" random number generator which
0084  * is a kernel crypto API use case for the get_random_bytes() function of the
0085  * /dev/random driver.
0086  *
0087  * Return: allocated cipher handle in case of success; IS_ERR() is true in case
0088  *     of an error, PTR_ERR() returns the error code.
0089  */
0090 struct crypto_rng *crypto_alloc_rng(const char *alg_name, u32 type, u32 mask);
0091
0092 static inline struct crypto_tfm *crypto_rng_tfm(struct crypto_rng *tfm)
0093 {
0094     return &tfm->base;
0095 }
0096
0097 /**
0098  * crypto_rng_alg - obtain name of RNG
0099  * @tfm: cipher handle
0100  *
0101  * Return the generic name (cra_name) of the initialized random number generator
0102  *
0103  * Return: generic name string
0104  */
0105 static inline struct rng_alg *crypto_rng_alg(struct crypto_rng *tfm)
0106 {
0107     return container_of(crypto_rng_tfm(tfm)->__crt_alg,
0108                 struct rng_alg, base);
0109 }
0110
0111 /**
0112  * crypto_free_rng() - zeroize and free RNG handle
0113  * @tfm: cipher handle to be freed
0114  *
0115  * If @tfm is a NULL or error pointer, this function does nothing.
0116  */
0117 static inline void crypto_free_rng(struct crypto_rng *tfm)
0118 {
0119     crypto_destroy_tfm(tfm, crypto_rng_tfm(tfm));
0120 }
0121
0122 /**
0123  * crypto_rng_generate() - get random number
0124  * @tfm: cipher handle
0125  * @src: Input buffer holding additional data, may be NULL
0126  * @slen: Length of additional data
0127  * @dst: output buffer holding the random numbers
0128  * @dlen: length of the output buffer
0129  *
0130  * This function fills the caller-allocated buffer with random
0131  * numbers using the random number generator referenced by the
0132  * cipher handle.
0133  *
0134  * Return: 0 function was successful; < 0 if an error occurred
0135  */
0136 static inline int crypto_rng_generate(struct crypto_rng *tfm,
0137                       const u8 *src, unsigned int slen,
0138                       u8 *dst, unsigned int dlen)
0139 {
0140     struct crypto_alg *alg = tfm->base.__crt_alg;
0141     int ret;
0142
0143     crypto_stats_get(alg);
0144     ret = crypto_rng_alg(tfm)->generate(tfm, src, slen, dst, dlen);
0145     crypto_stats_rng_generate(alg, dlen, ret);
0146     return ret;
0147 }
0148
0149 /**
0150  * crypto_rng_get_bytes() - get random number
0151  * @tfm: cipher handle
0152  * @rdata: output buffer holding the random numbers
0153  * @dlen: length of the output buffer
0154  *
0155  * This function fills the caller-allocated buffer with random numbers using the
0156  * random number generator referenced by the cipher handle.
0157  *
0158  * Return: 0 function was successful; < 0 if an error occurred
0159  */
0160 static inline int crypto_rng_get_bytes(struct crypto_rng *tfm,
0161                        u8 *rdata, unsigned int dlen)
0162 {
0163     return crypto_rng_generate(tfm, NULL, 0, rdata, dlen);
0164 }
0165
0166 /**
0167  * crypto_rng_reset() - re-initialize the RNG
0168  * @tfm: cipher handle
0169  * @seed: seed input data
0170  * @slen: length of the seed input data
0171  *
0172  * The reset function completely re-initializes the random number generator
0173  * referenced by the cipher handle by clearing the current state. The new state
0174  * is initialized with the caller provided seed or automatically, depending
0175  * on the random number generator type (the ANSI X9.31 RNG requires
0176  * caller-provided seed, the SP800-90A DRBGs perform an automatic seeding).
0177  * The seed is provided as a parameter to this function call. The provided seed
0178  * should have the length of the seed size defined for the random number
0179  * generator as defined by crypto_rng_seedsize.
0180  *
0181  * Return: 0 if the setting of the key was successful; < 0 if an error occurred
0182  */
0183 int crypto_rng_reset(struct crypto_rng *tfm, const u8 *seed,
0184              unsigned int slen);
0185
0186 /**
0187  * crypto_rng_seedsize() - obtain seed size of RNG
0188  * @tfm: cipher handle
0189  *
0190  * The function returns the seed size for the random number generator
0191  * referenced by the cipher handle. This value may be zero if the random
0192  * number generator does not implement or require a reseeding. For example,
0193  * the SP800-90A DRBGs implement an automated reseeding after reaching a
0194  * pre-defined threshold.
0195  *
0196  * Return: seed size for the random number generator
0197  */
0198 static inline int crypto_rng_seedsize(struct crypto_rng *tfm)
0199 {
0200     return crypto_rng_alg(tfm)->seedsize;
0201 }
0202
0203 #endif