GNU Linux-libre 6.6.34-gnu
[releases.git] / 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 crypto_istat_rng: statistics for RNG algorithm
20  * @generate_cnt:       number of RNG generate requests
21  * @generate_tlen:      total data size of generated data by the RNG
22  * @seed_cnt:           number of times the RNG was seeded
23  * @err_cnt:            number of error for RNG requests
24  */
25 struct crypto_istat_rng {
26         atomic64_t generate_cnt;
27         atomic64_t generate_tlen;
28         atomic64_t seed_cnt;
29         atomic64_t err_cnt;
30 };
31
32 /**
33  * struct rng_alg - random number generator definition
34  *
35  * @generate:   The function defined by this variable obtains a
36  *              random number. The random number generator transform
37  *              must generate the random number out of the context
38  *              provided with this call, plus any additional data
39  *              if provided to the call.
40  * @seed:       Seed or reseed the random number generator.  With the
41  *              invocation of this function call, the random number
42  *              generator shall become ready for generation.  If the
43  *              random number generator requires a seed for setting
44  *              up a new state, the seed must be provided by the
45  *              consumer while invoking this function. The required
46  *              size of the seed is defined with @seedsize .
47  * @set_ent:    Set entropy that would otherwise be obtained from
48  *              entropy source.  Internal use only.
49  * @stat:       Statistics for rng algorithm
50  * @seedsize:   The seed size required for a random number generator
51  *              initialization defined with this variable. Some
52  *              random number generators does not require a seed
53  *              as the seeding is implemented internally without
54  *              the need of support by the consumer. In this case,
55  *              the seed size is set to zero.
56  * @base:       Common crypto API algorithm data structure.
57  */
58 struct rng_alg {
59         int (*generate)(struct crypto_rng *tfm,
60                         const u8 *src, unsigned int slen,
61                         u8 *dst, unsigned int dlen);
62         int (*seed)(struct crypto_rng *tfm, const u8 *seed, unsigned int slen);
63         void (*set_ent)(struct crypto_rng *tfm, const u8 *data,
64                         unsigned int len);
65
66 #ifdef CONFIG_CRYPTO_STATS
67         struct crypto_istat_rng stat;
68 #endif
69
70         unsigned int seedsize;
71
72         struct crypto_alg base;
73 };
74
75 struct crypto_rng {
76         struct crypto_tfm base;
77 };
78
79 extern struct crypto_rng *crypto_default_rng;
80
81 int crypto_get_default_rng(void);
82 void crypto_put_default_rng(void);
83
84 /**
85  * DOC: Random number generator API
86  *
87  * The random number generator API is used with the ciphers of type
88  * CRYPTO_ALG_TYPE_RNG (listed as type "rng" in /proc/crypto)
89  */
90
91 /**
92  * crypto_alloc_rng() -- allocate RNG handle
93  * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
94  *            message digest cipher
95  * @type: specifies the type of the cipher
96  * @mask: specifies the mask for the cipher
97  *
98  * Allocate a cipher handle for a random number generator. The returned struct
99  * crypto_rng is the cipher handle that is required for any subsequent
100  * API invocation for that random number generator.
101  *
102  * For all random number generators, this call creates a new private copy of
103  * the random number generator that does not share a state with other
104  * instances. The only exception is the "krng" random number generator which
105  * is a kernel crypto API use case for the get_random_bytes() function of the
106  * /dev/random driver.
107  *
108  * Return: allocated cipher handle in case of success; IS_ERR() is true in case
109  *         of an error, PTR_ERR() returns the error code.
110  */
111 struct crypto_rng *crypto_alloc_rng(const char *alg_name, u32 type, u32 mask);
112
113 static inline struct crypto_tfm *crypto_rng_tfm(struct crypto_rng *tfm)
114 {
115         return &tfm->base;
116 }
117
118 static inline struct rng_alg *__crypto_rng_alg(struct crypto_alg *alg)
119 {
120         return container_of(alg, struct rng_alg, base);
121 }
122
123 /**
124  * crypto_rng_alg - obtain name of RNG
125  * @tfm: cipher handle
126  *
127  * Return the generic name (cra_name) of the initialized random number generator
128  *
129  * Return: generic name string
130  */
131 static inline struct rng_alg *crypto_rng_alg(struct crypto_rng *tfm)
132 {
133         return __crypto_rng_alg(crypto_rng_tfm(tfm)->__crt_alg);
134 }
135
136 /**
137  * crypto_free_rng() - zeroize and free RNG handle
138  * @tfm: cipher handle to be freed
139  *
140  * If @tfm is a NULL or error pointer, this function does nothing.
141  */
142 static inline void crypto_free_rng(struct crypto_rng *tfm)
143 {
144         crypto_destroy_tfm(tfm, crypto_rng_tfm(tfm));
145 }
146
147 static inline struct crypto_istat_rng *rng_get_stat(struct rng_alg *alg)
148 {
149 #ifdef CONFIG_CRYPTO_STATS
150         return &alg->stat;
151 #else
152         return NULL;
153 #endif
154 }
155
156 static inline int crypto_rng_errstat(struct rng_alg *alg, int err)
157 {
158         if (!IS_ENABLED(CONFIG_CRYPTO_STATS))
159                 return err;
160
161         if (err && err != -EINPROGRESS && err != -EBUSY)
162                 atomic64_inc(&rng_get_stat(alg)->err_cnt);
163
164         return err;
165 }
166
167 /**
168  * crypto_rng_generate() - get random number
169  * @tfm: cipher handle
170  * @src: Input buffer holding additional data, may be NULL
171  * @slen: Length of additional data
172  * @dst: output buffer holding the random numbers
173  * @dlen: length of the output buffer
174  *
175  * This function fills the caller-allocated buffer with random
176  * numbers using the random number generator referenced by the
177  * cipher handle.
178  *
179  * Return: 0 function was successful; < 0 if an error occurred
180  */
181 static inline int crypto_rng_generate(struct crypto_rng *tfm,
182                                       const u8 *src, unsigned int slen,
183                                       u8 *dst, unsigned int dlen)
184 {
185         struct rng_alg *alg = crypto_rng_alg(tfm);
186
187         if (IS_ENABLED(CONFIG_CRYPTO_STATS)) {
188                 struct crypto_istat_rng *istat = rng_get_stat(alg);
189
190                 atomic64_inc(&istat->generate_cnt);
191                 atomic64_add(dlen, &istat->generate_tlen);
192         }
193
194         return crypto_rng_errstat(alg,
195                                   alg->generate(tfm, src, slen, dst, dlen));
196 }
197
198 /**
199  * crypto_rng_get_bytes() - get random number
200  * @tfm: cipher handle
201  * @rdata: output buffer holding the random numbers
202  * @dlen: length of the output buffer
203  *
204  * This function fills the caller-allocated buffer with random numbers using the
205  * random number generator referenced by the cipher handle.
206  *
207  * Return: 0 function was successful; < 0 if an error occurred
208  */
209 static inline int crypto_rng_get_bytes(struct crypto_rng *tfm,
210                                        u8 *rdata, unsigned int dlen)
211 {
212         return crypto_rng_generate(tfm, NULL, 0, rdata, dlen);
213 }
214
215 /**
216  * crypto_rng_reset() - re-initialize the RNG
217  * @tfm: cipher handle
218  * @seed: seed input data
219  * @slen: length of the seed input data
220  *
221  * The reset function completely re-initializes the random number generator
222  * referenced by the cipher handle by clearing the current state. The new state
223  * is initialized with the caller provided seed or automatically, depending
224  * on the random number generator type (the ANSI X9.31 RNG requires
225  * caller-provided seed, the SP800-90A DRBGs perform an automatic seeding).
226  * The seed is provided as a parameter to this function call. The provided seed
227  * should have the length of the seed size defined for the random number
228  * generator as defined by crypto_rng_seedsize.
229  *
230  * Return: 0 if the setting of the key was successful; < 0 if an error occurred
231  */
232 int crypto_rng_reset(struct crypto_rng *tfm, const u8 *seed,
233                      unsigned int slen);
234
235 /**
236  * crypto_rng_seedsize() - obtain seed size of RNG
237  * @tfm: cipher handle
238  *
239  * The function returns the seed size for the random number generator
240  * referenced by the cipher handle. This value may be zero if the random
241  * number generator does not implement or require a reseeding. For example,
242  * the SP800-90A DRBGs implement an automated reseeding after reaching a
243  * pre-defined threshold.
244  *
245  * Return: seed size for the random number generator
246  */
247 static inline int crypto_rng_seedsize(struct crypto_rng *tfm)
248 {
249         return crypto_rng_alg(tfm)->seedsize;
250 }
251
252 #endif