xref: /openbmc/linux/include/crypto/rng.h (revision 9807e49b)
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 
crypto_rng_tfm(struct crypto_rng * tfm)113 static inline struct crypto_tfm *crypto_rng_tfm(struct crypto_rng *tfm)
114 {
115 	return &tfm->base;
116 }
117 
__crypto_rng_alg(struct crypto_alg * alg)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  */
crypto_rng_alg(struct crypto_rng * tfm)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  */
crypto_free_rng(struct crypto_rng * tfm)142 static inline void crypto_free_rng(struct crypto_rng *tfm)
143 {
144 	crypto_destroy_tfm(tfm, crypto_rng_tfm(tfm));
145 }
146 
rng_get_stat(struct rng_alg * alg)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 
crypto_rng_errstat(struct rng_alg * alg,int err)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  */
crypto_rng_generate(struct crypto_rng * tfm,const u8 * src,unsigned int slen,u8 * dst,unsigned int dlen)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  */
crypto_rng_get_bytes(struct crypto_rng * tfm,u8 * rdata,unsigned int dlen)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  */
crypto_rng_seedsize(struct crypto_rng * tfm)247 static inline int crypto_rng_seedsize(struct crypto_rng *tfm)
248 {
249 	return crypto_rng_alg(tfm)->seedsize;
250 }
251 
252 #endif
253