include/crypto/rng.h

   1 /*
   2  * RNG: Random Number Generator  algorithms under the crypto API
   3  *
   4  * Copyright (c) 2008 Neil Horman <nhorman@tuxdriver.com>
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU General Public License as published by the Free
   8  * Software Foundation; either version 2 of the License, or (at your option)
   9  * any later version.
  10  *
  11  */
  12
  13 #ifndef _CRYPTO_RNG_H
  14 #define _CRYPTO_RNG_H
  15
  16 #include <linux/crypto.h>
  17
  18 extern struct crypto_rng *crypto_default_rng;
  19
  20 int crypto_get_default_rng(void);
  21 void crypto_put_default_rng(void);
  22
  23 /**
  24  * DOC: Random number generator API
  25  *
  26  * The random number generator API is used with the ciphers of type
  27  * CRYPTO_ALG_TYPE_RNG (listed as type "rng" in /proc/crypto)
  28  */
  29
  30 static inline struct crypto_rng *__crypto_rng_cast(struct crypto_tfm *tfm)
  31 {
  32         return (struct crypto_rng *)tfm;
  33 }
  34
  35 /**
  36  * crypto_alloc_rng() -- allocate RNG handle
  37  * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
  38  *            message digest cipher
  39  * @type: specifies the type of the cipher
  40  * @mask: specifies the mask for the cipher
  41  *
  42  * Allocate a cipher handle for a random number generator. The returned struct
  43  * crypto_rng is the cipher handle that is required for any subsequent
  44  * API invocation for that random number generator.
  45  *
  46  * For all random number generators, this call creates a new private copy of
  47  * the random number generator that does not share a state with other
  48  * instances. The only exception is the "krng" random number generator which
  49  * is a kernel crypto API use case for the get_random_bytes() function of the
  50  * /dev/random driver.
  51  *
  52  * Return: allocated cipher handle in case of success; IS_ERR() is true in case
  53  *         of an error, PTR_ERR() returns the error code.
  54  */
  55 static inline struct crypto_rng *crypto_alloc_rng(const char *alg_name,
  56                                                   u32 type, u32 mask)
  57 {
  58         type &= ~CRYPTO_ALG_TYPE_MASK;
  59         type |= CRYPTO_ALG_TYPE_RNG;
  60         mask |= CRYPTO_ALG_TYPE_MASK;
  61
  62         return __crypto_rng_cast(crypto_alloc_base(alg_name, type, mask));
  63 }
  64
  65 static inline struct crypto_tfm *crypto_rng_tfm(struct crypto_rng *tfm)
  66 {
  67         return &tfm->base;
  68 }
  69
  70 /**
  71  * crypto_rng_alg - obtain name of RNG
  72  * @tfm: cipher handle
  73  *
  74  * Return the generic name (cra_name) of the initialized random number generator
  75  *
  76  * Return: generic name string
  77  */
  78 static inline struct rng_alg *crypto_rng_alg(struct crypto_rng *tfm)
  79 {
  80         return &crypto_rng_tfm(tfm)->__crt_alg->cra_rng;
  81 }
  82
  83 static inline struct rng_tfm *crypto_rng_crt(struct crypto_rng *tfm)
  84 {
  85         return &crypto_rng_tfm(tfm)->crt_rng;
  86 }
  87
  88 /**
  89  * crypto_free_rng() - zeroize and free RNG handle
  90  * @tfm: cipher handle to be freed
  91  */
  92 static inline void crypto_free_rng(struct crypto_rng *tfm)
  93 {
  94         crypto_free_tfm(crypto_rng_tfm(tfm));
  95 }
  96
  97 /**
  98  * crypto_rng_get_bytes() - get random number
  99  * @tfm: cipher handle
 100  * @rdata: output buffer holding the random numbers
 101  * @dlen: length of the output buffer
 102  *
 103  * This function fills the caller-allocated buffer with random numbers using the
 104  * random number generator referenced by the cipher handle.
 105  *
 106  * Return: > 0 function was successful and returns the number of generated
 107  *         bytes; < 0 if an error occurred
 108  */
 109 static inline int crypto_rng_get_bytes(struct crypto_rng *tfm,
 110                                        u8 *rdata, unsigned int dlen)
 111 {
 112         return crypto_rng_crt(tfm)->rng_gen_random(tfm, rdata, dlen);
 113 }
 114
 115 /**
 116  * crypto_rng_reset() - re-initialize the RNG
 117  * @tfm: cipher handle
 118  * @seed: seed input data
 119  * @slen: length of the seed input data
 120  *
 121  * The reset function completely re-initializes the random number generator
 122  * referenced by the cipher handle by clearing the current state. The new state
 123  * is initialized with the caller provided seed or automatically, depending
 124  * on the random number generator type (the ANSI X9.31 RNG requires
 125  * caller-provided seed, the SP800-90A DRBGs perform an automatic seeding).
 126  * The seed is provided as a parameter to this function call. The provided seed
 127  * should have the length of the seed size defined for the random number
 128  * generator as defined by crypto_rng_seedsize.
 129  *
 130  * Return: 0 if the setting of the key was successful; < 0 if an error occurred
 131  */
 132 static inline int crypto_rng_reset(struct crypto_rng *tfm,
 133                                    u8 *seed, unsigned int slen)
 134 {
 135         return crypto_rng_crt(tfm)->rng_reset(tfm, seed, slen);
 136 }
 137
 138 /**
 139  * crypto_rng_seedsize() - obtain seed size of RNG
 140  * @tfm: cipher handle
 141  *
 142  * The function returns the seed size for the random number generator
 143  * referenced by the cipher handle. This value may be zero if the random
 144  * number generator does not implement or require a reseeding. For example,
 145  * the SP800-90A DRBGs implement an automated reseeding after reaching a
 146  * pre-defined threshold.
 147  *
 148  * Return: seed size for the random number generator
 149  */
 150 static inline int crypto_rng_seedsize(struct crypto_rng *tfm)
 151 {
 152         return crypto_rng_alg(tfm)->seedsize;
 153 }
 154
 155 #endif