include/crypto/rng.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2 /*
   3  * RNG: Random Number Generator  algorithms under the crypto API
   4  *
   5  * Copyright (c) 2008 Neil Horman <nhorman@tuxdriver.com>
   6  * Copyright (c) 2015 Herbert Xu <herbert@gondor.apana.org.au>
   7  */
   8
   9 #ifndef _CRYPTO_RNG_H
  10 #define _CRYPTO_RNG_H
  11
  12 #include <linux/atomic.h>
  13 #include <linux/container_of.h>
  14 #include <linux/crypto.h>
  15
  16 struct crypto_rng;
  17
  18 /**
  19  * struct rng_alg - random number generator definition
  20  *
  21  * @generate:   The function defined by this variable obtains a
  22  *              random number. The random number generator transform
  23  *              must generate the random number out of the context
  24  *              provided with this call, plus any additional data
  25  *              if provided to the call.
  26  * @seed:       Seed or reseed the random number generator.  With the
  27  *              invocation of this function call, the random number
  28  *              generator shall become ready for generation.  If the
  29  *              random number generator requires a seed for setting
  30  *              up a new state, the seed must be provided by the
  31  *              consumer while invoking this function. The required
  32  *              size of the seed is defined with @seedsize .
  33  * @set_ent:    Set entropy that would otherwise be obtained from
  34  *              entropy source.  Internal use only.
  35  * @seedsize:   The seed size required for a random number generator
  36  *              initialization defined with this variable. Some
  37  *              random number generators does not require a seed
  38  *              as the seeding is implemented internally without
  39  *              the need of support by the consumer. In this case,
  40  *              the seed size is set to zero.
  41  * @base:       Common crypto API algorithm data structure.
  42  */
  43 struct rng_alg {
  44         int (*generate)(struct crypto_rng *tfm,
  45                         const u8 *src, unsigned int slen,
  46                         u8 *dst, unsigned int dlen);
  47         int (*seed)(struct crypto_rng *tfm, const u8 *seed, unsigned int slen);
  48         void (*set_ent)(struct crypto_rng *tfm, const u8 *data,
  49                         unsigned int len);
  50
  51         unsigned int seedsize;
  52
  53         struct crypto_alg base;
  54 };
  55
  56 struct crypto_rng {
  57         struct crypto_tfm base;
  58 };
  59
  60 extern struct crypto_rng *crypto_default_rng;
  61
  62 int crypto_get_default_rng(void);
  63 void crypto_put_default_rng(void);
  64
  65 /**
  66  * DOC: Random number generator API
  67  *
  68  * The random number generator API is used with the ciphers of type
  69  * CRYPTO_ALG_TYPE_RNG (listed as type "rng" in /proc/crypto)
  70  */
  71
  72 /**
  73  * crypto_alloc_rng() -- allocate RNG handle
  74  * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
  75  *            message digest cipher
  76  * @type: specifies the type of the cipher
  77  * @mask: specifies the mask for the cipher
  78  *
  79  * Allocate a cipher handle for a random number generator. The returned struct
  80  * crypto_rng is the cipher handle that is required for any subsequent
  81  * API invocation for that random number generator.
  82  *
  83  * For all random number generators, this call creates a new private copy of
  84  * the random number generator that does not share a state with other
  85  * instances. The only exception is the "krng" random number generator which
  86  * is a kernel crypto API use case for the get_random_bytes() function of the
  87  * /dev/random driver.
  88  *
  89  * Return: allocated cipher handle in case of success; IS_ERR() is true in case
  90  *         of an error, PTR_ERR() returns the error code.
  91  */
  92 struct crypto_rng *crypto_alloc_rng(const char *alg_name, u32 type, u32 mask);
  93
  94 static inline struct crypto_tfm *crypto_rng_tfm(struct crypto_rng *tfm)
  95 {
  96         return &tfm->base;
  97 }
  98
  99 static inline struct rng_alg *__crypto_rng_alg(struct crypto_alg *alg)
 100 {
 101         return container_of(alg, struct rng_alg, base);
 102 }
 103
 104 /**
 105  * crypto_rng_alg - obtain name of RNG
 106  * @tfm: cipher handle
 107  *
 108  * Return the generic name (cra_name) of the initialized random number generator
 109  *
 110  * Return: generic name string
 111  */
 112 static inline struct rng_alg *crypto_rng_alg(struct crypto_rng *tfm)
 113 {
 114         return __crypto_rng_alg(crypto_rng_tfm(tfm)->__crt_alg);
 115 }
 116
 117 /**
 118  * crypto_free_rng() - zeroize and free RNG handle
 119  * @tfm: cipher handle to be freed
 120  *
 121  * If @tfm is a NULL or error pointer, this function does nothing.
 122  */
 123 static inline void crypto_free_rng(struct crypto_rng *tfm)
 124 {
 125         crypto_destroy_tfm(tfm, crypto_rng_tfm(tfm));
 126 }
 127
 128 /**
 129  * crypto_rng_generate() - get random number
 130  * @tfm: cipher handle
 131  * @src: Input buffer holding additional data, may be NULL
 132  * @slen: Length of additional data
 133  * @dst: output buffer holding the random numbers
 134  * @dlen: length of the output buffer
 135  *
 136  * This function fills the caller-allocated buffer with random
 137  * numbers using the random number generator referenced by the
 138  * cipher handle.
 139  *
 140  * Return: 0 function was successful; < 0 if an error occurred
 141  */
 142 static inline int crypto_rng_generate(struct crypto_rng *tfm,
 143                                       const u8 *src, unsigned int slen,
 144                                       u8 *dst, unsigned int dlen)
 145 {
 146         return crypto_rng_alg(tfm)->generate(tfm, src, slen, dst, dlen);
 147 }
 148
 149 /**
 150  * crypto_rng_get_bytes() - get random number
 151  * @tfm: cipher handle
 152  * @rdata: output buffer holding the random numbers
 153  * @dlen: length of the output buffer
 154  *
 155  * This function fills the caller-allocated buffer with random numbers using the
 156  * random number generator referenced by the cipher handle.
 157  *
 158  * Return: 0 function was successful; < 0 if an error occurred
 159  */
 160 static inline int crypto_rng_get_bytes(struct crypto_rng *tfm,
 161                                        u8 *rdata, unsigned int dlen)
 162 {
 163         return crypto_rng_generate(tfm, NULL, 0, rdata, dlen);
 164 }
 165
 166 /**
 167  * crypto_rng_reset() - re-initialize the RNG
 168  * @tfm: cipher handle
 169  * @seed: seed input data
 170  * @slen: length of the seed input data
 171  *
 172  * The reset function completely re-initializes the random number generator
 173  * referenced by the cipher handle by clearing the current state. The new state
 174  * is initialized with the caller provided seed or automatically, depending
 175  * on the random number generator type (the ANSI X9.31 RNG requires
 176  * caller-provided seed, the SP800-90A DRBGs perform an automatic seeding).
 177  * The seed is provided as a parameter to this function call. The provided seed
 178  * should have the length of the seed size defined for the random number
 179  * generator as defined by crypto_rng_seedsize.
 180  *
 181  * Return: 0 if the setting of the key was successful; < 0 if an error occurred
 182  */
 183 int crypto_rng_reset(struct crypto_rng *tfm, const u8 *seed,
 184                      unsigned int slen);
 185
 186 /**
 187  * crypto_rng_seedsize() - obtain seed size of RNG
 188  * @tfm: cipher handle
 189  *
 190  * The function returns the seed size for the random number generator
 191  * referenced by the cipher handle. This value may be zero if the random
 192  * number generator does not implement or require a reseeding. For example,
 193  * the SP800-90A DRBGs implement an automated reseeding after reaching a
 194  * pre-defined threshold.
 195  *
 196  * Return: seed size for the random number generator
 197  */
 198 static inline int crypto_rng_seedsize(struct crypto_rng *tfm)
 199 {
 200         return crypto_rng_alg(tfm)->seedsize;
 201 }
 202
 203 #endif