Branch data     Line data    Source code

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